Package 'HDiR'

Title: Directional Highest Density Regions
Description: We provide an R tool for computation and nonparametric plug-in estimation of Highest Density Regions (HDRs) and general level sets in the directional setting. Concretely, circular and spherical HDRs can be reconstructed from a data sample following Saavedra-Nieves and Crujeiras (2021) <doi:10.1007/s11634-021-00457-4>. This library also contains two real datasets in the circular and spherical settings. The first one concerns a problem from animal orientation studies and the second one is related to earthquakes occurrences.
Authors: Paula Saavedra-Nieves [aut, cre], Rosa M Crujeiras [aut], Andrés Prieto [ctb], Felicita Scapini [dtc]
Maintainer: Paula Saavedra-Nieves <[email protected]>
License: GPL-2
Version: 1.1.3
Built: 2024-11-05 06:30:22 UTC
Source: CRAN

Help Index


Circular smoothing parameter for HDRs estimation

Description

This function provides the specific smoothing parameter for circular HDRs estimation proposed in Saavedra-Nieves and Crujeiras (2021).

Usage

circ.boot.bw(sample, bw = bw.CV(circular(sample),
upper=100), tau = 0.5, B = 50, upper = 1.5 * bw)

Arguments

sample

Numeric vector of angles in radians.

bw

Pilot soothing parameter to be used. Following Oliveira et al. (2014), the value of the smoothing parameter can be chosen by using the functions bw.rt, bw.CV, bw.pi or bw.boot. Default bw=bw.CV providing a cross-validation bandwidth.

tau

Numeric probability. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverage required for HDR. Default tau=0.5.

B

Integer value indicating the number of bootstrap resamples. Default B=50.

upper

Numerical upper value for bounding the optimization procedure. Default 1.5bw.

Details

Saavedra-Nieves and Crujeiras (2021) propose a specific smoothing parameter for HDRs estimation based on the minimization of the Hausdorff distance between the boundaries of the theoretical HDR and the plug-in estimator.

Value

A numeric value corresponding to the selected smoothing parameter.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# HDR selector from a sample of size 500 of model 5 in NPCirc
library(NPCirc)
set.seed(1)
sample<- rcircmix(500, model=5)
circ.boot.bw(sample,tau=0.4,B=2)

Euclidean and Hausdorff distances between two sets of points on the unit circle

Description

This function determines the Euclidean and Hausdorff distances between two sets of points on the unit circle.

Usage

circ.distances(x, y)

Arguments

x

Numeric vector of angles in radians determining a set of points on the unit circle.

y

Numeric vector of angles in radians determining a set of points on the unit circle.

Details

If x and y corresponds to two HDRs boundaries, this function returns the Euclidean and Hausdorff distances between the HDRs frontiers, but the function computes the Euclidean and Hausdorff distance for two sets of points on the circle, no matter their nature. See Saavedra-Nieves and Crujeiras (2021) for more details on these two distances.

Value

A list with two components:

dE

Euclidean distance.

dH

Hausdorff distance.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# Distances between boundaries of two plug-in HDR estimators for orientations of saltator specie
data(sandhoppers)
attach(sandhoppers)
#Orientations in October
saltatorO<-angle[(species=="salt")&(time=="afternoon")&(sex=="M")&(month=="October")]
hdr1<-circ.plugin.hdr(sample=saltatorO,tau=0.8,plot.hdrconf=FALSE)$hdr
#Orientations in April
saltatorA<-angle[(species=="salt")&(time=="afternoon")&(sex=="M")&(month=="April")]
hdr2<-circ.plugin.hdr(sample=saltatorA,tau=0.8,plot.hdrconf=FALSE)$hdr
circ.distances(hdr1,hdr2)

Computation of HDRs for a circular density and of general level sets for circular real-valued functions

Description

This function computes HDRs for a circular density and general level sets for real-valued functions defined on the unit circle.

Usage

circ.hdr(f,tau=NULL,level=NULL,plot.hdr=TRUE,col=NULL,
         lty=NULL,shrink=NULL,cex=NULL,pch=NULL)

Arguments

f

Object of class "function" that represents a circular density function or any general real-valued function defined on the unit circle. Vector parametrisation of function f on a vector of angles with values between 0 and 2π2\pi must be established. Additionally, if f is not a density function, the argument tau cannot be specified and only the value of level must be provided by the user.

tau

Numeric probability. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverage required for HDR. If tau=NULL, a value for the threshold level must be provided.

level

Numeric threshold of the HDR or of the general level set provided by the user. If level is larger than the maximum value of the function f, the HDR or the level set are equal to the emptyset. If level is smaller than the minimum of f, its support is obtained. If level=NULL, f must be a density function and a value for the probability coverage 1-tau of the HDR must be provided.

plot.hdr

Logical string. If TRUE, the circular density and the level set or the HDR are represented graphically. Default plot.density=TRUE.

