kdensity: Parametrically guided kernel density estimation

In kdensity: Kernel Density Estimation with Parametric Starts and Asymmetric Kernels

Parametrically guided kernel density estimation

Description

kdensity computes a parametrically guided kernel density estimate for univariate data. It supports asymmetric kernels and parametric starts through the kernel and start arguments.

Usage

kdensity(
  x,
  bw = NULL,
  adjust = 1,
  kernel = NULL,
  start = NULL,
  support = NULL,
  na.rm = FALSE,
  normalized = TRUE,
  tolerance = 0.01
)

Arguments

x	Numeric vector containing the data.
bw	A bandwidth function. Can be either a string, a custom-made function, or a double. The supported bandwidth functions are documented in bandwidths(). Every built-in kernel defaults to a closed-form rule; use bw = "ucv" for start-aware cross-validation. For symmetric kernels, bw is on the Gaussian standard-deviation scale.
adjust	An adjustment constant. For symmetric kernels, h = adjust * bw * sd, where sd is the kernel's stored scale factor (the reciprocal of its standard deviation). For asymmetric kernels, h = adjust * bw.
kernel	The kernel function. Can be chosen from the list of built-in kernels or be custom-made. See kernels() for details.
start	Parametric start. Can be chosen from the list of built-in parametric starts or be custom-made. See parametric_starts() for details.
support	The support of the data. Must be compatible with the supplied x and the supplied start and kernel. Is used to find the normalization constant, see normalized.
na.rm	Logical; if TRUE, NAs will be removed from x.
normalized	Logical; if TRUE, the density is normalized.
tolerance	Numeric; the relative error to tolerate in normalization.

Details

The default values for bw, kernel, start, and support are interdependent, and are chosen to make sense. E.g., the default value for support when start = beta is c(0, 1).

The start argument defaults to uniform, which corresponds to ordinary kernel density estimation. The typical default value for kernel is gaussian.

If normalized is FALSE and start != "uniform", the resulting density will not integrate to 1 in general.

Fitted objects are read-only: ⁠$<-⁠ and ⁠[[<-⁠ assignment is not supported. Use kde <- update(kde, bw = 0.5) to refit from the stored call with changed arguments and return a new object. The data must be visible where update() is called.

The logLik(), AIC(), and BIC() methods for kdensity objects describe the fitted parametric start alone, not the kernel density estimate: they use the start's maximum-likelihood log-likelihood, so they can be used to compare candidate parametric starts. They are undefined for the uniform and constant starts (logLik() returns NA and errors), which have no parametric model.

Value

kdensity returns an S3 function object of base::class() "kdensity". This is a callable function with the following elements, accessible by '$':

x

The data supplied in x.

⁠bw_str, bw, adjust, h⁠

The bandwidth function, the resulting bandwidth, the adjust argument, and the adjusted bandwidth.

⁠kernel_str, kernel, start, start_str, support⁠

Name of the kernel, the kernel object, name of the parametric start, the start object, and the support of the density.

⁠data.name, n, range, has.na, na.rm, normalized⁠

Name of the data, number of observations, the range of the data, whether the data x contained NA values, whether na.rm is TRUE or not, and whether the density is normalized.

call

The call to kdensity.

estimates

Named numeric vector containing the parameter estimates from the parametric start.

logLik

The log-likelihood of the fitted parametric start (not of the kernel density estimate): the sum of ⁠log start(x_i)⁠ at the maximum-likelihood estimates, evaluated directly on the log scale when supported by the start density. Is NA for the uniform and constant starts.

References

Hjort, Nils Lid, and Ingrid K. Glad. "Nonparametric density estimation with a parametric start." The Annals of Statistics (1995): 882-904.

Jones, M. C., and D. A. Henderson. "Miscellanea kernel-type density estimation on the unit interval." Biometrika 94.4 (2007): 977-984.

Chen, Song Xi. "Probability density function estimation using gamma kernels." Annals of the Institute of Statistical Mathematics 52.3 (2000): 471-480.

Silverman, Bernard W. Density estimation for statistics and data analysis. Vol. 26. CRC press, 1986.

See Also

The stats package function stats::density().

Examples

## Use gamma kernels to model positive data, the concentration of
## theophylline

concentration <- Theoph$conc + 0.001
plot(kdensity(concentration, start = "gamma", kernel = "gamma", adjust = 1 / 3),
  ylim = c(0, 0.15), lwd = 2, main = "Concentration of theophylline"
)
lines(kdensity(concentration, start = "gamma", kernel = "gaussian"),
  lty = 2, col = "grey", lwd = 2
)
lines(kdensity(concentration, start = "gaussian", kernel = "gaussian"),
  lty = 3, col = "blue", lwd = 2
)
lines(kdensity(concentration, start = "gaussian", kernel = "gamma", adjust = 1 / 3),
  lty = 4, col = "red", lwd = 2
)
rug(concentration)

kdensity documentation built on Oct. 28, 2026, 5:06 p.m.