hdrcde

https://pkg.robjhyndman.com/hdrcde/
Admin
hdrcde is an R package for computing highest density regions in one and two dimensions, conditional...
Tokens:20,477
Snippets:190
Trust Score:9.5
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### hdr.boxplot examples

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.boxplot.html

Examples from the documentation: plotting eruption durations, a bimodal example comparing boxplot and hdr.boxplot, and a skewed example using lambda = 0.

```r
# Old faithful eruption duration times
hdr.boxplot(faithful$eruptions)


# Simple bimodal example
x <- c(rnorm(100, 0, 1), rnorm(100, 5, 1))
par(mfrow = c(1, 2))
boxplot(x)
hdr.boxplot(x)


# Highly skewed example
x <- exp(rnorm(100, 0, 1))
par(mfrow = c(1, 2))
boxplot(x)
hdr.boxplot(x, lambda = 0)
```

--------------------------------

### Example: computing and plotting HDR with confidence intervals

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdrconf.html

Example code that generates data, estimates density, computes HDR with confidence intervals, and plots the result.

```R
x <- c(rnorm(100, 0, 1), rnorm(100, 4, 1))
den <- density(x, bw = hdrbw(x, 50))
hdr_conf <- hdrconf(x, den)
plot(hdr_conf, den, main = "50% HDR with 95% CI")
```

--------------------------------

### modalreg Example

Source: https://pkg.robjhyndman.com/hdrcde/reference/modalreg.html

A basic example of fitting a multimodal regression model to the lane2 dataset.

```R
lane2.fit <- modalreg(lane2$flow, lane2$speed, xfix = seq(55) * 40, a = 100, b = 4)
```

--------------------------------

### Install development version from GitHub

Source: https://pkg.robjhyndman.com/hdrcde/index.html

Installs the development version of hdrcde from GitHub using the pak package.

```R
pak::pak("robjhyndman/hdrcde")
```

--------------------------------

### hdr.den example with Old Faithful data

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.den.html

Example using the faithful dataset's eruption durations. The output shows the computed HDR intervals, f-alpha values, and mode.

```r
# Old faithful eruption duration times
hdr.den(faithful$eruptions)

#> Highest Density Regions
#>   50%: [1.923, 2.024], [3.944, 4.771]
#>   95%: [1.501, 2.521], [3.500, 5.091]
#>   99%: [1.324, 2.819], [3.151, 5.282]
#> 
#> f-alpha values: 0.3622 0.1526 0.06702
#> Mode: 4.381
```

--------------------------------

### Example: cde.bandwidths with faithful data

Source: https://pkg.robjhyndman.com/hdrcde/reference/cde.bandwidths.html

Example usage of cde.bandwidths with the faithful dataset, using method = 2 (normal reference rules). The resulting bandwidths are passed to cde() for plotting.

```r
bands <- cde.bandwidths(faithful$waiting, faithful$eruptions, method = 2)
plot(cde(faithful$waiting, faithful$eruptions, a = bands$a, b = bands$b))
```

--------------------------------

### hdr.den example with bimodal data

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.den.html

Example using a simple bimodal dataset created from two normal distributions. The output shows the HDR intervals, f-alpha values, and mode.

```r
# Simple bimodal example
x <- c(rnorm(100, 0, 1), rnorm(100, 5, 1))
hdr.den(x)

#> Highest Density Regions
#>   50%: [-0.4301, 1.090], [4.340, 5.606]
#>   95%: [-1.518, 6.710], [   NA,    NA]
#>   99%: [-2.226, 7.392], [   NA,    NA]
#> 
#> f-alpha values: 0.1057 0.07410 0.04932
#> Mode: 0.2942
```

--------------------------------

### Install stable version from CRAN

Source: https://pkg.robjhyndman.com/hdrcde/index.html

Installs the stable version of hdrcde from CRAN, including dependencies.

```R
install.packages('hdrcde', dependencies = TRUE)
```

--------------------------------

### cde() examples with Old Faithful and maxtemp data

Source: https://pkg.robjhyndman.com/hdrcde/reference/cde.html

Example usage of cde() on the Old Faithful data and on Melbourne maximum temperatures with bias adjustment. The second example fits a linear mean and passes it via the mean argument to adjust the conditional density.

