Package {kdensity}

Type:	Package
Title:	Kernel Density Estimation with Parametric Starts and Asymmetric Kernels
Version:	2.0.0
Description:	Handles univariate non-parametric density estimation with parametric starts and asymmetric kernels in a simple and flexible way. Kernel density estimation with parametric starts involves fitting a parametric density to the data before making a correction with kernel density estimation, see Hjort & Glad (1995) <doi:10.1214/aos/1176324627>. Asymmetric kernels make kernel density estimation more efficient on bounded intervals such as (0, 1) and the positive half-line. Supported asymmetric kernels are the gamma kernel of Chen (2000) <doi:10.1023/A:1004165218295>, the beta kernel of Chen (1999) <doi:10.1016/S0167-9473(99)00010-9>, and the copula kernel of Jones & Henderson (2007) <doi:10.1093/biomet/asm068>. User-supplied kernels, parametric starts, and bandwidths are supported.
License:	MIT + file LICENSE
URL:	https://github.com/JonasMoss/kdensity
BugReports:	https://github.com/JonasMoss/kdensity/issues
Encoding:	UTF-8
Suggests:	extraDistr, testthat, knitr, rmarkdown
Imports:	Rcpp, univariateML
LinkingTo:	Rcpp
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
NeedsCompilation:	yes
Packaged:	2026-10-28 12:55:42 UTC; jonas
Author:	Jonas Moss [aut, cre], Martin Tveten [ctb]
Maintainer:	Jonas Moss <jonas.gjertsen@gmail.com>
Repository:	CRAN
Date/Publication:	2026-10-28 14:30:02 UTC

Add a new kernel to kernels_environment.

Description

Add a new kernel to kernels_environment.

Usage

add_kernel(kernel_str, kernel)

Arguments

Value

None.

Add a new parametric start to starts_environment.

Description

Add a new parametric start to starts_environment.

Usage

add_start(start_str, start)

Arguments

Value

None.

Bandwidth Selectors

Description

The available options for bandwidth selectors, passed as the bw argument to kdensity.

Details

The bandwidth functions are not exported. They are members of the environment bw_environment, and can be accessed by kdensity:::bw_environment.

Defaults

Every default is a closed-form rule, so no default requires cross-validation:

The rules use only the data, not the fitted parametric start. When the start fits well, the correction it leaves for the kernel is smoother than the density itself, so a larger bandwidth would be better; the rules then undersmooth slightly. "ucv" takes the start into account at the cost of a computation that grows with the square of the sample size.

Bandwidth selectors

⁠"nrd0", "nrd", "bcv"⁠: Bandwidth selectors from stats, documented in stats::bw.nrd0(). They are on the scale of the Gaussian kernel's standard deviation; kdensity rescales them for the other symmetric kernels.

"SJ": The Sheather & Jones (1991) plug-in selector stats::bw.SJ(). For the gcopula kernel it is applied on the probit scale: there the Gaussian copula estimator is a Gaussian kernel estimate with bandwidth s = sqrt(1 - rho^2), where rho = 1 - h^2, so the selected s is converted to h = sqrt(1 - sqrt(1 - s^2)). If the selector fails on degenerate data, "JH" is used with a warning.

"ucv": Unbiased cross-validation. With a parametric start it refits the start without each observation, so its cost grows with the square of the sample size.

"HS": Hallberg Szabadváry's closed-form reference rule for the bias-corrected beta kernel, based on a beta reference density fitted by moments. Used for both beta kernels, with a fallback heuristic when the rule's moment conditions fail.

"GR": Chen's AMISE-optimal bandwidth for the bias-corrected gamma kernel, with the unknown density replaced by a gamma reference fitted by maximum likelihood to the positive observations. The fitted shape is floored at 3, keeping the fitted mean: the rule needs a shape above 3/2, and the floor was the most robust choice in simulations with exponential, lognormal, Weibull and mixture targets. Used for both gamma kernels.

"RHE": A reference rule for symmetric kernels that estimates the roughness of the density with Hermite polynomials around a fitted normal density. It uses only the data, not the parametric start.

"JH": Jones & Henderson's normal-reference rule for the Gaussian copula kernel. Accurate for unimodal data, but it oversmooths multimodal data badly; capped at 0.5.

Structure

The bandwidth selector is a function of four arguments: The data x, a kernel string kernel, a start string start, and a support vector support. To obtain the functions associated with these strings, use get_kernel and get_start. The function should return a double.

References

