cardioid: Cardioid Distribution Family Function

In VGAM: Vector Generalized Linear and Additive Models

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

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

Card, extlogitlink, vonmises.

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)

VGAM documentation built on Dec. 4, 2025, 1:07 a.m.