```R
# Old faithful data
faithful.cde <- cde(faithful$waiting, faithful$eruptions,
  x.name = "Waiting time", y.name = "Duration time"
)
plot(faithful.cde)

plot(faithful.cde, plot.fn = "hdr")


# Melbourne maximum temperatures with bias adjustment
x <- maxtemp[1:3649]
y <- maxtemp[2:3650]
maxtemp.cde <- cde(x, y,
  x.name = "Today's max temperature", y.name = "Tomorrow's max temperature"
)
# Assume linear mean
fit <- lm(y ~ x)
fit.mean <- list(x = 6:45, y = fit$coef[1] + fit$coef[2] * (6:45))
maxtemp.cde2 <- cde(x, y,
  mean = fit.mean,
  x.name = "Today's max temperature", y.name = "Tomorrow's max temperature"
)
plot(maxtemp.cde)
```

--------------------------------

### hdrbw example with faithful data

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdrbw.html

Example usage of hdrbw with the faithful eruptions data. Sets HDRlevelVal to 0.55, computes the optimal bandwidth hHDR, then uses hdr.den with prob = 100 * (1 - HDRlevelVal) and the computed bandwidth to estimate the highest density region.

```r
HDRlevelVal <- 0.55
x <- faithful$eruptions
hHDR <- hdrbw(x, HDRlevelVal)
HDRhat <- hdr.den(x, prob = 100 * (1 - HDRlevelVal), h = hHDR)
```

--------------------------------

### hdr() example with faithful data

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.html

Example using the Old Faithful eruption duration times. The output shows HDR intervals for 50%, 95%, and 99% probability, f-alpha values, and the estimated mode.

```r
# Old faithful eruption duration times
hdr(faithful$eruptions)
#> Highest Density Regions
#>   50%: [1.923, 2.025], [3.942, 4.772]
#>   95%: [1.501, 2.521], [3.500, 5.092]
#>   99%: [1.324, 2.819], [3.152, 5.282]
#> 
#> f-alpha values: 0.3610 0.1529 0.06747
#> Mode: 4.378
```

--------------------------------

### Example: Compute and plot HDRs for faithful data

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.cde.html

Computes conditional density for the faithful dataset using cde(), then calculates HDRs with hdr.cde at 50% and 95% levels. The printed output shows the HDR summary, and the final plot command visualizes the result.

```R
faithful.cde <- cde(faithful$waiting, faithful$eruptions)
faithful.hdr <- hdr.cde(faithful.cde, prob = c(0.50, 0.95))

faithful.hdr
#> HDRs for conditional density estimate:
#>    faithful$eruptions | faithful$waiting 
#> Conditioning values: 43.00, 46.79, 50.57, 54.36, 58.14, 61.93, 65.71, 69.50, 73.29, 77.07, 80.86, 84.64, 88.43, 92.21, 96.00 
#> Levels:  50%, 95% 
plot(faithful.hdr, xlab = "Waiting time", ylab = "Duration time")
```

--------------------------------

### Example: Plot conditional density with stacked and hdr

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.cde.html

Creates a 'cde' object from the 'faithful' dataset and plots it using the default 'stacked' method and then with 'plot.fn = "hdr"'.

```R
faithful.cde <- cde(faithful$waiting, faithful$eruptions,
  x.name = "Waiting time", y.name = "Duration time"
)
plot(faithful.cde)

plot(faithful.cde, plot.fn = "hdr")
```

--------------------------------

### Example: bivariate HDR boxplot and custom plot

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.boxplot.2d.html

Example usage: generates two bivariate normal clusters, creates a bivariate HDR boxplot with hdr.boxplot.2d, then computes an hdr2d object with hdr.2d and plots it with custom point color, points shown, and plotting character.

```R
x <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
y <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
hdr.boxplot.2d(x, y)


hdrinfo <- hdr.2d(x, y)
plot(hdrinfo, pointcol = "red", show.points = TRUE, pch = 3)
```

--------------------------------

### Plot HDRs from true and empirical densities

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.hdrconf.html

Example from the documentation that generates a 2x2 plot comparing HDRs computed from the true density and from an empirical density for confidence levels 50% and 95%. It uses hdrconf() and plot() on the resulting hdrconf objects.

