API Reference

All estimators assume X is an object that can be casted to a np.ndarray with dtype=np.float64.

Estimators

class kern.KernelDensity(bandwidth=1.0, kernel='gaussian')

Exact one-dimensional kernel density estimator.

Parameters:

• bandwidth (float, default=1.0) – Kernel bandwidth.

• kernel (str, default="gaussian") – One of gaussian, epanechnikov, triangular, uniform, or cosine.

Examples

>>> model = KernelDensity(bandwidth=0.3).fit([0.0, 0.2, 1.0])
>>> model.evaluate([0.1, 0.5]).shape
(2,)

fit(X, y=None)

Store the training samples.

evaluate(X)

Return density values at X.

self_density()

Return leave-one-out density at each training sample.

score_samples(X)

Return log-density values at X.

score(X, y=None)

Return the total log-likelihood of X.

class kern.ApproximateKernelDensity(bandwidth=1.0, kernel='gaussian', cutoff=None, max_neighbors=None, fast_gaussian=False, memory='auto')

Sorted one-dimensional KDE with distance and neighbor cutoffs.

The samples are sorted once by fit(). cutoff is measured in bandwidths. When it is None, compact kernels use 1 and Gaussian uses 4. max_neighbors limits work on each side of a point.

Set fast_gaussian=True to use Schraudolph’s exponential approximation [Schraudolph 1999]. memory="high" evaluates symmetric self-pairs once with per-thread buffers and caches external cutoff bounds. "low" avoids those buffers, while "auto" chooses based on problem size.

Parameters:

• bandwidth (float, default=1.0) – Kernel bandwidth.

• kernel (str, default="gaussian") – Kernel name.

• cutoff (float or None, default=None) – Distance cutoff measured in bandwidths. If None, compact kernels use 1 and Gaussian uses 4.

• max_neighbors (int or None, default=None) – Maximum number of neighbors to evaluate on each side of a point.

• fast_gaussian (bool, default=False) – Whether to use Schraudolph’s exponential approximation for Gaussian kernels.

• memory ({"auto", "high", "low"}, default="auto") – Memory strategy. "high" evaluates symmetric self-pairs once with per-thread buffers and caches external cutoff bounds. "low" avoids those buffers. "auto" chooses based on problem size and cutoff density.

Examples

Limit the Gaussian kernel to nearby samples:

>>> model = ApproximateKernelDensity(
...     bandwidth=0.2, cutoff=3.0, max_neighbors=2
... ).fit([0.0, 0.1, 0.4, 0.9, 1.0])
>>> model.evaluate([0.2, 0.8]).shape
(2,)
>>> model.self_density().shape
(5,)

fit(X, y=None)

Sort and store the training samples.

evaluate(X)

Return approximate density values at X.

self_density()

Return approximate leave-one-out density in original input order.

score_samples(X)

Return approximate log-density values at X.

score(X, y=None)

Return the total approximate log-likelihood of X.

class kern.BoundedKernelDensity(bandwidth=0.1, kernel='gaussian', method='reflected')

One-dimensional KDE for data on the [0, 1] unit interval.

method=None uses the regular unbounded kernel density estimator. method="reflected" works with every symmetric standard kernel. It uses the reflection construction for support constraints [Schuster 1985]. method="beta" uses the sample-centered Beta kernel.

Parameters:

• bandwidth (float, default=0.1) – Kernel bandwidth.

• kernel (str, default="gaussian") – Kernel name used by the reflected and regular methods.

• method ({None, "reflected", "beta"}, default="reflected") – Boundary correction method. None uses the regular unbounded KDE. "reflected" works with every symmetric standard kernel. "beta" uses the boundary-aware Beta kernel.

Examples

Fit a reflected KDE on samples inside the unit interval:

>>> model = BoundedKernelDensity(bandwidth=0.1).fit(
...     [0.05, 0.2, 0.6, 0.95]
... )
>>> model.evaluate([0.0, 0.5, 1.0]).shape
(3,)

Use the boundary-aware Beta kernel instead:

>>> beta_model = BoundedKernelDensity(method="beta", bandwidth=0.05).fit(
...     [0.1, 0.4, 0.8]
... )
>>> beta_model.score_samples([0.2, 0.7]).shape
(2,)

