relative_density

sofia_redux.toolkit.resampling.relative_density(sigma, counts, weight_sum, tolerance=None, max_dim=4)

Returns the relative density of samples compared to a uniform distribution.

The relative local density is defined as 1 for a uniform distribution, < 1 for a distribution that is sparse near the center, and > 1 when clustered around the center.

The sum of the distance_weights returned from a Gaussian weighting function on the samples is required for this calculation. The weighting function should be of the form:

\[w(\Delta x) = exp \left( -\sum_{k=1}^{K}{\frac{-\Delta x_k^2}{2 \sigma_k^2}} \right)\]

over \(K\) dimensions where \(\Delta x_k\) is the offset of a sample in dimension \(k\) from the point of interest, and \(\sigma\) must be supplied to relative_density as sigma, where distance_weights = \(\sum_{i=1}^{N}{w(x_i)}\) and counts = \(N\). Note that \(\sigma\) and \(x\) must be scaled such that the principle axis of an ellipsoid window containing all samples are equal to unity (principle axis in dimension \(k\) is \(\Omega_k = 1\) such that \(\prod_{k=1}^{K}{\Omega_k} = 1\) below).

The local relative density is then given as:

\[\rho = \frac{\rho(\text{measured})}{\rho(\text{uniform})}\]

where,

\[\rho(\text{uniform}) = N \frac{\Gamma \left( 1 + \frac{K}{2} \right)} {\pi^{K/2} \prod_{k=1}^{K}{\Omega_k}}\]

\[\rho(\text{measured}) = \frac {\sum_{i=1}^{N}{w_i}} {\int \cdots \int_{R} w(\mathbf{\Delta x}) \, {dx}_1 \cdots {dx}_K}\]

and region \(R\) satisfies the requirement \(\| \mathbf{\Delta x} \|_2 \leq 1\)

Parameters:

sigmanp.ndarray (n_dimensions,)

The standard deviation of the Gaussian weighting function used to calculate the distance_weights for each dimension.

countsint or float or numpy.ndarray (N,)

The number of data samples included in the sum of distance weights.

weight_sumint or float or numpy.ndarray (N,)

The sum of weights as returned from a Gaussian weighting function.

tolerancefloat, optional

Relative error tolerance passed to scipy.integrate.quad when determining the integral of the weighting function. The default of 10^(2*dim - 7) determined by testing, balancing precision with speed and convergence.

max_dimint, optional

If the number of dimensions is greater than max_dim, do not attempt to calculate the relative density since the integral calculation is unlikely to converge and will take a vast amount of time. The return output will be 1.0 or an array of ones (N,). The maximum recommended number of dimensions is 4 (default).

Returns:

float or numpy.ndarray of float64 (N,)

The relative density.