```r
x <- c(rnorm(100, 0, 1), rnorm(100, 4, 1))
den <- density(x, bw = bw.SJ(x))
trueden <- den
trueden$y <- 0.5 * (exp(-0.5 * (den$x * den$x)) + exp(-0.5 * (den$x - 4)^2)) / sqrt(2 * pi)

par(mfcol = c(2, 2))
for (conf in c(50, 95)) {
  m <- hdrconf(x, trueden, conf = conf)
  plot(m, trueden, main = paste(conf, "% HDR from true density"))
  m <- hdrconf(x, den, conf = conf)
  plot(m, den, main = paste(conf, "% HDR from empirical density\n(n=200)"))
}
```

--------------------------------

### hdr()

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.html

Documentation for the hdr function, which calculates highest density regions in one dimension.

```APIDOC
## hdr(x, prob, den, h, lambda, nn, all.modes)

### Description
Calculates highest density regions in one dimension. The function estimates the density from the data or uses a provided density, then computes the HDRs for the specified probability coverages.

### Usage
```r
hdr(
  x = NULL,
  prob = c(0.5, 0.95, 0.99),
  den = NULL,
  h = hdrbw(BoxCox(x, lambda), mean(prob)),
  lambda = 1,
  nn = 5000,
  all.modes = FALSE
)
```

### Arguments
- **x** (numeric vector) - Optional - Numeric vector containing data. If `x` is missing then `den` must be provided, and the HDR is computed from the given density.
- **prob** (numeric vector) - Optional - Probability coverage required for HDRs. Default is `c(0.5, 0.95, 0.99)`.
- **den** (list) - Optional - Density of data as list with components `x` and `y`. If omitted, the density is estimated from `x` using `stats::density()`.
- **h** (numeric) - Optional - Optional bandwidth for calculation of density.
- **lambda** (numeric) - Optional - Box-Cox transformation parameter where 0 ≤ λ ≤ 1. Default is 1.
- **nn** (integer) - Optional - Number of random numbers used in computing f-alpha quantiles. Default is 5000.
- **all.modes** (logical) - Optional - Return all local modes or just the global mode? Default is FALSE.

### Value
A list of three components:
- **hdr** - The endpoints of each interval in each HDR.
- **mode** - The estimated mode of the density.
- **falpha** - The value of the density at the boundaries of each HDR.

### Details
Either `x` or `den` must be provided. When `x` is provided, the density is estimated using kernel density estimation. A Box-Cox transformation is used if `lambda != 1`, as described in Wand, Marron and Ruppert (1991). This allows the density estimate to be non-zero only on the positive real line. The default kernel bandwidth `h` is selected using the algorithm of Samworth and Wand (2010). Hyndman's (1996) density quantile algorithm is used for calculation.

### Examples
```r
# Old faithful eruption duration times
hdr(faithful$eruptions)
#> Highest Density Regions
#>   50%: [1.923, 2.025], [3.942, 4.772]
#>   95%: [1.501, 2.521], [3.500, 5.092]
#>   99%: [1.324, 2.819], [3.152, 5.282]
#> 
#> f-alpha values: 0.3610 0.1529 0.06747
#> Mode: 4.378
```
```

--------------------------------

### Load maxtemp dataset

Source: https://pkg.robjhyndman.com/hdrcde/reference/maxtemp.html

Access the daily maximum temperatures in Melbourne, Australia, from 1981-1990 as a time series of frequency 365. Leap days have been omitted.

```r
maxtemp
```

--------------------------------

### hdr.den function usage

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.den.html

The function signature for hdr.den, showing all arguments and defaults. Use this to call the function with custom parameters.

```r
hdr.den(
  x,
  prob = c(0.5, 0.95, 0.99),
  den,
  h = hdrbw(BoxCox(x, lambda), mean(prob)),
  lambda = 1,
  xlab = NULL,
  ylab = "Density",
  ylim = NULL,
  plot.lines = TRUE,
  col = 2:8,
  bgcol = "gray",
  legend = FALSE,
  ...
)
```

--------------------------------

### hdrbw(x, HDRlevel, gridsize = 801, nMChdr = 1e+06, graphProgress = FALSE)

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdrbw.html

Estimates the optimal bandwidth for 1-dimensional highest density regions. It returns a numerical vector of length 1.

