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(\overrightarrow{\theta }\right)=\sum _{i=0}^{k-1}\frac{N_i}{N}\sum _{\overrightarrow{x}\in C_i}N[\overrightarrow{x},{\mathrm{\Sigma }}_i]\left(\overrightarrow{\theta }\right)$$

where $C_i$ is the set of points belonging to cluster $i$, $N_i$ is the number of points in this cluster, ${\mathrm{\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.