Package 'CircNNTSRSymmetric'

CircNNTSRSymmetric: An R Package for the statistical analysis of circular data using symmetric nonnegative trigonometric sums (NNTS) models. Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

Description

The statistical analysis of circular data using distributions based on symmetric Nonnegative Trigonometric Sums (NNTS). It includes functions to perform empirical analysis and estimate the parameters of density functions. Fernández-Durán, J.J. and Gregorio-Domínguez, M.M. (2025) <doi:10.48550/arXiv.2412.19501>.

Details

Package:	CircNNTSRSymmetric
Type:	Package
Version:	0.1.0
Date:	2025-02-02
License:	GLP (>=2)
LazyLoad:	yes

The NNTS (Non-Negative Trigonometric Sums) symmetric density around $\mu$ is defined as:

$f(\theta; M, \underline{c}, \mu)= \sum_{k=0}^M\sum_{l=0}^M \rho_k\rho_l e^{i(k-l)(\theta - \mu)}$

with $\rho_k$ real numbers for $k=0, \ldots, M$ with $\sum_{k=0}^M \rho_k^2 = \frac{1}{2\pi}$.

Equivalently, the symmetric NNTS density is:

$f(\theta; M, \underline{c}, \mu)= \frac{1}{2\pi}\sum_{k=0}^M\sum_{l=0}^M ||c_k|| ||\bar{c}_l|| e^{i(k-l)(\theta - \mu)} = \frac{1}{2\pi}\sum_{k=0}^M\sum_{l=0}^M c_{Sk} \bar{c}_{Sl} e^{i(k-l)\theta}$

. The parameters $c_{Sk}=||c_k||e^{-ik\mu}$ are the parameters of the general (non-symmetric) NNTS model.

The symmetric NNTS model is derived from the general NNTS model (Fernández-Durán, 2004 and Fernández-Durán and Gregorio-Domínguez, 2016) with norms (moduli) of the $c$ parameters equal in both models and arguments of the $c$ parameters equal to $\phi_k=-k\mu$ for $k=1,2, \ldots, M$.

Author(s)

Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez

Maintainer: Maria Mercedes Gregorio Dominguez <[email protected]>

References

Fernández-Durán, J.J. (2004). Circular Distributions Based on Nonnegative Trigonometric Sums. Biometrics, 60, pp. 499-503.

Fernández-Durán, J.J. and Gregorio-Domínguez, M.M. (2016). CircNNTSR: An R Package for the Statistical Analysis of Circular, Multivariate Circular, and Spherical Data Using Nonnegative Trigonometric Sums. Journal of Statistical Software, 70(6), 1-19. doi:10.18637/jss.v070.i06

Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

---

Parameter estimation for NNTS distributions with gradient stop

Description

Computes the maximum likelihood estimates of the NNTS parameters of an NNTS distribution, using a Newton algorithm on the hypersphere and considering a maximum number of iterations determined by a constraint in terms of the norm of the gradient

Usage

nntsmanifoldnewtonestimationgradientstop(data, M = 0, iter = 1000,
initialpoint = FALSE, cinitial,gradientstop=1e-10)

Arguments

data	Vector of angles in radians
M	Number of components in the NNTS symmetric density
iter	Number of iterations
initialpoint	TRUE if an initial point for the optimization algorithm for the general (asymmetric) NNTS density will be used
cinitial	Vector of size M+1. The first element is real and the next M elements are complex (values for $c_0$ and $c_1, ...,c_M$). The sum of the squared moduli of the parameters must be equal to 1/(2*pi). This is the vector of parameters for the general (asymmetric) NNTS density

gradientstop

gradientstop

The minimum value of the norm of the gradient to stop the Newton algorithm on the hypersphere

Value

cestimates	Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter's estimators of the NNTS model
loglik	Optimum log-likelihood value for the NNTS model
AIC	Value of Akaike's Information Criterion
BIC	Value of Bayesian Information Criterion
gradnormerror	Gradient error after the last iteration

Author(s)

Juan Jose Fernandez-Duran y Maria Mercedes Gregorio-Dominguez

References

Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

Examples

data(Turtles_radians)
resturtles<-nntsmanifoldnewtonestimationgradientstop(data=Turtles_radians, M = 2,
iter=1000,gradientstop=1e-10)
resturtles

---

Parameter estimation for NNTS symmetric distributions

Description

Computes the maximum likelihood estimates of the NNTS parameters of an NNTS symmetric distribution, using a Newton algorithm on the hypersphere

Usage

nntsmanifoldnewtonestimationsymmetry(data, M = 0,iter=1000,gradientstop=1e-10,
pevalmu=1000,initialpoint=FALSE,cinitial)

Arguments