```APIDOC
## hdrbw(x, HDRlevel, gridsize = 801, nMChdr = 1e+06, graphProgress = FALSE)

### Description
Estimates the optimal bandwidth for 1-dimensional highest density regions.

### Usage
hdrbw(x, HDRlevel, gridsize = 801, nMChdr = 1e+06, graphProgress = FALSE)

### Arguments
- **x** (numeric vector) - Required - Numerical vector containing data.
- **HDRlevel** (numeric) - Required - HDR-level as defined in Hyndman (1996). Setting `HDRlevel` equal to p (0<p<1) corresponds to a probability of 1-p of inclusion in the highest density region.
- **gridsize** (numeric) - Optional - The number of equally spaced points used for binned kernel density estimation. Default is 801.
- **nMChdr** (numeric) - Optional - The size of the Monte Carlo sample used for density quantile approximation of the highest density region, as described in Hyndman (1996). Default is 1e+06.
- **graphProgress** (logical) - Optional - Logical flag: if `TRUE` then plots showing the progress of the bandwidth selection algorithm are produced. Default is FALSE.

### Value
A numerical vector of length 1.

### Details
This is a plug-in rule for bandwidth selection tailored to highest density region estimation.

### References
Hyndman, R.J. (1996). Computing and graphing highest density regions. _The American Statistician_, **50**, 120-126.
Samworth, R.J. and Wand, M.P. (2010). Asymptotics and optimal bandwidth selection for highest density region estimation. _The Annals of Statistics_, **38**, 1767-1792.

### Author
Matt Wand

### Examples
```r
HDRlevelVal <- 0.55
x <- faithful$eruptions
hHDR <- hdrbw(x, HDRlevelVal)
HDRhat <- hdr.den(x, prob = 100 * (1 - HDRlevelVal), h = hHDR)
```
```

--------------------------------

### S3 method plot for class 'cde'

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.cde.html

Defines the S3 method for plotting 'cde' objects. The 'plot.fn' argument selects between 'stacked' (default) and 'hdr' plotting. When there is more than one conditioning variable, 'firstvar' and 'mfrow' control the layout.

```R
# S3 method for class 'cde'
plot(
  x,
  firstvar = 1,
  mfrow = n2mfrow(dim(x$z)[firstvar]),
  plot.fn = "stacked",
  x.name,
  margin = NULL,
  ...
)
```

--------------------------------

### plot(x, plot.modes = TRUE, mden, threshold = 0.05, xlim, ylim, xlab, ylab, border = TRUE, font = 1, cex = 1, ...)

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.hdrcde.html

Plots highest density regions continuously over some conditioned variable. This method is used to visualize the output of hdr.cde() by plotting HDRs and optionally modes.

```APIDOC
## plot(x, plot.modes = TRUE, mden, threshold = 0.05, xlim, ylim, xlab, ylab, border = TRUE, font = 1, cex = 1, ...)

### Description
Plots highest density regions continuously over some conditioned variable.

### Method
S3 method for class 'hdrcde'

### Usage
```r
# S3 method for class 'hdrcde'
plot(
  x,
  plot.modes = TRUE,
  mden,
  threshold = 0.05,
  xlim,
  ylim,
  xlab,
  ylab,
  border = TRUE,
  font = 1,
  cex = 1,
  ...
)
```

### Arguments
- **x** - Output from `hdr.cde()`.
- **plot.modes** - Should modes be plotted as well as HDRs?
- **mden** - Marginal density in the `x` direction. When small, the HDRs won't be plotted. Default is uniform so all HDRs are plotted.
- **threshold** - Threshold for margin density. HDRs are not plotted if the margin density `mden` is lower than this value.
- **xlim** - Limits for x-axis.
- **ylim** - Limits for y-axis.
- **xlab** - Label for x-axis.
- **ylab** - Label for y-axis.
- **border** - Show border of polygons.
- **font** - Font to be used in plot.
- **cex** - Size of characters.
- **...** - Other arguments passed to plotting functions.

### Value
None.

### References
Hyndman, R.J., Bashtannyk, D.M. and Grunwald, G.K. (1996) "Estimating and visualizing conditional densities". _Journal of Computational and Graphical Statistics_ , **5** , 315-336.

### See Also
`hdr.cde()`, `cde()`

### Author
Rob J Hyndman

### Examples
```r
faithful.cde <- cde(faithful$waiting, faithful$eruptions)
faithful.hdr <- hdr.cde(faithful.cde, prob = c(0.50, 0.95), plot = FALSE)
plot(faithful.hdr, xlab = "Waiting time", ylab = "Duration time")
```
```

--------------------------------

### S3 method plot for hdrconf objects

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.hdrconf.html

