Diagnostics functions¶

mftt.first_moment_error(samples, target_mean=None)[source]¶

Compute the Euclidean error in the first moment.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud to assess.
target_mean (array-like, shape (input_dim,), optional) – Target mean; defaults to the zero vector.

Returns:

Euclidean norm of the mean error.

Return type:

float

mftt.second_moment_error(samples, target_cov=None, ddof=1)[source]¶

Compute the Frobenius error in the covariance.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud to assess.
target_cov (array-like, shape (input_dim, input_dim), optional) – Target covariance; defaults to identity.
ddof (int, default=1) – Delta degrees of freedom used for the sample covariance.

Returns:

Frobenius norm of the covariance error.

Return type:

float

mftt.forstner_distance(samples, target_cov=None, ddof=1, jitter=1e-10)[source]¶

Compute the Forstner distance from a sample to a target covariance.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud to assess.
target_cov (array-like, shape (input_dim, input_dim), optional) – Target covariance; defaults to identity.
ddof (int, default=1) – Delta degrees of freedom used for the sample covariance.
jitter (float, default=1e-10) – Positive regularization used in covariance square roots.

Returns:

Forstner distance between covariance matrices.

Return type:

float

mftt.squared_mmd_gaussian_kernel(samples, reference_samples=None, target_mean=None, target_cov=None, bandwidth=None, bandwidth_mode='median_heuristic', random_seed=0, bandwidth_subset_size=2000, full_matrix_threshold=4000, block_size=1024)[source]¶

Compute an unbiased squared MMD against a Gaussian reference.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud to assess.
reference_samples (array-like, optional) – Explicit Gaussian-reference samples. If omitted, samples are drawn from target_mean and target_cov.
target_mean (array-like, shape (input_dim,), optional) – Mean of generated reference samples; defaults to zero.
target_cov (array-like, shape (input_dim, input_dim), optional) – Covariance of generated reference samples; defaults to identity.
bandwidth (float, optional) – Positive kernel bandwidth. When omitted, the median heuristic is used.
bandwidth_mode ({"median_heuristic"}, default="median_heuristic") – Rule used when bandwidth is omitted.
random_seed (int, optional, default=0) – Seed for generated reference data and median-heuristic subsets.
bandwidth_subset_size (int, default=2000) – Maximum rows used by the median-heuristic calculation.
full_matrix_threshold (int, default=4000) – Use dense kernel matrices at or below this cloud size.
block_size (int, default=1024) – Block size for exact large-cloud kernel accumulation.

Returns:

Unbiased squared Gaussian-kernel MMD.

Return type:

float

mftt.multiscale_squared_mmd_gaussian_kernel(samples, bandwidths, reference_samples=None, target_mean=None, target_cov=None, random_seed=0, full_matrix_threshold=4000, block_size=1024)[source]¶

Compute unbiased squared MMD values for supplied bandwidths.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud to assess.
bandwidths (array-like, shape (n_bandwidths,)) – Positive Gaussian-kernel bandwidths.
reference_samples (array-like, optional) – Explicit reference cloud; otherwise a Gaussian cloud is generated.
target_mean (array-like, shape (input_dim,), optional) – Mean of generated reference samples; defaults to zero.
target_cov (array-like, shape (input_dim, input_dim), optional) – Covariance of generated reference samples; defaults to identity.
random_seed (int, optional, default=0) – Seed for generated reference samples.
full_matrix_threshold (int, default=4000) – Dense-kernel cutoff.
block_size (int, default=1024) – Block size for exact large-cloud accumulation.

Returns:

One unbiased squared MMD value per supplied bandwidth.

Return type:

numpy.ndarray, shape (n_bandwidths,)

mftt.gaussian_diagnostics(samples, target_mean=None, target_cov=None, ddof=1, jitter=1e-10, random_seed=0, bandwidth_subset_size=2000, full_matrix_threshold=4000, block_size=1024)[source]¶