fit(X, y=None)

Store samples after checking the selected domain.

evaluate(X)

Return density values at X.

self_density()

Return leave-one-out density at each training sample.

score_samples(X)

Return log-density values at X.

score(X, y=None)

Return the total log-likelihood of X.

class kern.MultivariateKernelDensity(bandwidth=1.0, kernel='gaussian', block_size=32)

Multivariate KDE.

block_size controls how many query rows reuse each cached data block. Values from 16 to 64 are usually useful; the default is 32.

Parameters:

• bandwidth (float, default=1.0) – Kernel bandwidth.

• kernel (str, default="gaussian") – Kernel name.

• block_size (int, default=32) – Number of query rows that reuse each cached data block. Values from 16 to 64 are usually useful.

Examples

Fit a two-dimensional estimator and evaluate query rows:

>>> X = [[0.0, 0.0], [0.2, 0.1], [1.0, 0.9]]
>>> model = MultivariateKernelDensity(bandwidth=0.3).fit(X)
>>> model.evaluate([[0.1, 0.1], [0.8, 0.8]]).shape
(2,)
>>> model.n_features_in_
2

fit(X, y=None)

Store a row-major sample matrix.

evaluate(X)

Return density values at rows of X.

self_density()

Return leave-one-out density at each training row.

score_samples(X)

Return log-density values at rows of X.

score(X, y=None)

Return the total log-likelihood of X.

class kern.BandwidthSelector(grid=None, kernel='gaussian', cv='loo', parallel='auto', bounded=False, bounded_method='reflected')

Select a bandwidth for one kernel using log-likelihood.

Parameters:

• grid (array-like or None, default=None) – Candidate positive bandwidths. When omitted, default_bandwidth_grid() creates a data-scaled logarithmic grid during fit().

• kernel (str, default="gaussian") – Kernel used for every bandwidth candidate except Beta-kernel bounded selection.

• cv ("loo" or int, default="loo") – Leave-one-out or the number of folds.

• parallel ({"auto", "grid", "evaluation"}, default="auto") – Parallelize bandwidth candidates or each individual LOO/k-fold evaluation.

• bounded (bool, default=False) – Whether to select bandwidths for BoundedKernelDensity.

• bounded_method ({None, "reflected", "beta"}, default="reflected") – Boundary correction method used when bounded=True.

Examples

Use the default grid:

>>> selector = BandwidthSelector(kernel="cosine").fit(
...     [0.0, 0.1, 0.4, 0.8, 1.0]
... )
>>> selector.best_bandwidth_ in selector.grid_
True

Or provide an explicit grid:

>>> selector = BandwidthSelector(grid=[0.1, 0.2, 0.4]).fit(
...     [0.0, 0.1, 0.4, 0.8, 1.0]
... )

fit(X, y=None)

Score the grid and fit the best exact one-dimensional estimator.

evaluate(X)

Evaluate the selected estimator.

score_samples(X)

Return log-density values from the selected estimator.

self_density()

Return leave-one-out density from the selected estimator.

score(X, y=None)

Return total log-likelihood from the selected estimator.

Bandwidth grids

kern.default_bandwidth_grid(X, size=64, minimum=None, maximum=None)

Create a data-scaled logarithmic bandwidth grid.

The default range is centered on Silverman’s robust normal-reference bandwidth [Silverman 1986] and spans a factor of four in each direction.

Parameters:

• X (array-like) – One-dimensional training samples.

• size (int, default=64) – Number of grid values.

• minimum (float or None, default=None) – Smallest bandwidth. Uses one quarter of the reference bandwidth when omitted.

• maximum (float or None, default=None) – Largest bandwidth. Uses four times the reference bandwidth when omitted.

Returns:

C-contiguous positive float64 bandwidths.

Return type:

numpy.ndarray

Examples

>>> grid = default_bandwidth_grid([0.0, 0.2, 0.8, 1.0], size=8)
>>> grid.shape
(8,)

Build features

kern.has_openmp()

Return whether the current build uses OpenMP.

kern.has_blas()

Return whether the current build uses BLAS.