S3 method for plotting objects of class 'hdrconf' produced by hdrconf(). It takes the hdrconf output as x, the density data as a list with components x and y, and passes additional arguments to plot.

```r
# S3 method for class 'hdrconf'
plot(x, den, ...)
```

--------------------------------

### S3 method usage for plot.hdrcde

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.hdrcde.html

Shows the formal arguments of the plot method for 'hdrcde' objects. Use this to understand the available parameters such as plot.modes, threshold, and border.

```r
# S3 method for class 'hdrcde'
plot(
  x,
  plot.modes = TRUE,
  mden,
  threshold = 0.05,
  xlim,
  ylim,
  xlab,
  ylab,
  border = TRUE,
  font = 1,
  cex = 1,
  ...
)
```

--------------------------------

### hdrconf(x, den, prob = 0.9, conf = 0.95)

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdrconf.html

Calculates Highest Density Regions with confidence intervals.

```APIDOC
## hdrconf(x, den, prob = 0.9, conf = 0.95)

### Description
Calculates Highest Density Regions with confidence intervals.

### Usage
```r
hdrconf(x, den, prob = 0.9, conf = 0.95)
```

### Arguments
- **x** (numeric vector) - Required - Numeric vector containing data.
- **den** (list) - Required - Density of data as list with components `x` and `y`.
- **prob** (numeric) - Optional - Probability coverage for HDRs. Default is 0.9.
- **conf** (numeric) - Optional - Confidence for limits on HDR. Default is 0.95.

### Value
Returns a list containing the following components:
- **hdr** - Highest density regions.
- **hdr.lo** - Highest density regions corresponding to lower confidence limit.
- **hdr.hi** - Highest density regions corresponding to upper confidence limit.
- **falpha** - Values of fα corresponding to HDRs.
- **falpha.ci** - Values of fα corresponding to lower and upper limits.

### References
Hyndman, R.J. (1996) Computing and graphing highest density regions _American Statistician_, **50**, 120-126.

### See Also
`hdr()`, `plot.hdrconf()`

### Author
Rob J Hyndman

### Examples
```r
x <- c(rnorm(100, 0, 1), rnorm(100, 4, 1))
den <- density(x, bw = hdrbw(x, 50))
hdr_conf <- hdrconf(x, den)
plot(hdr_conf, den, main = "50% HDR with 95% CI")
```
```

--------------------------------

### hdr.cde(den, prob, plot, nn, ...)

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.cde.html

Calculates and plots highest density regions for a conditional density estimate. Uses output from cde().

```APIDOC
## hdr.cde(den, prob, plot, nn, ...)

### Description
Calculates and plots highest density regions for a conditional density estimate. Uses output from `cde()`.

### Usage
```r
hdr.cde(den, prob = c(0.5, 0.95, 0.99), plot = TRUE, nn = 1000, ...)
```

### Arguments
- **den** - Conditional density in the same format as the output from `cde()`.
- **prob** - Probability coverage level for HDRs.
- **plot** - Should HDRs be plotted? If FALSE, results are returned.
- **nn** - Number of points to be sampled from each density when estimating the HDRs.
- **...** - Other arguments passed to `plot.hdrcde()`.

### Value
- **hdr** - array (a,b,c) where a specifies conditioning value, b gives the HDR endpoints and c gives the probability coverage.
- **modes** - estimated mode of each conditional density.

The result is returned invisibly if `plot=TRUE`.

### References
Hyndman, R.J., Bashtannyk, D.M. and Grunwald, G.K. (1996) "Estimating and visualizing conditional densities". _Journal of Computational and Graphical Statistics_, **5**, 315-336.

### See Also
`plot.hdrcde()`, `cde()`

### Examples
```r
faithful.cde <- cde(faithful$waiting, faithful$eruptions)
faithful.hdr <- hdr.cde(faithful.cde, prob = c(0.50, 0.95))

faithful.hdr
#> HDRs for conditional density estimate:
#>    faithful$eruptions | faithful$waiting 
#> Conditioning values: 43.00, 46.79, 50.57, 54.36, 58.14, 61.93, 65.71, 69.50, 73.29, 77.07, 80.86, 84.64, 88.43, 92.21, 96.00 
#> Levels:  50%, 95% 
plot(faithful.hdr, xlab = "Waiting time", ylab = "Duration time")
```
```

--------------------------------