col

Color for plotting the HDR. Default col="darkgray" is used.

lty

A numeric value indicating the line type to represent the threshold of HDR. Line type can be specified as an integer (0=blank, 1=solid (default), 2=dashed, 3=dotted, 4=dotdash, 5=longdash, 6=twodash). Default lty=2.

shrink

Parameter that controls the size of the plotted circle. Default is 2. Larger than 1 values shrink the circle, while smaller values enlarge the circle.

cex

Point character size for representing the data on the scatterplot. Default is 0.5.

pch

Plotting character. Default 19.

Details

A detailed definition of HDRs for circular and spherical densities is given in Saavedra-Nieves and Crujeiras (2021). Trapezoidal rule is used to compute the threshold of HDR when tau is provided.

Value

If tau is provided, a list with the next components:

hdr

Boundaries of the HDR.

prob.content

Probability coverage 1-tau.

level

Threshold of the HDR associated to the probability content 1-tau.

If level is provided, a list with the next components:

levelset

Boundaries of the level set or a character indicating if the level set is equal to the emptyset or the support distribution.

level

Threshold of the level set.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# HDRs of model 11 in library NPCirc
library(NPCirc)
f1<-function(x){return(dcircmix(x,11))}
circ.hdr(f1,tau=0.2,shrink=1.5)
circ.hdr(f1,tau=0.8,shrink=1.5)

# Plug-in level set estimation for regression
# with circular (x) - linear (y) data by using
# the Nadaraya-Watson estimator
f2<-function(t){
  set.seed(1012)
  n <- 100
  x <- runif(n, 0, 2*pi)
  y <- sin(x)+0.5*rnorm(n)
  return(kern.reg.circ.lin(circular(x),y,t,bw=10,method="NW")$y)
}
circ.hdr(f2,level=.5,plot.hdr=FALSE)

Circular plug-in estimation of HDRs and confidence regions

Description

This function computes the circular plug-in estimator of HDRs and confidence regions in Saavedra-Nieves and Crujeiras (2021).

Usage

circ.plugin.hdr(sample,bw=bw.CV(circular(sample),upper=100),tau=NULL,
                tau.method="quantile",level=NULL,conf=.95,plot.hdr=TRUE,
                plot.hdrconf=TRUE,boot=FALSE,k=3,col=NULL,lty=NULL,shrink=NULL,
                lwd=NULL,pch=NULL,cex=NULL)

Arguments

sample

Numeric vector of angles in radians.

bw

Smoothing parameter to be used. It can be a numeric value directly selected by the user. Following Oliveira et al. (2014), the value of the smoothing parameter could be also chosen by using the functions bw.rt, bw.CV, bw.pi or bw.boot. Moreover, function circ.boot.bw allows to select the new smoothing parameter proposed in Saavedra-Nieves and Crujeiras (2021). Default bw=bw.CV providing a cross-validation bandwidth.

tau

Numeric probability. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverage required for HDR. If tau=NULL, a value for the threshold level of the HDR must be provided.

tau.method

Character value selecting the rule to estimate the threshold of the HDR. This must be one of "quantile" or "trapezoidal". The first option estimates the threshold using the quantile method proposed in Hyndman(1996); the second one, using the trapezoidal rule for numerical integration. Default tau.method= "quantile".

level

Numeric threshold of the HDR provided by the user. When level is larger than the maximum value of the density, the HDR is equal to the emptyset. If level is smaller than the minimum of the density, the HDR coincides with the support distribution. If level=NULL, a value for the probability coverage 1-tau of the HDR must be provided.

conf

Numeric value between 0 and 1 corresponding to the confidence for limits on HDR. Default conf=0.95.

plot.hdr

Logical string. If TRUE, the level set or the HDR are depicted. Default plot.hdr=TRUE.

plot.hdrconf

Logical string. If TRUE, the confidence region for the estimated HDR is added to the HDR graphical representation. Default plot.hdr=TRUE.

boot

Logical string. If TRUE, confidence regions are not computed. This option is only used for function circ.boot.bw in order to reduce the execution time. Default boot=FALSE.

k

Positive integer value that controls if the confidence region is plotted near (large values of k) or far away (small values of k) the estimated HDR. Default k=3.

col

Color number for plotting the HDR. Default col="darkgray" is used.

lty

A numeric value indicating the line type to represent the threshold of HDR. Line type can be specified as an integer (0=blank, 1=solid (default), 2=dashed, 3=dotted, 4=dotdash, 5=longdash, 6=twodash). Default lty=2.

shrink

Parameter that controls the size of the plotted circle. Default is 2. Larger than 1 values shrink the circle, while smaller values enlarge the circle.

lwd

A number indicating the line width for drawing symbol. Default 3.

pch

Point type. Default is 19.

cex

Point character size for representing the data on the scatterplot. Default is 0.5.

Details

