| cardioid {VGAM} | R Documentation |
Cardioid Distribution Family Function
Description
Estimates the two parameters of the cardioid distribution by maximum likelihood estimation.
Usage
cardioid(lmu = "extlogitlink(min = 0, max = 2*pi)",
lrho = "extlogitlink(min = -0.5, max = 0.5)",
imu = NULL, irho = NULL,
gmu = ppoints(16) * 2 * pi,
grho = ppoints(16) - 0.5, zero = NULL)
cardioid2(lmu = "extlogitlink(min = 0, max = 2*pi)",
lrho2 = "logitlink", imu = NULL, irho2 = NULL,
gmu = ppoints(8) * 2 * pi,
grho2 = ppoints(8), zero = "rho2")
Arguments
lmu, lrho, lrho2 |
Parameter link functions applied to the |
gmu, grho, grho2 |
Grid of initial values.
Because of a possible multimodal likelihood,
it is a good idea to try a fine rectangular grid
of values.
The default may be too fine and made coarser when
|
imu, irho, irho2 |
Initial values.
A |
zero |
See |
Details
The two-parameter cardioid distribution has a density that can be written as
f(y;\mu,\rho) = \frac{1}{2\pi}
\left[1 + 2\, \rho \cos(y - \mu) \right]
where 0 \leq y < 2\pi,
and 0 \leq \mu < 2\pi
is the location parameter (of the mode), and
-0.5 < \rho < 0.5 is
the concentration parameter.
The default link functions enforce the range
constraints of the parameters.
For positive \rho the distribution is unimodal and
symmetric about \mu.
The mean of Y (which make up the fitted values) is
\pi + (\rho/\pi) ((2 \pi-\mu) \sin(2 \pi-\mu) +
\cos(2 \pi-\mu) - \mu \sin(\mu) - \cos(\mu)).
Pewsey (2025) considers another parameterization:
since
f(y; \mu, -\rho) = f(y; \mu+\pi, \rho)
then \rho could be restricted to
[0, 0.5].
This suggests a variant parameterization:
\rho_2 = 2\rho
which lies in the unit interval and therefore
logitlink,
probitlink,
clogloglink, etc. are options.
This is implemented in
dcard2, pcard2,
qcard2, rcard2,
cardioid2 and is recommended
above the original parameterization. Another
reason this is better is that it
ensure identifiability because
dcard(theta, mu, -rho) is the same as
dcard(theta, mu + pi, rho).
Value
An object of class "vglmff" (see
vglmff-class).
The object is used by modelling
functions such as vglm,
rrvglm
and vgam.
Warning
Numerically, this distribution can be difficult
to fit because
of a log-likelihood having multiple maximums.
Indeed, Fisher scoring may not be suitable
for estimation, especially for n < 10.
Often the (global) solution occurs when
\rho
is on or near the boundary of the parameter space.
The user is therefore encouraged to try different
starting values, i.e.,
make use of imu and irho,
even though gmu and
grho/grho2 should suffice.
Note
Fisher scoring using simulation is no longer used. Instead, the EIM has been derived (Pewsey, 2025).
Author(s)
T. W. Yee
References
Pewsey, A. (2025). On Jeffreys's cardioid distribution. Computational Statistics and Data Analysis, 82, in press.
Jammalamadaka, S. R. and SenGupta, A. (2001). Topics in Circular Statistics, Singapore: World Scientific.
See Also
CircStats, circular and Directional currently have a lot more R functions for circular data than VGAM.
Examples
## Not run:
cdata <- data.frame(y = rcard2(1000, mu = 4, rho2 = 0.5))
fit <- vglm(y ~ 1, cardioid2, data = cdata, trace = TRUE)
coef(fit, matrix = TRUE)
Coef(fit)
c(with(cdata, mean(y)), head(fitted(fit), 1))
summary(fit)
## End(Not run)