### Usage signatures for hdr.2d, hdr.boxplot.2d, and plot.hdr2d

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.boxplot.2d.html

Function signatures for hdr.2d, hdr.boxplot.2d, and the S3 plot method for class 'hdr2d'. hdr.2d computes HDRs and returns an hdr2d object; hdr.boxplot.2d produces a bivariate HDR boxplot; plot.hdr2d draws the contours with optional shading and points.

```R
hdr.2d(
  x,
  y,
  prob = c(0.5, 0.95, 0.99),
  den = NULL,
  kde.package = c("ash", "ks"),
  h = NULL,
  xextend = 0.15,
  yextend = 0.15
)

hdr.boxplot.2d(
  x,
  y,
  prob = c(0.5, 0.99),
  kde.package = c("ash", "ks"),
  h = NULL,
  xextend = 0.15,
  yextend = 0.15,
  xlab = "",
  ylab = "",
  shadecols = "darkgray",
  pointcol = 1,
  outside.points = TRUE,
  ...
)

# S3 method for class 'hdr2d'
plot(
  x,
  shaded = TRUE,
  show.points = FALSE,
  outside.points = FALSE,
  pch = 20,
  shadecols = gray(rev(seq_along(x$alpha))/(length(x$alpha) + 1)),
  pointcol = 1,
  ...
)
```

--------------------------------

### hdrscatterplot(x, y, levels, kde.package, noutliers, label)

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdrscatterplot.html

Creates a scatterplot of x and y with points coloured according to the bivariate highest density regions (HDRs) they fall into. The function estimates the bivariate density using kernel density estimation and returns a ggplot object.

```APIDOC
## hdrscatterplot(x, y, levels, kde.package, noutliers, label)

### Description
Produces a scatterplot where the points are coloured according to the bivariate HDRs in which they fall. The bivariate density is estimated using kernel density estimation, and Hyndman's (1996) density quantile algorithm is used to compute the HDRs. A ggplot object is returned.

### Usage
```r
hdrscatterplot(
  x,
  y,
  levels = c(1, 50, 99),
  kde.package = c("ash", "ks"),
  noutliers = NULL,
  label = NULL
)
```

### Arguments
- **x** (numeric vector or matrix with 2 columns) - Required - Numeric vector or matrix with 2 columns.
- **y** (numeric vector) - Required - Numeric vector of same length as `x`.
- **levels** (numeric vector) - Optional - Percentage coverage for HDRs. Default is `c(1, 50, 99)`.
- **kde.package** (character) - Optional - Package to be used in calculating the kernel density estimate when `den=NULL`. Options are `"ash"` or `"ks"`. Default is `c("ash", "ks")`.
- **noutliers** (integer) - Optional - Number of outliers to be labelled. By default, all points outside the largest HDR are labelled.
- **label** (character vector) - Optional - Label of outliers of same length as `x` and `y`. By default, all outliers are labelled as the row index of the point `(x, y)`.

### Details
The bivariate density is estimated using kernel density estimation. Either `ash::ash2()` or `ks::kde()` is used to do the calculations. Then Hyndman's (1996) density quantile algorithm is used to compute the HDRs. The scatterplot of (x,y) is created where the points are coloured according to which HDR they fall. A ggplot object is returned.

### Value
A ggplot object.

### See Also
`hdr.boxplot.2d()`

### Author
Rob J Hyndman

### Examples
```r
x <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
y <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
hdrscatterplot(x, y)

hdrscatterplot(x, y, label = paste0("p", seq_along(x)))
```
```

--------------------------------

### hdr.boxplot(x, prob, h, lambda, boxlabels, col, main, xlab, ylab, pch, border, outline, space, ...)

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.boxplot.html

Calculates and plots a univariate highest density regions boxplot. The density is estimated using kernel density estimation with optional Box-Cox transformation. Returns nothing but produces a plot.