Jones, M. C., and D. A. Henderson. "Kernel-type density estimation on the unit interval." Biometrika 94.4 (2007): 977-984. Hjort, Nils Lid, and Ingrid K. Glad. "Nonparametric density estimation with a parametric start." The Annals of Statistics (1995): 882-904. Hallberg Szabadváry, Johan. "A Fast, Closed-Form Bandwidth Selector for the Beta Kernel Density Estimator." arXiv preprint arXiv:2601.19553 (2026). Sheather, S. J., and M. C. Jones. "A reliable data-based bandwidth selection method for kernel density estimation." Journal of the Royal Statistical Society: Series B 53.3 (1991): 683-690. Chen, Song Xi. "Probability density function estimation using gamma kernels." Annals of the Institute of Statistical Mathematics 52.3 (2000): 471-480.

See Also

kdensity(), stats::bandwidth.kernel() for the bandwidth selectors of stats::density(). In addition, kernels(); parametric_starts()

Examples

## Not a serious bandwidth function.
silly_width <- function(x, kernel = NULL, start = NULL, support = NULL) {
  rexp(1)
}
kdensity(mtcars$mpg, start = "gumbel", bw = silly_width)

Get bandwidth functions from string.

Description

Get bandwidth functions from string.

Usage

get_bw(bw_str)

Arguments

Value

a bandwidth function.

Helper function that gets a kernel function for kdensity.

Description

Helper function that gets a kernel function for kdensity.

Usage

get_kernel(kernel_str)

Arguments

Value

a kernel function of the format k(u) with integral normalized to 1.

Fill in missing kernel, start or support given the supplied values.

Description

This function takes the supplied values of kernel, start, and support and fills in the non-supplied ones. It also handles inconsistencies, such as providing a support on (-Inf, Inf) but a kernel on (0, Inf).

Usage

get_kernel_start_support(kernel, start, support)

Arguments

Details

The kernel and start parameters are either strings or adhering to the kernel/start list structure. support is a numeric vector of length two.

Value

a list with members kernel, kernel_str, start, start_str, and support.

Supplies a plotting range from a kdensity object.

Description

Supplies a plotting range from a kdensity object.

Usage

get_range(obj)

Arguments

Value

S vector of size 1000, used for plotting.

Get a bandwidth string when 'bw' is unspecified.

Description

Get a bandwidth string when 'bw' is unspecified.

Usage

get_standard_bw(kernel_str, start_str, support)

Arguments

Value

a bandwidth string.

Get densities and estimators from strings.

Description

Get densities and estimators from strings.

Usage

get_start(start_str)

Arguments

Value

A list of two functions.

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

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)

Evaluate a kdensity fit on a fast grid

Description

kdensity_grid() evaluates a fitted kdensity() object on a grid. The "fft" method uses weighted linear binning and an FFT convolution with the fitted kernel, the algorithm of stats::density(), for every built-in symmetric kernel. It also supports the Gaussian-copula kernel through its exact Gaussian-convolution representation on the probit scale.

Usage

kdensity_grid(
  object,
  from = NULL,
  to = NULL,
  n = 512L,
  method = c("auto", "exact", "fft"),
  fft_n = NULL,
  truncate = 8
)

Arguments

Details

The FFT method approximates only the binning and interpolation steps. The fitted parametric start and the normalization constant from object are retained. Calling the kdensity object itself always uses exact evaluation.

Value

An object of class "density". Its method element records whether exact or FFT evaluation was used.

See Also

kdensity()

Examples

set.seed(1)
fit <- kdensity(rbeta(1000, 2, 5), kernel = "gcopula", bw = 0.12)
fast <- kdensity_grid(fit, n = 512)
plot(fast)

Kernel functions

Description

Kernel functions are an important part of kdensity. This document lists the available built-in functions and the structure of them. Any kernel in the list can be used in kdensity by using kernel = "kernel" for the intended kernel.

Details

Ordinary symmetric kernel estimates use exact normalization constants. With a non-uniform parametric start, compact-support kernels still require numerical normalization, which can fail to converge; use gaussian if this occurs.

Symmetric kernels

⁠gaussian, normal⁠: The Gaussian kernel. The default argument when starts is supported on R. ⁠epanechnikov, rectangular (uniform), triangular, biweight, cosine, optcosine⁠: Standard symmetric kernels, also used in stats::density(). ⁠tricube, triweight⁠: Standard symmetric kernels. Not supported by stats::density(). laplace: Uses the Laplace density, also known as the double exponential density.

Asymmetric kernels

⁠gamma, gamma_biased⁠: The gamma kernels of Chen (2000). For use on the positive half-line. gamma_biased is Chen's first kernel, a gamma density with shape y / h + 1 and scale h. gamma is the recommended bias-corrected (modified) kernel, with shape y / h when ⁠y >= 2h⁠ and ⁠(y / (2h))^2 + 1⁠ otherwise. gcopula: The Gaussian copula kernel of Jones & Henderson (2007). For use on the unit interval. ⁠beta, beta_biased⁠: The beta kernel of Chen (1999). For use on the unit interval. beta is the recommended bias-corrected kernel.

Structure

