Statistics

Statistical helper functions for comparing distributions and aligned histograms.

statistics

Generic statistical comparison helpers.

simtools.statistics.compare_histogram_counts(counts1, counts2, metric='ks', bin_edges=None)

Compare two aligned count distributions with a selected metric.

Parameters:

counts1array-like

Baseline distribution counts.

counts2array-like

Candidate distribution counts.

metric{“ks”, “jensen_shannon”, “wasserstein”}, optional

Metric used for the comparison. "ks" compares cumulative counts, "jensen_shannon" compares unordered categories, and "wasserstein" compares ordered support values.

bin_edgesarray-like, optional

Bin edges for the Wasserstein comparison. Required for that metric.

Returns:

dict

Metric result with valid and reason fields. Empty distributions return an invalid result; malformed distributions raise ValueError.

Raises:

ValueError

If the count arrays, metric, or bin edges are invalid.

simtools.statistics.compare_samples_with_statistics(baseline_samples, candidate_samples, bin_edges=None, metric='ks')

Compare two sample arrays using the selected metric and optional bin edges.

Parameters:

baseline_samplesnp.ndarray

Baseline sample values.

candidate_samplesnp.ndarray

Candidate sample values.

bin_edgesnp.ndarray

Histogram bin edges used to include aligned count metadata. Required for non-KS metrics.

metric{“ks”, “jensen_shannon”, “wasserstein”}, optional

Metric used for the comparison.

Returns:

dict

Comparison statistics and, when bin edges are provided, histogram metadata.

simtools.statistics.ks_test_samples(samples1, samples2)

Compute the Kolmogorov-Smirnov (KS) statistic and p-value for two 1D sample arrays.

Parameters:

samples1np.ndarray

First sample array.

samples2np.ndarray

Second sample array.

Returns:

ks_statisticfloat

KS statistic value.

ks_pvaluefloat

KS test p-value.