locmodes: Location of modes and antimodes
In multimode: Mode Testing and Exploring

Description Usage Arguments Details Value Author(s) References Examples

Given a certain number of modes, this function provides the estimation of the location of modes and antimodes and their density value.

locmodes(data,mod0=1,lowsup=-Inf,uppsup=Inf,n=2^15,tol=10^(-5),display=F,...)

## S3 method for class 'locmod'
plot(x,addplot=NULL,xlab=NULL,ylab=NULL,addLegend=NULL,posLegend=NULL,...)

## S3 method for class 'locmod'
print(x,digits=getOption("digits"), ...)

`data`	Sample in which the critical bandwidth is computed.
`mod0`	Number of modes for which the critical bandwidth is calculated. Default `mod0=1`.
`lowsup`	Lower limit for the random variable support in the computation of the critical bandwidth. Default is `-Inf`.
`uppsup`	Upper limit for the random variable support in the computation of the critical bandwidth. Default is `Inf`.
`n`	The number of equally spaced points at which the density is to be estimated. When n > 512, it is rounded up to a power of 2 as in the `density` function. Default `n=2^15`.
`tol`	Accuracy requested in the computation of the critical bandwidth. Default value `tol=10^(-5)`.
`display`	Logical, if `TRUE` the kernel density estimation is plotted adding the estimated location of the modes and the antimodes. Default is `FALSE`.
`...`	Arguments to be passed to subsequent methods, `plot.default` for the `plot` method and `formatC` for the `print` method.
`x`	An object inheriting from class `"locmod"`.
`addplot`	Logical, if `TRUE` the plot is added to the current one. Default is `FALSE`.
`xlab`	A title for the x axis. See `title`.
`ylab`	A title for the y axis. See `title`.
`addLegend`	Logical, if `TRUE` the legend is added in the plot. Default is `TRUE`.
`posLegend`	The vector of two elements of coordinates to be used to position the legend. It can be specified by keyword as in the function `legend`. Default is `"topright"`.
`digits`	Number of significant digits to use, see `formatC`.

Given a certain number of modes, mod0, with locmodes the estimation of the location of modes and antimodes, their density value and the corresponding critical bandwidth is provided. To obtain these estimates, the kernel density estimation with gaussian kernel and the critical bandwidth for mod0 modes is employed. If the compact support is unknown, the critical bandwidth of Silverman (1981) is computed and if such a support is provided, then the one proposed by Hall and York (2001) is calculated. Note that when the support is unknown the critical bandwidth may create artificial modes in the tails.

Since a dichotomy method is employed for computing the critical bandwidth, the parameter tol is used to determine a stopping time in such a way that the error committed in the computation of the critical bandwidth is less than tol.

If display=TRUE, then the kernel density estimation using the critical bandwidth for mod0 modes is plotted. Additionally, the estimated location of modes (dashed lines), antimodes (point lines) and support (solid lines) can be also plotted. If addLegend=TRUE, a legend (in the position posLegend) with this information is included.

The NAs will be automatically removed.

A list with class "locmod" containing the following components:

`locations`	Vector with the estimated locations of modes (odd positions of the vector) and antimodes (even positions).
`fvalue`	Vector with estimated density values at modes (odd positions of the vector) and antimodes (even positions).
`cbw`	A list with class `"estmod"` which contains the critical bandwidth of the sample for `mod0` modes, see `bw.crit`.

Jose Ameijeiras-Alonso, Rosa M. Crujeiras and Alberto Rodríguez-Casal

Ameijeiras-Alonso, J., Crujeiras, R.M. and Rodríguez-Casal, A. (2019). Mode testing, critical bandwidth and excess mass, Test, 28, 900–919.

Ameijeiras-Alonso, J., Crujeiras, R.M. and Rodríguez-Casal, A. (2021). multimode: An R Package for Mode Assessment, Journal of Statistical Software, 97, 1–32.

Hall, P. and York, M. (2001). On the calibration of Silverman's test for multimodality, Statistica Sinica, 11, 515–536.

Silverman, B. W. (1981). Using kernel density estimates to investigate multimodality, Journal of the Royal Statistical Society. Series B, 43, 97–99.

# Testing for unimodality
set.seed(2016)
data=rnorm(50)
modetest(data)
#There is no evidence to reject the null hypothesis of unimodality
#Estimated location of the mode and its density value
locmodes(data)
## Not run: 
#Estimated locations of the five modes in the claw of Marron and Wand (1992)
library(nor1mix)
set.seed(2016)
n<-200
data<-nor1mix::rnorMix(n,MW.nm10)
#Adding the plot of the estimated locations
locmodes(data,5,display=T)
#Assuming that the compact support is [-1.5,1.5]
locmodes(data,5,-1.5,1.5,display=T)

## End(Not run)

	Ameijeiras-Alonso et al. (2018) excess mass test

data:  data
Excess mass = 0.079185, p-value = 0.506
alternative hypothesis: true number of modes is greater than 1


Estimated location
Mode: -0.5651903 

Estimated value of the density
Mode: 0.4229909 

Critical bandwidth: 0.4180908

Warning message:
In locmodes(data) :
  If the density function has an unbounded support, artificial modes may have been created in the tails

Estimated location
Modes: -2.458196  -0.759649  0.1084437  0.4495994  0.9357462 
Antimodes: -2.131688  -0.1605872  0.2669699  0.7395817 

Estimated value of the density
Modes: 0.0193012  0.4149353   0.35628  0.3583746  0.345829 
Antimodes: 0.01545373  0.3370749  0.3527849  0.3299447 

Critical bandwidth: 0.1816101

Warning message:
In locmodes(data, 5, display = T) :
  If the density function has an unbounded support, artificial modes may have been created in the tails

Estimated location
Modes: -0.9354084  -0.4878276  0.05629011  0.5117865  0.9796727 
Antimodes: -0.6189528  -0.1837618  0.2894588  0.7409974 

Estimated value of the density
Modes: 0.4410117  0.4157784  0.3865489  0.4017639  0.4130368 
Antimodes: 0.4107008  0.291326  0.3240414  0.2711733 

Critical bandwidth: 0.1088104