cardioid: 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")

Value

An object of class "vglmff" (see

vglmff-class). The object is used by modelling functions such as vglm,

rrvglm

and vgam.

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.

Author

T. W. Yee

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.

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).

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.

Examples

Run this code

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

Run the code above in your browser using DataLab