Cardioid Distribution Family Function

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 $\mu$ and $\rho$ and $\rho_2$ parameters, respectively. See Links for more choices.

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 $n$ is very large. Pewsey (2025) recommends that MLE be used for $n > 10$ so a warning may occur if $n$ is too small. See CommonVGAMffArguments for more information.

imu, irho, irho2

Initial values. A NULL means an initial value is chosen internally. See CommonVGAMffArguments for information.

zero

See CommonVGAMffArguments for information.

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.

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.

Author

T. W. Yee

Note

Fisher scoring using simulation is no longer used. Instead, the EIM has been derived (Pewsey, 2025).

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.

Examples

if (FALSE) { # \dontrun{
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)
} # }