A kernel is a list containing two mandatory elements and one optional element. The mandatory element 'kernel' is the kernel function. It takes arguments ⁠y, x, h⁠, where x is the data supplied to kdensity and y is the point of evaluation. h is the bandwidth. Internally, the kernel function is evaluated as 1/h*kernel(y, x, h). It should be vectorized in x, but vectorization in y is not needed.

The second mandatory element is support, stating the domain of definition for the kernel. This is used to distinguish kernels on the unit interval / positive half-line from kernels on R.

sd is used for symmetric kernels and is the reciprocal of the kernel's standard deviation. This scale factor converts a bandwidth on the Gaussian standard-deviation scale to h = adjust * bw * sd.

Custom objects must use names different from the built-ins (for example, my_gaussian). Registering another custom object under the same name replaces the earlier custom object.

References

Chen, Song Xi. "Probability density function estimation using gamma kernels." Annals of the Institute of Statistical Mathematics 52.3 (2000): 471-480. Jones, M. C., and D. A. Henderson. "Kernel-type density estimation on the unit interval." Biometrika 94.4 (2007): 977-984. Chen, Song Xi. "Beta kernel estimators for density functions." Computational Statistics & Data Analysis 31.2 (1999): 131-145.

See Also

kdensity(); parametric_starts(); bandwidths().

Examples

my_gaussian <- list(
  kernel = function(y, x, h) stats::dnorm((y - x) / h),
  sd = 1,
  support = c(-Inf, Inf)
)

my_gcopula <- list(
  kernel = function(y, x, h) {
    rho <- 1 - h^2
    inside <- rho^2 * (qnorm(y)^2 + qnorm(x)^2) - 2 * rho * qnorm(y) * qnorm(x)
    h / sqrt(1 - rho^2) * exp(-inside / (2 * (1 - rho^2)))
  },
  support = c(0, 1)
)

Parametric starts

Description

A parametric start is a density function with an associated estimator which is used as a starting point in kdensity. Several parametric starts are implemented, all with maximum likelihood estimation. Custom-made parametric starts are possible, see the Structure section.

Structure

The parametric start contains three elements: The density function, an estimation function, and the support of the density. The parameters of the density function must partially match the parameters of the estimator function. The estimator function takes one argument, a numeric vector, which is passed from kdensity.

Custom objects must use names different from the built-ins (for example, my_gaussian). Registering another custom object under the same name replaces the earlier custom object.

Supported parametric starts

kdensity supports more than 20 built-in starts from the univariateML package, see univariateML::univariateML_models for a list. Densities with variable support, power, are not supported. The pareto density has its support fixed to ⁠(1,Inf)⁠. The options ⁠uniform, constant⁠ makes kdensity estimate a kernel density without parametric starts.

See Also

kdensity(); kernels(); bandwidths()

Examples

start_exponential <- list(
  density = stats::dexp,
  estimator = function(data) {
    c(rate = 1 / mean(data))
  },
  support = c(0, Inf)
)

start_inverse_gaussian <- list(
  density = extraDistr::dwald,
  estimator = function(data) {
    c(
      mu = mean(data),
      lambda = mean(1 / data - 1 / mean(data))
    )
  },
  support = c(0, Inf)
)

Plot, Lines and Points Methods for Kernel Density Estimation

Description

The plot method for kdensity objects.

Usage

## S3 method for class 'kdensity'
plot(x, range = NULL, plot_start = FALSE, zero_line = TRUE, grid = "auto", ...)

## S3 method for class 'kdensity'
lines(
  x,
  range = NULL,
  plot_start = FALSE,
  zero_line = TRUE,
  grid = "auto",
  ...
)

## S3 method for class 'kdensity'
points(
  x,
  range = NULL,
  plot_start = FALSE,
  zero_line = TRUE,
  grid = "auto",
  ...
)

Arguments

Value

None.

See Also

kdensity()

Examples

## Using the data set "precip" to eye-ball the similarity between
## a kernel fit, a parametric fit, and a kernel with parametric start fit.
kde_gamma <- kdensity(precip, kernel = "gaussian", start = "gamma")
kde <- kdensity(precip, kernel = "gaussian", start = "uniform")

plot(kde_gamma, main = "Annual Precipitation in US Cities")
lines(kde_gamma, plot_start = TRUE, lty = 2)
lines(kde, lty = 3)
rug(precip)

Helper function for the plot methods.

Description

A helper function for the plot methods that does most of the work under the hood.

Usage

plot_helper(
  x,
  range = NULL,
  plot_start = FALSE,
  zero_line = TRUE,
  grid = "auto",
  ptype = c("plot", "lines", "points"),
  ...
)

Arguments

Value

None.

Checks compatibility between supports.

Description

The supplied support must never be larger than the support of the parametric start / kernel.

Usage

support_compatible(kernel, start, support)

Arguments

Value

None.