A detailed definition of plug-in estimators for directional HDRs is given in Saavedra-Nieves and Crujeiras (2021). The density quantile algorithm proposed in Hyndman (1996) or the numerical integration method of trapezoidal rule can be used to compute the threshold of HDR. The confidence region for the estimated HDR is calculated also following Hyndman (1996).

Value

If tau is provided, a list with the next components:

hdr

Boundaries of the HDR.

prob.content

Probability coverage 1-tau.

level

Threshold associated to the probability content 1-tau.

bw

Value of the smoothing parameter used for kernel density estimation.

hdr.lo

HDR corresponding to lower confidence limit.

level.lo

Threshold associated to the lower confidence limit.

hdr.hi

HDR corresponding to upper confidence limit.

level.hi

Threshold associated to the upper confidence limit.

If level is provided, a list with the next components:

levelset

boundaries of the level set or a character indicating if the level set is equal to the emptyset or the support distribution.

prob.content

Probability coverage 1-tau associated to the level value.

level

Threshold of the level set.

bw

Value of the smoothing parameter used for kernel density estimation.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Hyndman, R.J. (1996). Computing and graphing highest density regions, The American Statistician, 50, 120-126.
Oliveira, M., Crujeiras. R.M. and Rodríguez-Casal, A. (2014). NPCirc: An R Package for Nonparametric Circular Methods, Journal of Statistical Software, 61, 1-26.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# Plug-in HDR for orientations of saltator specie in April and October
data(sandhoppers)
attach(sandhoppers)
#Orientations in October
saltatorO<-angle[(species=="salt")&(time=="afternoon")&(sex=="M")&(month=="October")]
circ.plugin.hdr(sample=saltatorO,tau=0.8,plot.hdrconf=FALSE)
#Orientations in April
saltatorA<-angle[(species=="salt")&(time=="afternoon")&(sex=="M")&(month=="April")]
circ.plugin.hdr(sample=saltatorA,tau=0.8,plot.hdrconf=FALSE)
#HDR confidence bands for model 5 in NPCirc package
library(NPCirc)
set.seed(1)
sample<- rcircmix(500, model=5)
circ.plugin.hdr(sample,bw=bw.CV(circular(sample),upper=100),tau=0.6)

Circular scatterplot for plug-in HDRs

Description

This function produces a circular scatterplot with points coloured according to the HDRs in which they fall.

Usage

circ.scatterplot(sample,tau=c(0.25,0.5,.75),
bw=bw.CV(circular(sample),upper=100),tau.method="quantile",
plot.density=TRUE,col=NULL,shrink=NULL,cex=NULL,lty=NULL)

Arguments

sample

Numeric vector of angles in radians.

tau

Numeric vector of probabilities. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverages required for HDRs.

bw

Smoothing parameter to be used. Following Oliveira et al. (2014), the value of the smoothing parameter can be chosen by using the functions bw.rt, bw.CV, bw.pi or bw.boot. It could be also selecting by considering circ.boot.bw, the new smoothing parameter proposed in Saavedra-Nieves and Crujeiras (2021). Default bw=bw.CV providing a cross-validation bandwidth.

tau.method

Character value selecting the rule to estimate the threshold of the HDR. This must be one of "quantile" or "trapezoidal". The first option estimates the threshold using the quantile method proposed in Hyndman(1996); the second one, using the trapezoidal rule for numerical integration. Default tau.method= "quantile".

plot.density

Logical string. If TRUE, the kernel density estimator is added to the scatterplot. Default plot.density=TRUE.

col

Vector containing the color numbers for plotting the scatterplot. If NULL, a default color palette is used.

shrink

Parameter that controls the size of the plotted circle. Default is 2. Larger values shrink the circle, while smaller values enlarge the circle.

cex

Point character size for representing the data on the scatterplot. Default is 0.5.

lty

A numeric vector indicating the line types to represent the thresholds of HDRs. Line type can be specified as an integer (0=blank, 1=solid (default), 2=dashed, 3=dotted, 4=dotdash, 5=longdash, 6=twodash). Default lty=2.

Details

A detailed definition of directional HDRs and of their plug-in estimators is given in Saavedra-Nieves and Crujeiras (2021).
Package NPCirc is used to estimate the circular density using the classical kernel density estimator. See Oliveira et al. (2014) for more details.
Moreover, the density quantile algorithm proposed in Hyndman (1996) or the trapezoidal rule can be used to compute the threshold of HDR.
The scatterplot is created colouring the sample points according to which HDR they fall.

Value

