| Type: | Package |
| Title: | Axial Data using NNTS Models |
| Version: | 0.1.0 |
| Description: | Statistical analysis of axial using distributions Nonnegative Trigonometric Sums (NNTS). The package includes functions for calculation of densities and distributions, for the estimation of parameters, and more. Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025), ”Multimodal distributions for circular axial data", <doi:10.48550/arXiv.2504.04681>. |
| Depends: | R (≥ 4.3.0), stats, graphics |
| Imports: | psychTools, CircNNTSR |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.2.3 |
| NeedsCompilation: | no |
| Packaged: | 2025-04-20 05:47:42 UTC; mercedesgregorio |
| Author: | Juan Jose Fernandez-Duran [aut], Maria Mercedes Gregorio-Dominguez [aut, cre] |
| Maintainer: | Maria Mercedes Gregorio-Dominguez <mercedes@itam.mx> |
| Repository: | CRAN |
| Date/Publication: | 2025-04-23 10:20:05 UTC |
Dataset B13 from Fisher
Description
Dataset B13 from Fisher (1993) contains measurements of termite mound orientations for the species Amitermes laurensis, collected from 14 sites on the Cape York Peninsula, North Queensland, Australia. Experiment reported in Spain et al. (1983)
Usage
Datab13fisher
Format
A data frame with 906 rows and 4 variables:
- site
Site number
- latitude
Latitude of the site
- longitude
Longitude of the site
- orientation
Orientation of the mound in degrees
References
Fisher, N.I. (1993) Statistical analysis of circular data. Cambridge University Press. Spain, A.V., Okello-Oloya, T. and John, R.D. (1983) Orientation of the termitaria of two species of Amitermes (Isoptera:Termitinae) from Northern Queensland. Aust. J. Zoo. 31, 167-177.
Examples
data(Datab13fisher)
Dataset B22 from Fisher
Description
Dataset B22 from Fisher (1993) includes 63 median directions of face cleats measured at the Wallsend Borehole Colliery in New South Wales, Australia. The median directions were measured at intervals of 20 meters along the coal seam. Fisher (1993) from Shepherd and Fisher (1981, 1982)
Usage
Datab22fisher
Format
A data frame with 63 rows and 1 variable:
- orientations
Orientation of the mound in degrees
References
Fisher, N.I. (1993) Statistical analysis of circular data. Cambridge University Press. Shepherd, J. and Fisher, N.I. (1981) A rapid method of mapping fracture trends in collieries. Aust. Coal Miner August, 24-33. Shepherd, J. and Fisher, N.I. (1982) A rapid method of mapping fracture trends in collieries. Trans. Soc. Min. Eng. AIME 270, 1931-2.
Examples
data(Datab22fisher)
Dataset B2 from Fisher
Description
Dataset B2 from Fisher (1993) contains measurements of the long-axis orientations of 133 feldspar laths in basalt. Fisher (1993) from Smith (1988)
Usage
Datab2fisher
Format
A data frame with 133 rows and 1 variable:
- orientations
Orientation angle in degrees
References
Fisher, N.I. (1993) Statistical analysis of circular data. Cambridge University Press. Smith, N.M. (1988) Reconstruction of the Tertiary drainage systems of the Inverell region. Unpublished B.Sc.(Hons.) thesis, Department of Geography, University of Sydney, Australia
Examples
data(Datab2fisher)
Dataset B5 from Fisher
Description
Dataset B5 from Fisher (1993) contains orientations of 60 feldspar laths in basalt. Fisher (1993) from Smith (1988)
Usage
Datab5fisher
Format
A data frame with 60 rows and 1 variable:
- orientations
Orientation angle in degrees
References
Fisher, N.I. (1993) Statistical analysis of circular data. Cambridge University Press. Smith, N.M. (1988) Reconstruction of the Tertiary drainage systems of the Inverell region. Unpublished B.Sc.(Hons.) thesis, Departmen of Geography, University of Sydney, Australia
Examples
data(Datab5fisher)
Leaf angles
Description
The dataset from Pisek and Adamson (2020) contains leaf inclination angle measurements for 11 species of gum trees (genus Eucalyptus) observed at the Huntington Library, Art Collections, and Botanical Gardens in Pasadena, California (latitude 34.125, longitude -118.114, altitude 207 m.a.s.l.)
Usage
Leafangles
Format
A data frame with 999 rows and 3 variable:
- idnumber
Observation id
- idtype
Id number of the 11 species of gum trees \ 1 : balladoniensis \ 2 : calycogona \ 3 : erythronema \ 4 : grossa \ 5 : guilfoylei \ 6 : lansdowneana \ 7 : macrandra \ 8 : oleosa \ 9 : robusta \ 10 : shirleyi \ 11 : stoateri
- leafangle
Leaf inclination angle in degrees
References
Pisek, J. and Adamson, K. (2020). Dataset of leaf inclination angles for 71 different Eucalyptus species. Data in Brief, 33, 106391
Examples
data(Leafangles)
NNTS density function for axial data
Description
Density function for the NNTS axial model
Usage
axialnntsdensity(data, cpars = 1/sqrt(pi), M = 0)
Arguments
data |
Vector of size R with axial angles in radians |
cpars |
Vector of complex numbers of dimension M+1. The first element is a real and positive number. The sum of the squared moduli of the c parameters must be equal to 1/pi |
M |
Number of components in the NNTS axial model |
Value
res |
The function returns a 1 by R matrix with the density function evaluated at each element of the vector data of size R |
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
References
Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025). Multimodal distributions for circular axial data. arXiv:2504.04681 [stat.ME] (available at https://arxiv.org/abs/2504.04681)
Examples
ccoef<-axialnntsrandominitial(3)
axialnntsdensity(1,ccoef,3)
axialnntsdensity(pi/2,ccoef,3)
axialnntsdensity(c(1,pi/2),ccoef,3)
Axial NNTS log-likelihood function
Description
Computes the log-likelihood function with NNTS density for axial data
Usage
axialnntsloglik(data, cpars = 1/sqrt(pi), M = 0)
Arguments
data |
Vector of size R with observed axial angles in radians |
cpars |
Vector of complex numbers of dimension M+1. The first element is a real and positive number. The sum of the squared moduli of the c parameters must be equal to 1/pi |
M |
Number of components in the NNTS axial model |
Value
y |
The function returns a 1 by R matrix with the value of the log-likelihood function for each element of the data vector of size R |
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
References
Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025). Multimodal distributions for circular axial data. arXiv:2504.04681 [stat.ME] (available at https://arxiv.org/abs/2504.04681)
Examples
a<-c(runif(10,3*pi/4,pi-0.00000001),runif(10,pi/4,pi/2-0.00000001))
set.seed(12345)
ccoef<-axialnntsrandominitial(2)
axialnntsloglik(a,ccoef,2)
Parameter estimation for axial NNTS distributions with gradient stop
Description
Computes the maximum likelihood estimates of the parameters of an axial 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
axialnntsmanifoldnewtonestimationgradientstop(data, M = 0, iter = 1000,
initialpoint = FALSE, cinitial,gradientstop=1e-10)
Arguments
data |
Vector of axial angles in radians |
M |
Number of components in the NNTS axial model |
iter |
Number of iterations |
initialpoint |
TRUE if an initial point for the optimization algorithm for the axial 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/pi. |
gradientstop |
The minimum value of the norm of the gradient to stop the Newton algorithm on the hypersphere |
Value
A list with 5 elements:
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 axial model |
loglik |
Optimum log-likelihood value for the NNTS axial 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 and Maria Mercedes Gregorio-Dominguez
References
Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025). Multimodal distributions for circular axial data. arXiv:2504.04681 [stat.ME] (available at https://arxiv.org/abs/2504.04681)
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(Datab2fisher)
feldsparsangles<-Datab2fisher$orientations
feldsparsangles<-feldsparsangles*(pi/180)
resfeldspars<-axialnntsmanifoldnewtonestimationgradientstop(data=feldsparsangles,
M = 2,iter=1000,gradientstop=1e-10)
resfeldspars
Parameter estimation for axial NNTS distributions with known location angle gradient stop
Description
Computes the maximum likelihood estimates of the parameters of an axial symmetric NNTS distribution with known location angle, 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
axialnntsmanifoldnewtonestimationgradientstopknownmu(data, muknown=0, M = 0, iter = 1000,
initialpoint = FALSE, cinitial,gradientstop=1e-10)
Arguments
data |
Vector of axial angles in radians |
muknown |
Value of the known location angle |
M |
Number of components in the NNTS axial model |
iter |
Number of iterations |
initialpoint |
TRUE if an initial point for the optimization algorithm for the axial 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/pi. |
gradientstop |
The minimum value of the norm of the gradient to stop the Newton algorithm on the hypersphere |
Value
A list with 13 elements:
cestimatesmuknown |
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 axial model with known location angle |
muknown |
Known value of the location angle of the NNTS axial model |
loglikmuknown |
Optimum log-likelihood value for the NNTS axial model with known location angle |
AICmuknown |
Value of Akaike's Information Criterion for the NNTS axial model with known location angle |
BICmuknown |
Value of Bayesian Information Criterion for the NNTS axial model with known location angle |
gradnormerrormuknown |
Gradient error after the last iteration for the estimation of the parameters of the NNTS axial model with known location angle |
cestimatesmuunknown |
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 axial model with unknown location angle |
loglikmuunknown |
Optimum log-likelihood value for the general NNTS axial model with unknown location angle |
AICmuunknown |
Value of Akaike's Information Criterion for the general NNTS axial model with unknown location angle |
BICmuunknown |
Value of Bayesian Information Criterion for the general NNTS axial model with unknown location angle |
gradnormerrormuunknown |
Gradient error after the last iteration for the estimation of the parameters of the general NNTS axial model with unknown location angle |
loglikratioformuknown |
Value of the likelihood ratio test statistic for known location angle |
loglikratioformuknownpvalue |
Value of the asymptotic chi squared p-value of the likelihood ratio test statistic for known location angle |
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
References
Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025). Multimodal distributions for circular axial data. arXiv:2504.04681 [stat.ME] (available at https://arxiv.org/abs/2504.04681)
Examples
data(Datab2fisher)
feldsparsangles<-Datab2fisher
feldsparsangles<-feldsparsangles$orientations*(pi/180)
resfeldsparknownangle<-axialnntsmanifoldnewtonestimationgradientstopknownmu(data=feldsparsangles,
muknown=pi/2, M = 2, iter =1000, gradientstop=1e-10)
resfeldsparknownangle
hist(feldsparsangles,breaks=seq(0,pi,pi/7),xlab="Orientations (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,.8),axes=FALSE)
axialnntsplot(resfeldsparknownangle$cestimatesmuunknown[,2],2,add=TRUE)
axialnntsplot(resfeldsparknownangle$cestimatesmuknown[,2],2,add=TRUE,lty=2)
axis(1,at=c(0,pi/2,pi),labels=c("0",expression(pi/2),expression(pi)),las=1)
axis(2)
Parameter estimation for axial symmetric NNTS distributions with known location angle gradient stop
Description
Computes the maximum likelihood estimates of the parameters of an axial symmetric NNTS distribution with known location angle, 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
axialnntsmanifoldnewtonestimationgradientstopknownmusymmetric(data, muknown=0, M = 0,
iter = 1000, initialpoint = FALSE, cinitial,gradientstop=1e-10)
Arguments
data |
Vector of axial angles in radians |
muknown |
Value of the known location angle |
M |
Number of components in the NNTS axial model |
iter |
Number of iterations |
initialpoint |
TRUE if an initial point for the optimization algorithm for the axial 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/pi. This is the vector of parameters for the general (asymmetric) NNTS axial density |
gradientstop |
The minimum value of the norm of the gradient to stop the Newton algorithm on the hypersphere |
Value
A list with 13 elements:
cestimatesmuknown |
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 axial model with known location angle |
muknown |
Known value of the location angle of the symmetric NNTS axial model |
loglikmuknown |
Optimum log-likelihood value for the symmetric NNTS axial model with known location angle |
AICmuknown |
Value of Akaike's Information Criterion for the symmetric NNTS axial model with known location angle |
BICmuknown |
Value of Bayesian Information Criterion for the symmetric NNTS axial model with known location angle |
gradnormerrormuknown |
Gradient error after the last iteration for the estimation of the parameters of the symmetric NNTS axial model with known location angle |
cestimatesmuunknown |
Matrix of (M+1)x2. The first column is the parameter numbers, and the second column is the c parameter's estimators of the general (non-symmetric) NNTS axial model with unknown location angle |
loglikmuunknown |
Optimum log-likelihood value for the general (non-symmetric) NNTS axial model with unknown location angle |
AICmuunknown |
Value of Akaike's Information Criterion for the general (non-symmetric) NNTS axial model with unknown location angle |
BICmuunknown |
Value of Bayesian Information Criterion for the general (non-symmetric) NNTS axial model with unknown location angle |
gradnormerrormuunknown |
Gradient error after the last iteration for the estimation of the parameters of the general (non-symmetric) NNTS axial model with unknown location angle |
loglikratioformuknown |
Value of the likelihood ratio test statistic for known location angle |
loglikratioformuknownpvalue |
Value of the asymptotic chi squared p-value of the likelihood ratio test statistic for known location angle |
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
References
Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025). Multimodal distributions for circular axial data. arXiv:2504.04681 [stat.ME] (available at https://arxiv.org/abs/2504.04681)
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(Datab2fisher)
feldsparsangles<-Datab2fisher
feldsparsangles<-feldsparsangles$orientations*(pi/180)
resfeldsparknownanglesymmetric<-axialnntsmanifoldnewtonestimationgradientstopknownmusymmetric(
data=feldsparsangles, muknown=pi/3, M = 3, iter =1000, gradientstop=1e-10)
resfeldsparknownanglesymmetric
hist(feldsparsangles,breaks=seq(0,pi,pi/7),xlab="Orientations (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,.8),axes=FALSE)
axialnntsplot(resfeldsparknownanglesymmetric$cestimatesmuunknown[,2],3,add=TRUE)
axialnntsplot(resfeldsparknownanglesymmetric$cestimatesmuknown[,2],3,add=TRUE,lty=2)
axis(1,at=c(0,pi/2,pi),labels=c("0",expression(pi/2),expression(pi)),las=1)
axis(2)
Parameter estimation for axial symmetric NNTS distributions with gradient stop
Description
Computes the maximum likelihood estimates of the parameters of an axial symmetric 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
axialnntsmanifoldnewtonestimationgradientstopsymmetric(data, M = 0, iter = 1000,
gradientstop = 1e-10, pevalmu = 1000, initialpoint = FALSE, cinitial)
Arguments
data |
Vector of axial angles in radians |
M |
Number of components in the NNTS axial model |
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 pi to search for the maxima of the angle of symmetry |
initialpoint |
TRUE if an initial point for the optimization algorithm for the axial 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/pi. |
Value
A list with 13 elements:
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 axial model |
mu |
Estimate of the angle of symmetry of the NNTS symmetric axial model |
logliksym |
Optimum log-likelihood value for the NNTS symmetric axial model |
AICsym |
Value of Akaike's Information Criterion for the NNTS symmetric axial model |
BICsym |
Value of Bayesian Information Criterion for the NNTS symmetric axial model |
gradnormerrorsym |
Gradient error after the last iteration for the estimation of the parameters of the NNTS symmetric axial 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 general (non-symmetric) NNTS axial model |
logliknonsym |
Optimum log-likelihood value for the general (non-symmetric) NNTS axial model |
AICnonsym |
Value of Akaike's Information Criterion for the general (non-symmetric) NNTS axial model |
BICnonsym |
Value of Bayesian Information Criterion for the general (non-symmetric) NNTS axial model |
gradnormerrornonsym |
Gradient error after the last iteration for the estimation of the parameters of the general (non-symmetric) NNTS axial 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 and Maria Mercedes Gregorio-Dominguez
References
Fernandez-Duran, J.J. and Gregorio-Dominguez, M.M. (2025). Multimodal distributions for circular axial data. arXiv:2504.04681 [stat.ME] (available at https://arxiv.org/abs/2504.04681)
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(Datab2fisher)
feldsparsangles<-Datab2fisher
feldsparsangles<-feldsparsangles$orientations*(pi/180)
resfeldsparsymm<-axialnntsmanifoldnewtonestimationgradientstopsymmetric(data=feldsparsangles,
M = 2, iter =1000, gradientstop=1e-10,pevalmu=1000)
resfeldsparsymm
hist(feldsparsangles,breaks=seq(0,pi,pi/7),xlab="Orientations (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,.8),axes=FALSE)
axialnntsplot(resfeldsparsymm$cestimatessym[,2],2,add=TRUE)
axialnntsplot(resfeldsparsymm$cestimatesnonsym[,2],2,add=TRUE,lty=2)
axis(1,at=c(0,pi/2,pi),labels=c("0",expression(pi/2),expression(pi)),las=1)
axis(2)
Plots the NNTS axial density
Description
Plots the NNTS axial density
Usage
axialnntsplot(cpars = 1/sqrt(pi), M = 0, ...)
Arguments
cpars |
Vector of complex numbers of dimension M+1. The first element is a real and positive number. The sum of the SQUARED moduli of the c parameters must be equal to 1/pi |
M |
Number of components in the NNTS axial model |
... |
Arguments passed to the function curve |
Value
No return value
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
Examples
set.seed(1234567)
cp<-axialnntsrandominitial(3)
axialnntsplot(cp,3)
Initial random point
Description
This function generates a random point on the surface of the (M+1)-dimensional hypersphere with radius 1/sqrt(pi) which corresponds to a random parameter vector of the NNTS axial density
Usage
axialnntsrandominitial(M=1)
Arguments
M |
Number of components in the NNTS axial model |
Value
res |
A complex vector of size M+1 which can be used as a valid initial point for the estimation functions |
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
Examples
set.seed(12345)
axialnntsrandominitial(3)
axialnntsrandominitial(7)
NNTS axial density simulation function
Description
Simulation for the density function for the NNTS axial model
Usage
axialnntssimulation(nsim=1, cpars = 1/pi, M = 0)
Arguments
nsim |
Number of simulations |
cpars |
Parameters of the model. A vector of complex numbers of dimension M+1. The sum of the squared moduli of the c parameters must be equal to 1/pi |
M |
Number of components in the NNTS axial model |
Value
A list with two components:
simulations |
The function generates a vector with nsim simulated random values from the NNTS axial density function |
conteo |
Number of uniform random numbers used to obtain the nsim simulations by the acceptance-rejection simulation method |
Author(s)
Juan Jose Fernandez-Duran and Maria Mercedes Gregorio-Dominguez
Examples
set.seed(1234567)
ccoef<-axialnntsrandominitial(M=4)
data<-axialnntssimulation(100,ccoef,M=4)$simulations
hist(data,breaks=seq(0,pi,pi/7),xlab="Orientations (radians)",freq=FALSE,
ylab="",main="",ylim=c(0,1))
axialnntsplot(ccoef,M=4,add=TRUE)