```APIDOC
## hdr.boxplot(x, prob, h, lambda, boxlabels, col, main, xlab, ylab, pch, border, outline, space, ...)

### Description
Calculates and plots a univariate highest density regions boxplot. The density is estimated using kernel density estimation with optional Box-Cox transformation. Returns nothing but produces a plot.

### Usage
```r
hdr.boxplot(
  x,
  prob = c(0.99, 0.5),
  h = hdrbw(BoxCox(x, lambda), mean(prob)),
  lambda = 1,
  boxlabels = "",
  col = rev(gray(seq(9)/10)),
  main = "",
  xlab = "",
  ylab = "",
  pch = 1,
  border = 1,
  outline = TRUE,
  space = 0.25,
  ...
)
```

### Arguments
- **x** (numeric vector or list) - Required - Numeric vector containing data or a list containing several vectors.
- **prob** (numeric vector) - Optional - Probability coverage required for HDRs `stats::density()`. Default: c(0.99, 0.5).
- **h** (numeric) - Optional - Optional bandwidth for calculation of density. Default: hdrbw(BoxCox(x, lambda), mean(prob)).
- **lambda** (numeric) - Optional - Box-Cox transformation parameter where 0 ≤ λ ≤ 1. Default: 1.
- **boxlabels** (character) - Optional - Label for each box plotted. Default: "".
- **col** (character vector) - Optional - Colours for regions of each box. Default: rev(gray(seq(9)/10)).
- **main** (character) - Optional - Overall title for the plot. Default: "".
- **xlab** (character) - Optional - Label for x-axis. Default: "".
- **ylab** (character) - Optional - Label for y-axis. Default: "".
- **pch** (numeric) - Optional - Plotting character. Default: 1.
- **border** (numeric) - Optional - Width of border of box. Default: 1.
- **outline** (logical) - Optional - If not `TRUE`, the outliers are not drawn. Default: TRUE.
- **space** (numeric) - Optional - The space between each box, between 0 and 0.5. Default: 0.25.
- **...** - Optional - Other arguments passed to plot.

### Value
nothing.

### Details
The density is estimated using kernel density estimation. A Box-Cox transformation is used if `lambda!=1`, as described in Wand, Marron and Ruppert (1991). This allows the density estimate to be non-zero only on the positive real line. The default kernel bandwidth `h` is selected using the algorithm of Samworth and Wand (2010). Hyndman's (1996) density quantile algorithm is used for calculation.

### Examples
```r
# Old faithful eruption duration times
hdr.boxplot(faithful$eruptions)

# Simple bimodal example
x <- c(rnorm(100, 0, 1), rnorm(100, 5, 1))
par(mfrow = c(1, 2))
boxplot(x)
hdr.boxplot(x)

# Highly skewed example
x <- exp(rnorm(100, 0, 1))
par(mfrow = c(1, 2))
boxplot(x)
hdr.boxplot(x, lambda = 0)
```
```

--------------------------------

### plot.hdr2d

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.boxplot.2d.html

S3 method for class 'hdr2d' to plot the HDR contours.

```APIDOC
## plot.hdr2d

### Description
S3 method for class 'hdr2d' to plot the HDR contours.

### Usage
```r
# S3 method for class 'hdr2d'
plot(
  x,
  shaded = TRUE,
  show.points = FALSE,
  outside.points = FALSE,
  pch = 20,
  shadecols = gray(rev(seq_along(x$alpha))/(length(x$alpha) + 1)),
  pointcol = 1,
  ...
)
```

### Arguments
- **x** (hdr2d object) - Required - An object of class `hdr2d`.
- **shaded** (logical) - Optional - If `TRUE`, the HDR contours are shown as shaded regions.
- **show.points** (logical) - Optional - If `TRUE`, the observations are plotted over the top of the HDR contours.
- **outside.points** (logical) - Optional - If `TRUE`, the observations lying outside the largest HDR are shown.
- **pch** (plotting character) - Optional - The plotting character used for observations.
- **shadecols** (colors) - Optional - Colors for shaded regions.
- **pointcol** (color) - Optional - Color for outliers and mode.
- **...** - Optional - Other arguments to be passed to plot.

### Details
S3 method for class 'hdr2d' to plot the HDR contours.

### Examples
```r
x <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
y <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
hdrinfo <- hdr.2d(x, y)
plot(hdrinfo, pointcol = "red", show.points = TRUE, pch = 3)
```
```

--------------------------------

### Usage: hdr.cde function signature

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.cde.html

Function signature for hdr.cde. Arguments: den (conditional density from cde()), prob (probability coverage levels), plot (whether to plot), nn (number of points to sample), and ... (passed to plot.hdrcde).

```R
hdr.cde(den, prob = c(0.5, 0.95, 0.99), plot = TRUE, nn = 1000, ...)
```

--------------------------------

### plot(x, den, ...)