A scatterplot showing the points coloured according to which HDR they fall. Futhermore, a list where the number of components is equal to the number HDR estimated or, equivalently, to the length of tau vector. Each component contains the sample points in each HDR from the smallest value of tau to the biggest one.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Hyndman, R.J. (1996). Computing and graphing highest density regions, The American Statistician, 50, 120-126.
Oliveira, M., Crujeiras R.M. and Rodríguez-Casal, A. (2014). NPCirc: an R package for nonparametric circular methods. Journal of Statistical Software, 61(9), 1-26. https://www.jstatsoft.org/v61/i09/.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# Scatterplot for orientations of females for saltator specie
data(sandhoppers)
attach(sandhoppers)
saltatorF<-angle[(species=="salt")&(sex=="F")]
circ.scatterplot(saltatorF)
# Scatterplot for sample of size 100 of model 14 in NPCirc
library(NPCirc)
set.seed(1)
sample<- rcircmix(100, model=14)
circ.scatterplot(sample,tau=c(0.2,0.5,0.8))

Density functions for mixtures of spherical von Mises-Fisher

Description

Density functions for nine finite mixtures of spherical von Mises-Fisher allowing different numbers of modes.

Usage

dspheremix(x, model = NULL)

Arguments

x

A matrix whose rows represent points on the unit sphere in Cartesian coordinates. If a row norm is different from one, a message appears indicating that they must be standardized.

model

Number between 1 and 9, corresponding to a density model defined in Saavedra-Nieves and Crujeiras (2021). See Details.

Details

These nine spherical models are obtained as mixtures of von Mises distributions where the density ff is given by:

f=i=1IwiKvM(x;mi;ki),wi0;i=1Iwi=1f=\sum_{i=1}^I w_i K_{vM}(x;m_i;k_i), w_i\geq 0;\sum_{i=1}^I w_i=1

with KvMK_vM denoting the von Mises-Fisher kernel density; mim_i, kik_i and wiw_i the mean, concentration and weight corresponding to each component. More details can be found in Hornik and Grun (2014) and Wood (1994). The combination of means, concentration parameters and the weights of spherical models from Saavedra-Nieves and Crujeiras (2021) are specified below:

S1: (0, 0, 1) (mm); 10 (kk); 1 (ww).

S2: (0, 0, 1), (0, 0, -1) (mm); 1, 1 (kk); 1/2, 1/2 (ww).

S3: (0, 0, 1), (0, 0, -1) (mm); 10, 1 (kk); 1/2, 1/2 (ww).

S4: (0, 0, 1); (0, 1/2\sqrt2, 1/2\sqrt2) (mm); 10, 10 (kk); 1/2, 1/2 (ww).

S5: (0, 0, 1); (0, 1/2\sqrt2, 1/2\sqrt2) (mm); 10, 10 (kk); 2/5, 3/5 (ww).

S6: (0, 0, 1); (0, 1/2\sqrt2, 1/2\sqrt2) (mm); 10, 5 (kk); 1/5, 4/5 (ww).

S7: (0, 0, 1), (0, 1, 0), (1, 0, 0) (mm); 5, 5, 5 (kk); 1/3, 1/3, 1/3 (ww).

S8: (0, 0, 1), (0, 1, 0), (1, 0, 0) (mm); 5, 5, 5 (kk); 2/3, 1/6, 1/6 (ww).

S9: (0, 0, 1); (0, 1/2\sqrt 2, 1/2\sqrt 2), (0, 1, 0) (mm); 10, 10, 10 (kk); 1/3, 1/3, 1/3 (ww).

Value

A numeric vector of density evaluated on x.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Hornik, K. and Grun, B. (2014). movMF: an R package for fitting mixtures of von Mises-Fisher distributions. Journal of Statistical Software, 58(10), 1-31.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.
Wood, A. T. (1994). Simulation of the von Mises Fisher distribution. Communications in Statistics-Simulation and Computation, 23(1), 157-164.

Examples

# Density function evaluation from model S1
data <- rbind(c(1,0,0),c(0,1,0),c(0,0,1))
dspheremix(data, model=1)

Earthquakes on Earth between October 2004 and April 2020

Description

Geographical coordinates (latitude and longitude) of earthquakes of magnitude greater than or equal to 2.5 degrees.

Usage

data("earthquakes")

Format

A data frame with 272 observations on the following 2 variables:

Latitude

A numeric vector containing the latitude coordinates.

Longitude

A numeric vector containing the longitude coordinates.

Details

To map this dataset on the unit sphere, function euclid in package Directional can be used.

Source

European-Mediterranean Seismological Centre, https://www.emsc-csem.org.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
library(ggplot2)
}
if (requireNamespace("maps", quietly = TRUE)) {
library(maps)
}
if (requireNamespace("mapproj", quietly = TRUE)) {
library(mapproj)
}
data(earthquakes)
world <- map_data("world")
g.earthquakes <- ggplot() +
  geom_map(data = world, map = world,
           mapping = aes(map_id = region),
           color = "grey90", fill = "grey80") +
  geom_point(data = earthquakes,
            mapping = aes(x = Longitude, y = Latitude),
            color = "red",alpha=.2,size=.75,stroke=0) +
    scale_y_continuous(breaks = NULL, limits = c(-90, 90)) +
  scale_x_continuous(breaks = NULL, limits = c(-180, 180)) +
  coord_map("mercator")
