adam_core.coordinates.covariances module

adam_core.coordinates.covariances.sigmas_to_covariances(sigmas: ndarray) → ndarray

Convert an array of standard deviations to an array of covariance matrices. Non-diagonal elements are set to zero.

Parameters:

sigmas (numpy.ndarray (N, D)) – Standard deviations for N coordinates in D dimensions.

Returns:

covariances – Covariance matrices for N coordinates in D dimensions.

Return type:

numpy.ndarray (N, D, D)

class adam_core.coordinates.covariances.CoordinateCovariances(table: Table, **kwargs: int | float | str)

Bases: Table

values

A column for storing large lists of values (over 2³¹ objects).

Unless you need to represent data with more than 2**31 elements, prefer ListColumn.

The values in the list can be of any type.

Note that all quivr Tables are storing lists of values, so this column type is only useful for storing lists of lists.

Parameters:

• value_type – The type of the values in the list.

• nullable – Whether the list can contain null values.

• metadata – A dictionary of metadata to attach to the column.

• validator – A validator to run against the column’s values.

property sigmas

to_matrix() → ndarray

Return the covariance matrices as a 3D array of shape (N, 6, 6).

Returns:

covariances – Covariance matrices for N coordinates in 6 dimensions.

Return type:

numpy.ndarray (N, 6, 6)

classmethod from_matrix(covariances: ndarray) → CoordinateCovariances

Create a Covariances object from a 3D array of covariance matrices.

Parameters:

covariances (numpy.ndarray (N, 6, 6)) – Covariance matrices for N coordinates in 6 dimensions.

Returns:

covariances – Covariance matrices for N coordinates in 6 dimensions.

Return type:

Covariances

:raises ValueError : If the covariance matrices are not (N, 6, 6):

classmethod from_sigmas(sigmas: ndarray) → CoordinateCovariances

Create a Covariances object from a 2D array of sigmas.

Parameters:

sigmas (numpy.ndarray (N, 6)) – Array of 1-sigma uncertainties for N coordinates in 6 dimensions.

Returns:

covariances – Covariance matrices with the diagonal elements set to the squares of the input sigmas.

Return type:

Covariances

classmethod nulls(length: int) → CoordinateCovariances

Create a Covariances object with all covariance matrix elements set to NaN. :param length: Number of coordinates. :type length: int

Returns:

covariances – Covariance matrices for N coordinates in 6 dimensions.

Return type:

CoordinateCovariances

is_all_nan() → bool

Check if all covariance matrix values are NaN.

Returns:

is_all_nan – True if all covariance matrix elements are NaN, False otherwise.

Return type:

bool

schema: ClassVar[pa.Schema] = values: large_list<item: double>   child 0, item: double

adam_core.coordinates.covariances.make_positive_semidefinite(cov: ndarray, semidef_tol: float = 1e-15) → ndarray

Adjust a covariance matrix that is non positive semidefinite within a given tolerance, by flipping the sign of the negative eigenvalues. This can occur when the covariance matrix inludes values that are close to zero, which results in very small negative numbers.

Parameters:

• cov (~numpy.ndarray (D, D)) – Covariance matrix to adjust.

• tol (float, optional) – Tolerance for eigenvalues close to zero.

Returns:

cov_psd – Positive semidefinite covariance matrix.

Return type:

~numpy.ndarray (D, D)

adam_core.coordinates.covariances.sample_covariance_random(mean: ndarray, cov: ndarray, num_samples: int = 10000, seed: int | None = None, semidef_tol: float | None = 1e-15) → Tuple[ndarray, ndarray, ndarray]

Sample a multivariate Gaussian distribution with given mean and covariances.

The returned weights will be equal to 1 / num_samples so that each sample is equally weighted. Weights are returned from this function so its interface is identical to that of ~adam_core.coordinates.covariances.sample_covariance_sigma_points.

Parameters:

• mean (~numpy.ndarray (D)) – Multivariate mean of the Gaussian distribution.

• cov (~numpy.ndarray (D, D)) – Multivariate variance-covariance matrix of the Gaussian distribution.

• num_samples (int, optional) – Number of samples to draw from the distribution.

• seed (int, optional) – Seed for the random number generator.

• semidef_tol (float, optional) – Tolerance for eigenvalues close to zero.

Returns:

• samples (~numpy.ndarray (num_samples, D)) – The drawn samples row-by-row.

• W (~numpy.ndarray (num_samples)) – Weights of the samples.

