OnlineKDE

OnlineKDE(cvSpace, compressionThreshold=1.0, useExistingBandwidths=True, kernelShape='gaussian', minBandwidth=0.0)

Online kernel density estimate with on-the-fly kernel compression.

Parameters:

Name	Type	Description	Default
`cvSpace`		The `CVSpace` the estimate lives on.	required
`compressionThreshold`	`float`	Merge a new kernel into any existing kernel closer than this, measured as a Mahalanobis distance. Zero disables merging.	`1.0`
`useExistingBandwidths`	`bool`	Whether the nearest-neighbour search scales distances by the existing kernels' bandwidths rather than the incoming kernel's.	`True`
`kernelShape`	`str`	Either `"gaussian"` or `"compact"`.	`'gaussian'`
`minBandwidth`		Per-CV floor on the bandwidth of new kernels, applied after the Silverman shrink. Zero disables it.	`0.0`

iadd

__iadd__(other)

Absorb every kernel of other.

The weight moments are combined directly rather than re-accumulated from the absorbed kernels: a compressed kernel carries the combined weight of all its samples, so squaring it would overstate the sum of squared weights and collapse the effective sample size.

bandwidthFactor

bandwidthFactor(logWeight)

Silverman shrink factor for a new kernel of the given log weight.

Computed from this estimate's effective sample size with the new kernel's weight already counted, which is what update applies. The sample size also counts a prior weight w0 = 1, so kernels whose weights are small next to it barely shrink the bandwidth.

evaluate

evaluate(point)

Log of the normalized density at a single point.

getCorrectedLogPDF

getCorrectedLogPDF(pilotFactor=2.0, iterations=1, matchingScale=5.0)

Log density on the grid with the smoothing bias removed.

Kernel smoothing makes a density estimate too low on steep walls and too high at the bottom of basins, to order h^2 in the bandwidth. This applies the multiplicative bias correction of Jones, Linton and Nielsen (Biometrika 82, 327 (1995)), which cuts the bias to order h^4 while keeping the estimate positive:

A pilot estimate P~ uses the same kernels, broadened by pilotFactor, which keeps its noise low.
Each kernel's weight is divided by P~ at its center, so the reweighted samples follow P / P~, which is nearly flat.
Smoothing that ratio with the broad kernels costs little bias, and P~ times the smoothed ratio estimates P.

iterations repeats steps 2 and 3 with the result as the pilot. The product does not conserve probability locally, which would shift free energy differences between basins. So the result is finally rescaled to carry, at the length scale of matchingScale pilot bandwidths, the same probability as the uncorrected estimate, which conserves it kernel by kernel.

The correction needs the broadened kernels to stay narrow compared with the features of the density, say a third of a basin's width. Early in a run, when the kernels are still wide, it can do more harm than good.

Only the reported density changes; the bias built from getLogPDF does not. Costs a few evaluations of the broadened kernels on the grid and at the kernel centers. NaN with no kernels.

getLogMeanDensity

getLogMeanDensity()

Log of Z_n, the mean density over the compressed kernel centers.

NaN with no kernels deposited yet, for the same reason as getLogPDF: the mean over an empty set is undefined, so the log(0) and inf - inf along the way are expected, not warned about.

getLogPDF

getLogPDF()

Log of the normalized probability density on the grid.

With no kernels deposited yet, both operands are -inf and the result is the documented NaN (see getState's empty-KDE note) rather than an error; the subtraction is expected to be undefined here, not a sign that something went wrong.

getLogSumWeights

getLogSumWeights()

Log of the total sample weight, ln(sum_k w_k); -inf with no samples.

getNumKernels

getNumKernels()

Number of compressed kernels currently stored.

getNumSamples

getNumSamples()

Number of samples deposited, however the kernels were merged.

getState

getState()

Flat, npz-writable snapshot of this estimate.

The CVSpace is deliberately excluded: all walkers share identical CV definitions, so a reader constructs its own and calls setState.

setState

setState(state)

Restore from a snapshot, discarding current contents.

The snapshot comes from getState.

update

update(position, logWeight, variance, factor=None)

Deposit a kernel of the given log weight and per-CV variance.

The bandwidth is shrunk by factor when given, and otherwise by this estimate's own bandwidthFactor. Passing one lets an estimate that is part of a larger one size kernels by the larger one's sample size.