data	Vector of angles in radians
M	Number of components in the NNTS symmetric density
iter	Number of iterations
gradientstop	The minimum value of the norm of the gradient to stop the Newton algorithm on the hypersphere
pevalmu	Number of equidistant points in the interval 0 to 2pi to search for the maxima of the angle of symmetry
initialpoint	TRUE if an initial point for the optimization algorithm for the general (asymmetric) NNTS density will be used
cinitial	Vector of size M+1. The first element is real and the next M elements are complex (values for $c_0$ and $c_1, ...,c_M$). The sum of the squared moduli of the parameters must be equal to 1/(2*pi). This is the vector of parameters for the general (asymmetric) NNTS density

Value

cestimatessym	Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter's estimators of the symmetric NNTS model
mu	Estimate of the angle of symmetry of the NNTS symmetric model
logliksym	Optimum log-likelihood value for the NNTS symmetric model
AICsym	Value of Akaike's Information Criterion for the NNTS symmetric model
BICsym	Value of Bayesian Information Criterion for the NNTS symmetric model
gradnormerrorsym	Gradient error after the last iteration for the estimation of the parameters of the NNTS symmetric model
cestimatesnonsym	Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter's estimators of the symmetric NNTS model
logliknonsym	Optimum log-likelihood value for the general (non-symmetric) NNTS model
AICnonsym	Value of Akaike's Information Criterion for the general (non-symmetric) NNTS model
BICnonsym	Value of Bayesian Information Criterion for the general (non-symmetric) NNTS model
gradnormerrornonsym	Gradient error after the last iteration for the estimation of the parameters of the general (non-symmetric) NNTS model
loglikratioforsym	Value of the likelihood ratio test statistic for symmetry
loglikratioforsympvalue	Value of the asymptotic chi squared p-value of the likelihood ratio test statistic for symmetry

Author(s)

Juan Jose Fernandez-Duran y Maria Mercedes Gregorio-Dominguez

References

Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

Examples