g.earthquakes

Random generation functions for mixtures of spherical von Mises-Fisher

Description

Random generation functions for nine finite mixtures of spherical von Mises-Fisher allowing different numbers of modes.

Usage

rspheremix(n, model = NULL)

Arguments

n

Number of observations to generate.

model

Number between 1 and 9, corresponding with a model defined in Saavedra-Nieves and Crujeiras (2021). See Details.

Details

These nine spherical models are obtained as mixtures of von Mises distributions where the density ff is given by:

f=i=1IwiKvM(x;mi;ki),wi0;i=1Iwi=1f=\sum_{i=1}^I w_i K_{vM}(x;m_i;k_i), w_i\geq 0;\sum_{i=1}^I w_i=1

with KvMK_vM denoting the von Mises-Fisher kernel density; mim_i, kik_i and wiw_i the mean, concentration and weight corresponding to each component. More details can be found in Hornik and Grun (2014) and Wood (1994). The combination of means, concentration parameters and the weights of spherical models from Saavedra-Nieves and Crujeiras (2021) are specified below:

S1: (0, 0, 1) (mm); 10 (kk); 1 (ww).

S2: (0, 0, 1), (0, 0, -1) (mm); 1, 1 (kk); 1/2, 1/2 (ww).

S3: (0, 0, 1), (0, 0, -1) (mm); 10, 1 (kk); 1/2, 1/2 (ww).

S4: (0, 0, 1); (0, 1/2\sqrt2, 1/2\sqrt2) (mm); 10, 10 (kk); 1/2, 1/2 (ww).

S5: (0, 0, 1); (0, 1/2\sqrt2, 1/2\sqrt2) (mm); 10, 10 (kk); 2/5, 3/5 (ww).

S6: (0, 0, 1); (0, 1/2\sqrt2, 1/2\sqrt2) (mm); 10, 5 (kk); 1/5, 4/5 (ww).

S7: (0, 0, 1), (0, 1, 0), (1, 0, 0) (mm); 5, 5, 5 (kk); 1/3, 1/3, 1/3 (ww).

S8: (0, 0, 1), (0, 1, 0), (1, 0, 0) (mm); 5, 5, 5 (kk); 2/3, 1/6, 1/6 (ww).

S9: (0, 0, 1); (0, 1/2\sqrt 2, 1/2\sqrt 2), (0, 1, 0) (mm); 10, 10, 10 (kk); 1/3, 1/3, 1/3 (ww).

Value

A matrix with nn unit length rows representing the generated values from a finite mixture of spherical von Mises-Fisher.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Hornik, K. and Grun, B. (2014). movMF: an R package for fitting mixtures of von Mises-Fisher distributions. Journal of Statistical Software, 58(10), 1-31.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.
Wood, A. T. (1994). Simulation of the von Mises Fisher distribution. Communications in Statistics-Simulation and Computation, 23(1), 157-164.

Examples

# Random generation from model 1 in library HDiR
data <- rspheremix(500, model=1)
library(Directional)
sphereplot(data)

Behavioral plasticity of Talitrus saltator and Talorchestia brito

Description

Orientation measured under natural conditions and other variables of interest for analyzing the behavioral plasticity of two sympatric sandhoppers species, Talitrus saltator and Talorchestia brito. The experiment was carried out on the exposed nontidal sand of Zouara beach located in the Tunisian northwestern coast. More details can be found in Marchetti and Scapini (2003) or Scapini et al. (2002).

Usage

data("sandhoppers")

Format

A data frame with 1828 observations on the following 12 variables.

angle

Numeric vector containing the orientation angles in radians between 0 and 2π2\pi.

date

A factor where each level indicates the date when angles were measured.

month

A factor with two levels indicating the month when angles were measured. Experiments were performed in two different periods, April and October, which were chosen for the abundance of the populations, as well as for their non-extreme and changing climatic conditions.

time

A factor with levels afternoon, morning and noon.

azim

A numeric vector indicating the sun azimuth. The sun position was confounded with the time of the day (morning: 100-150, noon: az=151-210 and afternoon: az=211-260 experiments).

hour

A factor with hours when angles were measured.

species

A factor with three levels (brito, salt, ND) indicating the specie (brito, saltator, not determined).

sex

A factor with three levels (F, M, J) indicating the sex (female, male, J).

temp

A numeric vector indicating the temperature (degrees centigrade).

humid

A numeric vector indicating the air relative humidity (%).

land

A factor with two levels (no, yes) indicating landscape view was either permitted or screened.

trap

A numeric vector containing the traps identifier used for capturing the sandhoppers.

Details