Source: https://pkg.robjhyndman.com/hdrcde/reference/plot.hdrconf.html

S3 method for class 'hdrconf' that plots Highest Density Regions with confidence intervals. It takes the output from hdrconf and a density object, and passes additional arguments to the underlying plot function.

```APIDOC
## plot(x, den, ...)

### Description
Plots Highest Density Regions with confidence intervals.

### Usage
```r
# S3 method for class 'hdrconf'
plot(x, den, ...)
```

### Arguments
- **x** - Output from `hdrconf`.
- **den** - Density of data as list with components `x` and `y`.
- **...** - Other arguments are passed to plot.

### Value
None

### Examples
```r
x <- c(rnorm(100, 0, 1), rnorm(100, 4, 1))
den <- density(x, bw = bw.SJ(x))
trueden <- den
trueden$y <- 0.5 * (exp(-0.5 * (den$x * den$x)) + exp(-0.5 * (den$x - 4)^2)) / sqrt(2 * pi)

par(mfcol = c(2, 2))
for (conf in c(50, 95)) {
  m <- hdrconf(x, trueden, conf = conf)
  plot(m, trueden, main = paste(conf, "% HDR from true density"))
  m <- hdrconf(x, den, conf = conf)
  plot(m, den, main = paste(conf, "% HDR from empirical density\n(n=200)"))
}
```
```

--------------------------------

### modalreg Usage

Source: https://pkg.robjhyndman.com/hdrcde/reference/modalreg.html

The function signature for modalreg, defining the parameters for conditioning variables, bandwidths, and estimation settings.

```R
modalreg(
  x,
  y,
  xfix = seq(min(x), max(x), l = 50),
  a,
  b,
  deg = 0,
  iter = 30,
  P = 2,
  start = "e",
  prun = TRUE,
  prun.const = 10,
  plot.type = c("p", 1),
  labels = c("", "x", "y"),
  pch = 20,
  ...
)
```

--------------------------------

### hdr.2d

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdr.boxplot.2d.html

Calculates highest density regions in two dimensions and returns an object of class `hdr2d` containing all the information needed to compute the HDR contours.

```APIDOC
## hdr.2d

### Description
Calculates highest density regions in two dimensions and returns an object of class `hdr2d` containing all the information needed to compute the HDR contours.

### Usage
```r
hdr.2d(
  x,
  y,
  prob = c(0.5, 0.95, 0.99),
  den = NULL,
  kde.package = c("ash", "ks"),
  h = NULL,
  xextend = 0.15,
  yextend = 0.15
)
```

### Arguments
- **x** (numeric vector) - Required - Numeric vector.
- **y** (numeric vector) - Required - Numeric vector of same length as `x`.
- **prob** (numeric vector) - Optional - Probability coverage required for HDRs.
- **den** (list) - Optional - Bivariate density estimate (a list with elements x, y and z where x and y are grid values and z is a matrix of density values). If `NULL`, the density is estimated.
- **kde.package** (character) - Optional - Package to be used in calculating the kernel density estimate when `den=NULL`.
- **h** (pair of bandwidths) - Optional - Pair of bandwidths passed to either `ash::ash2()` or `ks::kde()`. If NULL, a reasonable default is used. Ignored if `den` is not `NULL`.
- **xextend** (numeric) - Optional - Proportion of range of `x`. The density is estimated on a grid extended by `xextend` beyond the range of `x`.
- **yextend** (numeric) - Optional - Proportion of range of `y`. The density is estimated on a grid extended by `yextend` beyond the range of `y`.

### Value
Returns an object of class `hdr2d` containing all the information needed to compute the HDR contours.

### Details
The density is estimated using kernel density estimation. Either `ash::ash2()` or `ks::kde()` is used to do the calculations. Then Hyndman's (1996) density quantile algorithm is used to compute the HDRs.

### Examples
```r
x <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
y <- c(rnorm(200, 0, 1), rnorm(200, 4, 1))
hdrinfo <- hdr.2d(x, y)
plot(hdrinfo, pointcol = "red", show.points = TRUE, pch = 3)
```
```

--------------------------------

### hdrconf function usage

Source: https://pkg.robjhyndman.com/hdrcde/reference/hdrconf.html

The usage signature for hdrconf, showing the function arguments: x, den, prob, and conf.

```R
hdrconf(x, den, prob = 0.9, conf = 0.95)
```
Tokens:
Raw