Summarize how closely a sample cloud matches a Gaussian target.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud to assess.
target_mean (array-like, shape (input_dim,), optional) – Gaussian target mean; defaults to zero.
target_cov (array-like, shape (input_dim, input_dim), optional) – Gaussian target covariance; defaults to identity.
ddof (int, default=1) – Delta degrees of freedom for sample covariance.
jitter (float, default=1e-10) – Covariance regularization for the Forstner distance.
random_seed (int, optional, default=0) – Seed for MMD reference sampling.
bandwidth_subset_size (int, default=2000) – Median-heuristic subset limit.
full_matrix_threshold (int, default=4000) – Dense-kernel cutoff.
block_size (int, default=1024) – Block size for exact large-cloud MMD.

Returns:

Sample moments, target moments, moment errors, Forstner distance, MMD, and the bandwidth used.

Return type:

dict

mftt.map_gaussian_diagnostics(map_obj, target_samples, target_mean=None, target_cov=None, ddof=1, jitter=1e-10, random_seed=0, bandwidth_subset_size=2000, full_matrix_threshold=4000, block_size=1024)[source]¶

Push target samples through a trained map and summarize Gaussianity.

Parameters:

map_obj (TriangularMap, HierarchicalTriangularMap, or NonHierarchicalTriangularMap) – Trained map exposing evaluate from target to reference coordinates.
target_samples (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target samples evaluated by map_obj.
target_mean (array-like, shape (input_dim,), optional) – Gaussian reference mean; defaults to zero.
target_cov (array-like, shape (input_dim, input_dim), optional) – Gaussian reference covariance; defaults to identity.
ddof (int, default=1) – Delta degrees of freedom for sample covariance.
jitter (float, default=1e-10) – Covariance regularization for the Forstner distance.
random_seed (int, optional, default=0) – Seed for MMD reference sampling.
bandwidth_subset_size (int, default=2000) – Median-heuristic subset limit.
full_matrix_threshold (int, default=4000) – Dense-kernel cutoff.
block_size (int, default=1024) – Block size for exact large-cloud MMD.

Returns:

Gaussian diagnostics of mapped reference-space samples.

Return type:

dict

mftt.median_heuristic_bandwidth(samples, reference_samples=None, target_mean=None, target_cov=None, random_seed=0, bandwidth_subset_size=2000)[source]¶

Estimate a Gaussian-kernel bandwidth from samples and reference data.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Sample cloud used to estimate the bandwidth.
reference_samples (array-like, optional) – Reference cloud with the same coordinate dimension. When omitted, a Gaussian cloud is drawn from target_mean and target_cov.
target_mean (array-like, shape (input_dim,), optional) – Mean for generated Gaussian reference samples; defaults to zero.
target_cov (array-like, shape (input_dim, input_dim), optional) – Covariance for generated Gaussian reference samples; defaults to the identity.
random_seed (int, optional, default=0) – Seed used for generated reference samples and subset selection.
bandwidth_subset_size (int, default=2000) – Maximum number of rows used by the median-distance calculation.

Returns:

Positive median-heuristic bandwidth.

Return type:

float

mftt.sample_mean(samples)[source]¶

Compute the empirical mean of a sample cloud.

Parameters:: samples (array-like, shape (n_samples, input_dim)) – Samples in a common coordinate system.
Returns:: Empirical mean.
Return type:: numpy.ndarray, shape (input_dim,)

mftt.sample_covariance(samples, ddof=1)[source]¶

Compute the empirical covariance matrix of a sample cloud.

Parameters:

samples (array-like, shape (n_samples, input_dim)) – Samples in a common coordinate system.
ddof (int, default=1) – Delta degrees of freedom used in the covariance denominator.

Returns:

Empirical covariance.

Return type:

numpy.ndarray, shape (input_dim, input_dim)

Raises:

ValueError – If fewer than ddof + 1 rows are supplied.