Authors thank Prof. Felicita Scapini for providing the sandhoppers data (collected under the support of the European Project ERB ICI8-CT98-0270).

References

Marchetti, G. M. and Scapini, F., Use of multiple regression models in the study of sandhopper orientation under natural conditions, Estuarine, Coastal and Shelf Science, 58, 207-215 (2003).
Scapini, F., Aloia, A., Bouslama, M. F., Chelazzi, L., Colombini, I., ElGtari, M., Fallaci, M. and Marchetti, G. M. Multiple regression analysis of the sources of variation in orientation of two sympatric sandhoppers, Talitrus saltator and Talorchestia brito, from an exposed Mediterranean beach, Behavioral Ecology and Sociobiology, 51(5), 403-414 (2002).

Examples

data(sandhoppers)
attach(sandhoppers)
library(NPCirc)
saltator=circular(angle[(species=="salt")],type="angles",units="radians")
brito=circular(angle[(species=="brito")],type="angles",units="radians")
library(NPCirc)
oldpar<-par(mfrow=c(1,2))
plot(saltator)
plot(brito)
par(oldpar)

Spherical smoothing parameter for HDRs estimation

Description

This function provides the specific smoothing parameter for spherical HDRs estimation proposed in Saavedra-Nieves and Crujeiras (2021).

Usage

sphere.boot.bw(sample,bw="none",tau=0.5,ngrid=500,
               B=50,nborder=500,upper=NULL)

Arguments

sample

A matrix whose rows represent points on the unit sphere in Cartesian coordinates. If a row norm is different from one, a message appears indicating that they must be standardized.

bw

Pilot smoothing parameter to be used. According to Directional package, this can be either "none" for cross validation or "rot" for the rule of thumb suggested by García-Portugués (2013). Default bw="none".

tau

Numeric probability. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverage required for HDR. Default tau=0.5.

ngrid

Resolution of the density calculation. Default ngrid=500.

B

Integer string indicating the number of bootstrap resamples. Default B=50.

nborder

Maximum number of HDRs boundary points to be represented. Default nborder=500.

upper

Numerical upper value for bounding the optimization procedure. Default upper=NULL. In this case, the upper bound is equal to 1.5bw.

Details

Saavedra-Nieves and Crujeiras (2021) propose a specific smoothing parameter for HDRs estimation based on the minimization of the Hausdorff distance between the boundaries of the theoretical HDR and the plug-in estimator.

Value

A numeric value corresponding to the selected smoothing parameter.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

García-Portugués, E. (2013). Exact risk improvement of bandwidth selectors for kernel density estimation with directional data. Electronic Journal of Statistics, 7, 1655-1685.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# HDR selector from a sample of size 1000 of model 4 in library HDiR
set.seed(1)
sample=rspheremix(500,model=4)
sphere.boot.bw(sample,tau=0.8,B=2)

Euclidean and Hausdorff distances between two sets of points on the unit sphere

Description

This function determines the Euclidean and Hausdorff distances between two sets of points on the unit sphere.

Usage

sphere.distances(x, y)

Arguments

x

A matrix whose rows represent points on the unit sphere in Cartesian coordinates. If a row norm is different from one, a message appears indicating that they must be standardized.

y

A matrix whose rows represent points on the unit sphere in Cartesian coordinates. If a row norm is different from one, a message appears indicating that they must be standardized.

Details

If x and y correspond to two HDRs boundaries, this function returns the Euclidean and Hausdorff distances between the HDR frontiers, but the function computes the Euclidean and Hausdorff distance for two sets of points on the sphere, no matter their nature. See Saavedra-Nieves and Crujeiras (2021) for more details on these two distances.

Value

A list with two components:

dE

Euclidean distance.

dH

Hausdorff distance.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# Distances between boundaries of two plug-in HDR estimators for spherical model 9 in HDiR package
set.seed(1)
sample=rspheremix(1000, model =9)
x<-sphere.plugin.hdr(sample,tau=0.8,plot.hdr=FALSE)$hdr
y<-sphere.plugin.hdr(sample,tau=0.5,plot.hdr=FALSE)$hdr
sphere.distances(x, y)

Computation of HDRs for a spherical density and of general level sets for spherical real-valued functions

Description

This function computes HDRs of a spherical density and general level sets for real-valued functions defined on the unit sphere.

Usage

sphere.hdr(f,tau=NULL,level=NULL,nborder=1000,tol=0.1,
           mesh=40,deg=6,plot.hdr=TRUE,col=NULL)

Arguments

f

Object of class "function" that represents a spherical density function or any general real-valued function defined on the unit sphere. Matrix parametrisation of f must be established. Each row of the matrix corresponds to the cartesian coordinates of a point on the unit sphere. Additionally, if f is not a density function, the argument tau cannot be specified and only the value of level must be provided by the user.

tau

Numeric probability. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverage required for HDR. If tau=NULL, a value for the threshold level must be provided.

