adaptiveDensityCircular: Adaptive Kernel Density Estimation for circular data

In circularKDE: Recent Methods for Kernel Density Estimation of Circular Data

Adaptive Kernel Density Estimation for circular data

Description

This function computes an adaptive kernel density estimate for circular data, adjusting the bandwidth locally based on a global bandwidth parameter and data density (see \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s00180-023-01401-0")}).

Usage

adaptiveDensityCircular(
  x,
  bw0,
  alpha = 0.5,
  type = "n",
  z = NULL,
  from = 0,
  to = 2 * pi,
  n = 500
)

Arguments

x	Data for which the density is to be estimated. The object is coerced to a numeric vector in radians using circular. Can be a numeric vector or an object of class circular.
bw0	Global bandwidth parameter, a positive numeric value that sets the baseline smoothness of the density estimate. Controls the overall scale of the kernel.
alpha	Numeric scalar between 0 and 1 (default is 0.5) that determines the sensitivity of the local bandwidth adaptation. Higher values increase the influence of local data density on the bandwidth.
type	Character string specifying the method for calculating the local adaptation factor (default is "n"). Available options are: "am" Arithmetic mean of pilot density estimates "gm" Geometric mean of pilot density estimates (requires all positive values) "rv" Range (max - min) of pilot density estimates "n" No scaling factor (equivalent to fixed bandwidth)
z	Optional numeric vector of points at which to evaluate the density. If NULL (default), a grid of n equally spaced points between from and to is generated automatically.
from	Starting point of the evaluation range, a numeric value in radians. Must be finite. Default is circular(0) (0 radians).
to	Ending point of the evaluation range, a numeric value in radians. Must be finite. Default is circular(2 * pi) (2*pi radians).
n	Positive integer specifying the number of evaluation points (default is 500). Ignored if z is provided. Determines the resolution of the density estimate when z is NULL.

Details

The method extends the classical idea of variable bandwidth estimators from the linear case (Breiman et al., 1977) to the circular setting by employing the von Mises kernel. Specifically, the procedure follows three steps:

1. A pilot density estimate is obtained using a fixed global bandwidth \kappa (bw0).

2. Local adaptation factors \lambda_i are computed at each data point \Theta_i according to

   \lambda_i = \left\{ g / \hat{f}(\Theta_i) \right\}^{\alpha},

   where g is a global measure of central tendency (typically the geometric mean) and \alpha \in [0,1] is a sensitivity parameter.

3. The adaptive density is evaluated using local bandwidths \lambda_i \cdot \kappa, resulting in the estimator

   \hat{f}(\theta) = \frac{1}{2n\pi} \sum_{i=1}^{n} \frac{1}{I_0(\lambda_i \kappa)} \exp\!\big(\lambda_i \kappa \cos(\theta - \Theta_i)\big).

Value

A numeric vector of length equal to the length of z (or n if z is NULL), containing the estimated density values at each evaluation point.

References

Zámečník, S., Horová, I., Katina, S., & Hasilová, K. (2023). An adaptive method for bandwidth selection in circular kernel density estimation. Computational Statistics. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s00180-023-01401-0")}

Breiman, L., Meisel, W., & Purcell, E. (1977). Variable kernel estimates of multivariate densities. Technometrics, 19(2), 135-144. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.2307/1268623")}

Examples

# Example with numeric data in radians
library(circular)
x <- rvonmises(100, mu = circular(0), kappa = 1)
bw0 <- bwLscvg(x = x)$minimum
dens <- adaptiveDensityCircular(x, bw0 = bw0)
plot(seq(0, 2 * pi, length.out = 500), dens, type = "l",
     main = "Adaptive Circular Density")

# Example with numerical integration over interval [0,2pi] to verify normalization of
# computed density
library(circular)
x <- rvonmises(100, mu = circular(0), kappa = 1)
bw0 <- bwLscvg(x = x)$minimum
dens <- function(z)adaptiveDensityCircular(z = z, bw0 = bw0, x=x)
integrate(dens, lower = 0, upper = 2*pi) # 1 with absolute error < 4e-07

circularKDE documentation built on Jan. 7, 2026, 9:06 a.m.