offset_variance

sofia_redux.toolkit.resampling.offset_variance(coordinates, reference, mask=None, mean=None, sigma_inv=None, scale=1.0, dof=1)

Variance at reference coordinate derived from distribution uncertainty.

Given a distribution of coordinates (\(X\)), calculate the variance at a reference coordinate (\(X_{ref}\)) based upon the uncertainty in the coordinate distribution. Firstly, the distribution covariance matrix (\(\Sigma\)) is calculated by coordinate_covariance() enabling the variance at the reference position to be given as:

\[V(X_{ref}) = (X_{ref} - E[X])^{T} \Sigma^{-1} (X_{ref} - E[X])\]

If the expected value of the distribution is known (\(E[X]\)) or pre-calculated, it can be passed in to the function using the mean optional parameter along with the lost degrees of freedom (dof) spent in determining \(E[X]\). If not, the default is to use \(\bar{X}\) and dof = 1.

The user may optionally specify a scale factor (\(\beta\)) such that:

\[V(X_{ref}) = (\beta(X_{ref} - E[X]))^{T} \Sigma^{-1} (\beta(X_{ref} - E[X]))\]

or:

\[V(X_{ref}) = \beta^2 (X_{ref} - E[X])^{T} \Sigma^{-1} (X_{ref} - E[X])\]

Parameters:

coordinatesnumpy.ndarray (n_dimensions, n_coordinates)

The coordinates of the distribution.

referencenumpy.ndarray (n_dimensions,)

The reference coordinate.

masknumpy.ndarray of bool (n_coordinates,), optional

An array of bool values where True indicates a coordinate should be included in the calculation, and False indicates that a coordinate should be ignored. By default, all coordinates are included.

meannumpy.ndarray (n_dimensions,), optional

The mean of the coordinate distribution in each dimension. If not provided, the expected value in each dimension will be calculated using coordinate_mean().

scaleint or float, optional

The scaling factor described above.

dofint or float, optional

The lost degrees of freedom, typically 1 to indicate that the population mean is not known and is replaced by the sample mean.

sigma_invnumpy.ndarray (n_dimensions, n_dimensions), optional

If the covariance matrix of the coordinate distribution has already been calculated, the matrix inverse may be passed in as sigma_inv for speed.

Returns:

variancefloat

The variance at the reference coordinate determined from the coordinate distribution.