level

Numeric threshold of the HDR or of the general level set provided by the user. If level is larger than the maximum value of the function f, the HDR or the level set are equal to the emptyset. If level is smaller than the minimum of f, its support is obtained. If level=NULL, f must be a density function and a value for the probability coverage 1-tau of the HDR must be provided.

nborder

Maximum number of HDRs boundary points to be represented. Default nborder= 1000.

tol

Tolerance parameter to determinate the boundary of HDRs. Default tol=0.1.

mesh

A numeric value 10, 20 or 40 indicating the 3D cartesian mesh used for numerical integration on the unit shere. Default mesh=40 considering a total of 32000 triangular cells on the sphere. If mesh=20 or mesh=10, 8000 triangular cells or 2000 are considered, respectively.

deg

Integer string indicating the degree (from 0 to 6) of the quadrature rules for triangles on the sphere for numerical integration. Default deg=6.

plot.hdr

Logical string. If TRUE, the boundary of the level set or the HDR are represented graphically. Default plot.density=TRUE.

col

Color number for plotting the boundary of the HDR. Default "darkgray".

Details

A detailed definition of directional HDRs for a density is given in Saavedra-Nieves and Crujeiras (2021). Note that numerical integration on the sphere is used to compute the threshold of HDR when tau is provided.

Value

If tau is provided, a list with the next components:

hdr

A matrix of rows of points on the HDR boundary.

prob.content

Probability coverage 1-tau.

level

Threshold associated to the probability content 1-tau.

If level is provided, a list with the next components:

levelset

A matrix of rows of points on the level set boundary.

level

Threshold of the level set.

Author(s)

Paula Saavedra-Nieves, Rosa M. Crujeiras and Andrés Prieto.

References

Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

#HDR of model 8 in library HDiR
f1<-function(x){return(dspheremix(x,model=8))}
sphere.hdr(f1,tau=0.5,mesh=20,deg=3)


# Density level set plug-in reconstruction from a sample
# of size 500 (model 8) by using a kernel density
# estimator with uniform kernel
library(DirStats)
f2<-function(x){
  set.seed(1)
  sample<-rspheremix(500, model = 3)
  return(kde_dir(x, data = sample, h = 0.4,
  L = function(x) dunif(x)))
}
sphere.hdr(f2,level=0.3)

Spherical plug-in estimation of HDRs

Description

This function computes the spherical plug-in estimator of HDRs.

Usage

sphere.plugin.hdr(sample,bw="none",ngrid=500,
                  tau=NULL,level=NULL,nborder=1000,tol=0.01,
                  mesh=40,deg=3,plot.hdr=TRUE, col=NULL)

Arguments

sample

A matrix whose rows represent points on the unit sphere in Cartesian coordinates. If a row norm is different from one, a message appears indicating that they must be standardized.

bw

Smoothing parameter to be used. It can be a numeric value directly selected by the user. According to Directional package, this could be also either "none" for cross validation or "rot" for the rule of thumb suggested by García-Portugués (2013). Moreover, function sphere.boot.bw allows to select the new smoothing parameter proposed in Saavedra-Nieves and Crujeiras (2021). Default bw="none".

ngrid

Sets the resolution of the density calculation. Default ngrid=500.

tau

Numeric probability. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverage required for HDR. If tau=NULL, a value for the threshold level of the HDR must be provided.

level

Numeric threshold of the HDR provided by the user. When level is larger than the maximum value of the density, the HDR is equal to the emptyset. If level is smaller than the minimum of the density, the HDR coincides with the support distribution. If level=NULL, a value for the probability coverage 1-tau of the HDR must be provided.

nborder

Maximum number of HDRs boundary points to be represented. Default nborder= 1000.

tol

Tolerance parameter to determinate the boundary of HDRs. Default tol=0.01.

mesh

A numeric value 10, 20 or 40 indicating the 3D cartesian mesh used for numerical integration on the unit shere. Default mesh=40 considering a total of 32000 triangular cells on the sphere. If mesh=20 or mesh=10, 8000 triangular cells or 2000 are considered, respectively.

deg

Integer string indicating the degree (from 0 to 6) of the quadrature rules for triangles on the sphere. Default deg=6.

plot.hdr

Logical string. If TRUE, the boundary of the level set or the HDR are represented graphically. Default plot.hdr=TRUE.

col

Color number for plotting the boundary of the HDR. Default "darkgray".

Details

A detailed definition of plug-in estimators for directional HDRs is given in Saavedra-Nieves and Crujeiras (2021). Moreover, the density quantile algorithm proposed in Hyndman (1996) is used to compute the threshold of HDR.

Value

If tau is provided, a list with the next components:

hdr

A matrix of rows of points on the HDR boundary.

prob.content

Probability coverage 1-tau.

level

Threshold associated to the probability content 1-tau.

bw

Value of the smoothing parameter used for kernel density estimation.

