Kernel Density Estimation (ligo.skymap.kde)

class ligo.skymap.kde.BoundedKDE(pts, low=-inf, high=inf, periodic=False, bw_method=None)

Bases: gaussian_kde

Density estimation using a KDE on bounded domains.

Bounds can be any combination of low or high (if no bound, set to float('inf') or float('-inf')), and can be periodic or non-periodic. Cannot handle topologies that have multi-dimensional periodicities; will only handle topologies that are direct products of (arbitrary numbers of) R, [0,1], and S1.

Parameters:

ptsnumpy.ndarray

(Ndim, Npts) shaped array of points (as in gaussian_kde).

low

Lower bounds; if None, assume no lower bounds.

high

Upper bounds; if None, assume no upper bounds.

periodic

Boolean array giving periodicity in each dimension; if None assume no dimension is periodic.

bw_methodoptional

Bandwidth estimation method (see gaussian_kde).

evaluate(pts)

Evaluate the KDE at the given points.

quantile(pt)

Quantile of pt, evaluated by a greedy algorithm.

Parameters:

pt

The point at which the quantile value is to be computed.

Notes

The quantile of pt is the fraction of points used to construct the KDE that have a lower KDE density than pt.

class ligo.skymap.kde.Clustered2DSkyKDE(pts, *args, **kwargs)

Bases: SkyKDE

Represents a kernel-density estimate of a sky-position PDF that has been decomposed into clusters, using a different kernel for each cluster.

The estimated PDF is

\[p\left( \vec{\theta} \right) = \sum_{i = 0}^{k-1} \frac{N_i}{N} \sum_{\vec{x} \in C_i} N\left[\vec{x}, \Sigma_i\right]\left( \vec{\theta} \right)\]

where \(C_i\) is the set of points belonging to cluster \(i\), \(N_i\) is the number of points in this cluster, \(\Sigma_i\) is the optimally-converging KDE covariance associated to cluster \(i\).

The number of clusters, \(k\) is chosen to maximize the BIC for the given set of points being drawn from the clustered KDE. The points are assigned to clusters using the k-means algorithm, with a decorrelated metric. The overall clustering behavior is similar to the well-known X-Means algorithm.

classmethod transform(pts)

Override in sub-classes to transform points.

class ligo.skymap.kde.Clustered2Plus1DSkyKDE(pts, max_k=40, trials=5, assign=None, jobs=1)

Bases: Clustered3DSkyKDE

A hybrid sky map estimator that uses a 2D clustered KDE for the marginal distribution as a function of (RA, Dec) and a 3D clustered KDE for the conditional distance distribution.

posterior_spherical(pts)

Evaluate the posterior probability density in spherical polar coordinates, as a function of (ra, dec, distance).

class ligo.skymap.kde.Clustered3DSkyKDE(pts, max_k=40, trials=5, assign=None, jobs=1)

Bases: SkyKDE

Like Clustered2DSkyKDE, but clusters in 3D space. Can compute volumetric posterior density (per cubic Mpc), and also produce Healpix maps of the mean and standard deviation of the log-distance.

as_healpix(top_nside=16)

Return a HEALPix multi-order map of the posterior density and conditional distance distribution parameters.

posterior_spherical(pts)

Evaluate the posterior probability density in spherical polar coordinates, as a function of (ra, dec, distance).

classmethod transform(pts)

Override in sub-classes to transform points.