upxo.pxtal.twinned_simple_3d.representativeness_metrics module
representativeness_metrics.py
A registry of two-sample distribution-comparison statistics, each
wrapped as a “higher score = higher representativeness” similarity –
for comparing a candidate (subset) property distribution against a
reference (parent) distribution. Decomposes
TwinnedSimple3DBase.compare_property_distributions’s bundled
3-metric score into individually selectable entries, and adds more
standard two-sample statistics on top.
- upxo.pxtal.twinned_simple_3d.representativeness_metrics.compute_all_selected(selected_keys, ref_vals, cand_vals, low_pct=0.0, high_pct=100.0, score_function='exp')[source]
Compute every selected representativeness metric comparing cand_vals (a subset’s property distribution) against ref_vals (the parent/reference distribution), after independently trimming each side to [low_pct, high_pct] percentiles of its own range (
TwinnedSimple3DBase.percentile_trim).- Parameters:
selected_keys (iterable of str) – Keys into METRIC_REGISTRY.
ref_vals (array-like) – Raw per-grain property values.
cand_vals (array-like) – Raw per-grain property values.
low_pct (float) – Percentile-of-range outlier trim, applied identically to both sides. (0, 100) is a no-op.
high_pct (float) – Percentile-of-range outlier trim, applied identically to both sides. (0, 100) is a no-op.
score_function (str) – ‘exp’ or ‘reciprocal’ – see
TwinnedSimple3DBase._squash_distance.
- Returns:
{metric_key: score}, one entry per requested key that both exists in METRIC_REGISTRY and computed successfully to a finite value. A metric that raises (e.g. too few points after trimming) OR returns NaN/inf (some statistics – e.g. Kruskal-Wallis on two literally-identical samples – degenerate to NaN rather than raising) is silently omitted rather than aborting the whole batch – callers should treat a missing key as “not computable for this pair”, not as an error. Empty dict if either side has fewer than 2 points after trimming.
- Return type: