`MonteCarloSamples`#

class MonteCarloSamples(samples: ndarray, epoch: int, frame: str = 'J2000', definition=None, labels: Sequence[str] | None = None, weights: ndarray | None = None)#

Bases: UncertaintyQuantification

Uncertainty represented by a cloud of (optionally weighted) samples.

The samples \(\mathbf{x}^{(i)}\), \(i = 1, \ldots, N\), stand for the distribution directly, with no Gaussian assumption. With weights \(w_i\) (normalised to sum to one; equal weights when none are given) the moments are

\[\bar{\mathbf{x}} = \sum_i w_i\, \mathbf{x}^{(i)}, \qquad P = \frac{1}{1 - \sum_i w_i^2} \sum_i w_i (\mathbf{x}^{(i)} - \bar{\mathbf{x}}) (\mathbf{x}^{(i)} - \bar{\mathbf{x}})^T,\]

the unbiased weighted covariance, which reduces to the usual \(1/(N-1)\) sample covariance for equal weights.

Parameters:

samplesnp.ndarray: Samples, shape (n_samples, n_dimensions).
epochint: J2000 ephemeris time (ET seconds) the samples refer to.
framestr, optional: Reference frame. Defaults to 'J2000'.
definitionoptional: State or sequence definition. Defaults to None.
labelssequence of str, optional: Name of each dimension. Defaults to x0, x1, ....
weightsnp.ndarray, optional: Non-negative weight of each sample, shape (n_samples,). Normalised to sum to one. Defaults to equal weights.

Attributes:

definition: The sequence or state definition.
epoch: The epoch of the uncertainty representation.
frame: The reference frame of the uncertainty representation.
labels: Name of each dimension.
n_dimensions: Number of dimensions.
n_samples: Number of samples.
samples: The samples, shape (n_samples, n_dimensions).
weights: Normalised weight of each sample, shape (n_samples,).

Methods

`effective_sample_size`()	Kish effective sample size \(1 / \sum_i w_i^2\).
`get_covariance`()	Unbiased weighted sample covariance.
`get_mean`()	Weighted sample mean.
`get_percentile`(percentile)	Weighted percentile of each dimension.
`get_standard_deviations`()	Square root of the diagonal of `get_covariance()`.
`to_array`()	Return the samples as an array.
`to_covariance_matrix`()	Gaussian summary of the samples as a covariance matrix.

Raises:

SamplesShapeError: If samples is not a 2-D array of finite values.
LabelsSizeError: If labels does not name every dimension.
WeightsError: If weights is not one non-negative finite value per sample with a positive sum.

effective_sample_size() → float#

Kish effective sample size \(1 / \sum_i w_i^2\).

Returns:

float: n_samples for equal weights, smaller otherwise.

get_covariance() → ndarray#

Unbiased weighted sample covariance.

Returns:

np.ndarray: Covariance, shape (n_dimensions, n_dimensions).

get_mean() → ndarray#

Weighted sample mean.

Returns:

np.ndarray: Mean, shape (n_dimensions,).

get_percentile(percentile) → ndarray#

Weighted percentile of each dimension.

The sorted samples are placed at the weight accumulated before each one, rescaled to [0, 1], and the percentile is interpolated linearly between them. For equal weights these positions are \(i / (N - 1)\), so the result matches np.percentile(samples, percentile, axis=0).

Parameters:

percentilefloat or array_like: Percentile(s) in [0, 100].

Returns:

np.ndarray: Shape (n_dimensions,) for a scalar percentile, otherwise (len(percentile), n_dimensions).

get_standard_deviations() → ndarray#

Square root of the diagonal of get_covariance().

Returns:

np.ndarray: 1-sigma of each dimension, shape (n_dimensions,).

to_array() → ndarray#

Return the samples as an array.

Returns:

np.ndarray: The samples, shape (n_samples, n_dimensions).

to_covariance_matrix() → CovarianceMatrix#

Gaussian summary of the samples as a covariance matrix.

Returns:

CovarianceMatrix: get_covariance() with unitless entries, at this epoch and frame.

property definition#: The sequence or state definition.

property epoch: int#: The epoch of the uncertainty representation.

property frame: str#: The reference frame of the uncertainty representation.

property labels: list#: Name of each dimension.

property n_dimensions: int#: Number of dimensions.

property n_samples: int#: Number of samples.

property samples: ndarray#: The samples, shape (n_samples, n_dimensions).

property weights: ndarray#: Normalised weight of each sample, shape (n_samples,).

exception LabelsSizeError#

Bases: ValueError

The labels do not name every dimension of the samples.

exception SamplesShapeError#

Bases: ValueError

The samples are not a finite 2-D array.

exception WeightsError#

Bases: ValueError

The weights are not one non-negative finite value per sample.

MonteCarloSamples#

`MonteCarloSamples`#