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

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 <mercedes@itam.mx>

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

gradientstop

Value

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

Value

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

Value

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

Value

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

Value

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)