data(Turtles_radians)
resturtlessymm<-nntsmanifoldnewtonestimationsymmetry(data=Turtles_radians, M = 2, iter =1000,
gradientstop=1e-10,pevalmu=1000)
resturtlessymm
hist(Turtles_radians,breaks=seq(0,2*pi,2*pi/13),xlab="Direction (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,.8),axes=FALSE)
nntsplot(resturtlessymm$cestimatessym[,2],2,add=TRUE)
nntsplot(resturtlessymm$cestimatesnonsym[,2],2,add=TRUE,lty=2)
axis(1,at=c(0,pi/2,pi,6*(pi/4),2*pi),labels=c("0",expression(pi/2),expression(pi),
expression(3*pi/2),expression(2*pi)),las=1)
axis(2)

data(Ants_radians)
resantssymm<-nntsmanifoldnewtonestimationsymmetry(data=Ants_radians, M = 4, iter =1000,
gradientstop=1e-10,pevalmu=1000)
resantssymm
hist(Ants_radians,breaks=seq(0,2*pi,2*pi/13),xlab="Direction (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,.8),axes=FALSE)
nntsplot(resantssymm$cestimatessym[,2],4,add=TRUE)
nntsplot(resantssymm$cestimatesnonsym[,2],4,add=TRUE,lty=2)
axis(1,at=c(0,pi/2,pi,6*(pi/4),2*pi),labels=c("0",expression(pi/2),expression(pi),
expression(3*pi/2),expression(2*pi)),las=1)
axis(2)

---

Parameter estimation for NNTS symmetric distributions

Description

Computes the maximum likelihood estimates of the NNTS parameters of an NNTS symmetric distribution with known angle of symmetry mu, using a Newton algorithm on the hypersphere

Usage

nntsmanifoldnewtonestimationsymmetryknownsymmetryanglemu(data, mu, M = 0,
iter=1000,gradientstop=1e-10,initialpoint=FALSE,cinitial)

Arguments

data	Vector of angles in radians
mu	Known angle of symmetry of the NNTS symmetric model
M	Number of components in the NNTS symmetric density
iter	Number of iterations
gradientstop	The minimum value of the norm of the gradient to stop the Newton algorithm on the hypersphere
initialpoint	TRUE if an initial point for the optimization algorithm for the general (asymmetric) NNTS density will be used
cinitial	Vector of size M+1. The first element is real and the next M elements are complex (values for $c_0$ and $c_1, ...,c_M$). The sum of the squared moduli of the parameters must be equal to 1/(2*pi). This is the vector of parameters for the general (asymmetric) NNTS density

Value

cestimatessym	Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter's estimators of the symmetric NNTS model
mu	Known angle of symmetry of the NNTS symmetric model
logliksym	Optimum log-likelihood value for the NNTS symmetric model
AICsym	Value of Akaike's Information Criterion for the NNTS symmetric model
BICsym	Value of Bayesian Information Criterion for the NNTS symmetric model
gradnormerrorsym	Gradient error after the last iteration for the estimation of the parameters of the NNTS symmetric model
cestimatesnonsym	Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter's estimators of the symmetric NNTS model
logliknonsym	Optimum log-likelihood value for the general (non-symmetric) NNTS model
AICnonsym	Value of Akaike's Information Criterion for the general (non-symmetric) NNTS model
BICnonsym	Value of Bayesian Information Criterion for the general (non-symmetric) NNTS model
gradnormerrornonsym	Gradient error after the last iteration for the estimation of the parameters of the general (non-symmetric) NNTS model
loglikratioforsym	Value of the likelihood ratio test statistic for symmetry
loglikratioforsympvalue	Value of the asymptotic chi squared p-value of the likelihood ratio test statistic for symmetry

Author(s)

Juan Jose Fernandez-Duran y Maria Mercedes Gregorio-Dominguez

References

Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

Examples

data(Ants_radians)
resantssymmknownmu<-nntsmanifoldnewtonestimationsymmetryknownsymmetryanglemu(data=Ants_radians,
mu=pi, M = 4, iter =1000,gradientstop=1e-10)
resantssymmknownmu
hist(Ants_radians,breaks=seq(0,2*pi,2*pi/13),xlab="Direction (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,.8),axes=FALSE)
nntsplot(resantssymmknownmu$cestimatessym[,2],4,add=TRUE)
nntsplot(resantssymmknownmu$cestimatesnonsym[,2],4,add=TRUE,lty=2)
axis(1,at=c(0,pi/2,pi,6*(pi/4),2*pi),labels=c("0",expression(pi/2),expression(pi),
expression(3*pi/2),expression(2*pi)),las=1)
axis(2)

---

Moments of an NNTS density

Description

Computes the first moment, second moment, mean direction, dispersion, circular varance, coefficient of asymmetry and kurtosis from the given parameters of an NNTS density.

Usage

nntsmeasureslocationdispersion(cestimates,M=0)

Arguments

cestimates	Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter vecto (or c estimates) of the NNTS model
M	Number of components in the NNTS density

Value

firstmoment	Value of the first trigonometric moment
secondmoment	Value of the second trigonometric moment
meandirection	Value of the mean direction
dispersion	Value of the dispersion
circularvariance	Value of the circular variance
asymmetrycoefficient	Value of the coefficient of asymmetry
kurtosis	Value of the kurtosis

Author(s)

Juan Jose Fernandez-Duran y Maria Mercedes Gregorio-Dominguez

References

Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

Examples

data(Ants_radians)
resants<-nntsmanifoldnewtonestimationgradientstop(data=Ants_radians, M = 2, iter=1000,
gradientstop=1e-10)
resants
nntsmeasureslocationdispersion(resants$cestimates,M=2)

---

Calculation of the Sample Skewness

Description

Computes the skewness for a sample of angles

Usage

samplecircularskewness(data)

Arguments

data	Vector of angles in radians

Value

Value

Value of the sample skewness

Author(s)

Juan Jose Fernandez-Duran y Maria Mercedes Gregorio-Dominguez

References

Fernández-Durán, J.J., Gregorio-Domínguez, M.M. (2025). Multimodal Symmetric Circular Distributions Based on Nonnegative Trigonometric Sums and a Likelihood Ratio Test for Reflective Symmetry, arXiv:2412.19501 [stat.ME] (available at https://arxiv.org/abs/2412.19501)

Examples

data(Ants_radians)
samplecircularskewness(data=Ants_radians)

# non-symmetric
cp3a<-c(0.27672975+0.00000000i,-0.04547516-0.00298663i,-0.18680096-0.10457410i,
0.03339396-0.18317526i)
cp3a<-cp3a/sqrt(sum(Mod(cp3a)^2))
cp3a<-(1/sqrt(2*pi))*cp3a

cp3annts<-cbind(c(0,1,2,3),cp3a)
nntsmeasureslocationdispersion(cp3annts,M=3)
set.seed(1234567890)
datasim3a<-nntssimulation(1000,cp3a,3)$simulations
samplecircularskewness(datasim3a)

#symmetric
cp3b<-Mod(cp3a)
cp3bnnts<-cbind(c(0,1,2,3),cp3b)
nntsmeasureslocationdispersion(cp3bnnts,M=3)
set.seed(1234567890)
datasim3b<-nntssimulation(1000,cp3b,3)$simulations
samplecircularskewness(datasim3b)

#symmetric bis
cp3c<-c(0.3131489,0.1421822,0.1266749,0.1575766)
cp3c<-cp3c/sqrt(sum(Mod(cp3c)^2))
cp3c<-(1/sqrt(2*pi))*cp3c
cp3c<-cp3c*exp((0:3)*1i*(-pi))
cp3cnnts<-cbind(c(0,1,2,3),cp3c)
nntsmeasureslocationdispersion(cp3cnnts,M=3)
set.seed(1234567890)
datasim3c<-nntssimulation(1000,cp3c,3)$simulations
samplecircularskewness(datasim3c)

---