If level is provided, a list with the next components:

levelset

A matrix of rows of points on the level set boundary or a character indicating if the level set is equal to the emptyset or the support distribution.

prob.content

Probability coverage 1-tau associated to the level value.

level

Threshold of the level set.

bw

Value of the smoothing parameter used for kernel density estimation.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

García-Portugués, E. (2013). Exact risk improvement of bandwidth selectors for kernel density estimation with directional data. Electronic Journal of Statistics, 7, 1655-1685.
Hyndman, R.J. (1996). Computing and graphing highest density regions, The American Statistician, 50, 120-126.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# Plug-in HDR estimator for spherical model 9 in HDiR package
set.seed(1)
sample=rspheremix(1000, model =9)
sphere.plugin.hdr(sample,tau=0.8,col="red")

#Plug-in HDR estimator for data on earthquakes on Earth
if (requireNamespace("ggplot2", quietly = TRUE)) {
library(ggplot2)
}
if (requireNamespace("maps", quietly = TRUE)) {
library(maps)
}
if (requireNamespace("mapproj", quietly = TRUE)) {
library(mapproj)
}
data(earthquakes)
library(Directional)
hdr08<-as.data.frame(euclid.inv(sphere.plugin.hdr(euclid(earthquakes),tau=0.8,
plot.hdr=FALSE)$hdr))
world <- map_data("world")
g.earthquakes <- ggplot() +
  geom_map(data = world, map = world,
           mapping = aes(map_id = region),
           color = "grey90", fill = "grey80") +
  geom_point(data = earthquakes,
            mapping = aes(x = Longitude, y = Latitude),
           color = "red",alpha=.2,size=.75,stroke=0) +
  geom_point(data = hdr08,
            mapping = aes(x = Long, y = Lat),
            color = "darkblue", size = 1) +
  scale_y_continuous(breaks = NULL, limits = c(-90, 90)) +
 scale_x_continuous(breaks = NULL, limits = c(-180, 180)) +
  coord_map("mercator")
g.earthquakes

Spherical scatterplot for plug-in HDRs

Description

This function produces a spherical scatterplot with points coloured according to the HDRs in which they fall.

Usage

sphere.scatterplot(sample,tau=c(0.25,0.5,.75),bw="none",
                   ngrid=500,nborder=1000,tol=0.1, col=NULL)

Arguments

sample

A matrix whose rows represent points on the unit sphere in Cartesian coordinates. If a row norm is different from one, a message appears indicating that they must be standardized.

tau

Numeric vector of probabilities. According to Saavedra-Nieves and Crujeiras (2021), 1-tau represents the probability coverages required for HDRs.

bw

Smoothing parameter to be used. According to Directional package, this can be either "none" for cross validation or "rot" for the rule of thumb suggested by García-Portugués (2013). It could be also selecting by considering sphere.boot.bw, the new smoothing parameter proposed in Saavedra-Nieves and Crujeiras (2021). Default bw="none".

ngrid

Sets the resolution of the density calculation. Default ngrid=500.

nborder

Maximum number of HDRs boundary points to be represented. Default nborder= 1000.

tol

Tolerance parameter to determinate the boundary of HDRs. Default tol=0.1.

col

Vector containing the color numbers for plotting the scatterplot. If NULL, a default color palette is used.

Details

A detailed definition of directional HDRs and of their plug-in estimators is given in Saavedra-Nieves and Crujeiras (2021).
Package Directional is used to compute tha von Mises-Fisher kernel density estimate.
The density quantile algorithm proposed in Hyndman (1996) is used to calculate the threshold of HDR.
The scatterplot is created colouring the sample points according to which HDR they fall.

Value

A scatterplot showing the points coloured according to which HDR they fall. Futhermore, a list where the number of components is equal to the number HDR estimated or, equivalently, to the length of tau vector. Each component contains the sample points in each HDR from the smallest value of tau to the biggest one.

Author(s)

Paula Saavedra-Nieves and Rosa M. Crujeiras.

References

García-Portugués, E. (2013). Exact risk improvement of bandwidth selectors for kernel density estimation with directional data. Electronic Journal of Statistics, 7, 1655-1685.
Tsagris, M., Athineou, G., Sajib, A., Tsagris, M. M. and Imports, M. A. S. S. (2016). Package Directional. https://cran.r-project.org/package=Directional.
Saavedra-Nieves, P. and Crujeiras, R. M. (2021). Nonparametric estimation of directional highest density regions. Advances in Data Analysis and Classification, 1-36.

Examples

# Scatterplot of model 4 in library HDiR
set.seed(1)
sample=rspheremix(1000,model=4)
sphere.scatterplot(sample,tau=c(.2,.5,.8))
#Scatterplot of model 9 in library HDiR
set.seed(1)
sample=rspheremix(1000,model=9)
sphere.scatterplot(sample)