circ.plugin.hdr {HDiR}

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)