• W_cov (~numpy.ndarray (num_samples)) – Weights of the samples to reconstruct covariance matrix.

:raises ValueError : If the covariance matrix is not positive semidefinite, within the given tolerance.:

adam_core.coordinates.covariances.sample_covariance_sigma_points(mean: ndarray, cov: ndarray, alpha: float = 1, beta: float = 0.0, kappa: float = 0.0) → Tuple[ndarray, ndarray, ndarray]

Create sigma-point samples of a multivariate Gaussian distribution with given mean and covariances.

Parameters:

• mean (~numpy.ndarray (D)) – Multivariate mean of the Gaussian distribution.

• cov (~numpy.ndarray (D, D)) – Multivariate variance-covariance matrix of the Gaussian distribution.

• alpha (float, optional) – Spread of the sigma points between 1e^-2 and 1.

• beta (float, optional) – Prior knowledge of the distribution usually set to 2 for a Gaussian.

• kappa (float, optional) – Secondary scaling parameter usually set to 0.

Returns:

• sigma_points (~numpy.ndarray (2 * D + 1, D)) – Sigma points drawn from the distribution.

• W (~numpy.ndarray (2 * D + 1)) – Weights of the sigma points.

• W_cov (~numpy.ndarray (2 * D + 1)) – Weights of the sigma points to reconstruct covariance matrix.

References

[1] Wan, E. A; Van Der Merwe, R. (2000). The unscented Kalman filter for nonlinear estimation.

Proceedings of the IEEE 2000 Adaptive Systems for Signal Processing, Communications, and Control Symposium, 153-158. https://doi.org/10.1109/ASSPCC.2000.882463

adam_core.coordinates.covariances.weighted_mean(samples: ndarray, W: ndarray) → ndarray

Calculate the weighted mean of a set of samples.

Parameters:

• samples (~numpy.ndarray (N, D)) – Samples drawn from the distribution (these can be randomly drawn or sigma points)

• W (~numpy.ndarray (N)) – Weights of the samples.

Returns:

mean – Mean calculated from the samples and weights.

Return type:

~numpy.ndarray (D)

adam_core.coordinates.covariances.weighted_covariance(mean: ndarray, samples: ndarray, W_cov: ndarray) → ndarray

Calculate a covariance matrix from samples and their corresponding weights.

Parameters:

• mean (~numpy.ndarray (D)) – Mean calculated from the samples and weights. See ~adam_core.coordinates.covariances.weighted_mean.

• samples (~numpy.ndarray (N, D)) – Samples drawn from the distribution (these can be randomly drawn or sigma points)

• W_cov (~numpy.ndarray (N)) – Weights of the samples to reconstruct covariance matrix.

Returns:

cov – Covariance matrix calculated from the samples and weights.

Return type:

~numpy.ndarray (D, D)

adam_core.coordinates.covariances.transform_covariances_sampling(coords: ndarray, covariances: ndarray, func: Callable, num_samples: int = 100000) → MaskedArray

Transform covariance matrices by sampling the transformation function.

Parameters:

• coords (~numpy.ndarray (N, D)) – Coordinates that correspond to the input covariance matrices.

• covariances (~numpy.ndarray (N, D, D)) – Covariance matrices to transform via sampling.

• func (function) – A function that takes coords (N, D) as input and returns the transformed coordinates (N, D). See for example: thor.coordinates.cartesian_to_spherical or thor.coordinates.cartesian_to_keplerian.

• num_samples (int, optional) – The number of samples to draw.

Returns:

covariances_out – Transformed covariance matrices.

Return type:

~numpy.ndarray (N, D, D)

adam_core.coordinates.covariances.transform_covariances_jacobian(coords: ndarray, covariances: ndarray, _func: Callable, **kwargs) → ndarray

Transform covariance matrices by calculating the Jacobian of the transformation function using ~jax.jacfwd.

Parameters:

• coords (~numpy.ndarray (N, D)) – Coordinates that correspond to the input covariance matrices.

• covariances (~numpy.ndarray (N, D, D)) – Covariance matrices to transform via numerical differentiation.

• _func (function) – A function that takes a single coord (D) as input and return the transformed coordinate (D). See for example: thor.coordinates._cartesian_to_spherical or thor.coordinates._cartesian_to_keplerian.

Returns:

covariances_out – Transformed covariance matrices.

Return type:

~numpy.ndarray (N, D, D)