upxo.pxtal.twinned_simple_3d.mc_qualification module

mc_qualification.py

Candidate representativeness scoring and shortlist ranking for the Monte-Carlo temporal-slice qualification stage of the twinned simple 3D pipeline: derived per-candidate statistics (scale calibration, rescaled property stats, EBSD-distribution comparisons) and the star-count / aggregate-score / coupled shortlist ranking built from them.

Ported from pxtal/twinned_simple_3d/gui/pages_mc.py (previously only reachable through MCCandidateSelectionPage/MCQualificationPage – none of the logic here has any GUI/Tkinter dependency).

upxo.pxtal.twinned_simple_3d.mc_qualification.ng_qualifies(ratio, tol_pct)

Whether a candidate’s Ng ratio falls within +/- tol_pct% of 1.0.

upxo.pxtal.twinned_simple_3d.mc_qualification.prop_qualifies(cmp_result, tol_pct)

Whether a candidate’s property ratio (from TwinnedSimple3DBase.compare_property_distributions) falls within +/- tol_pct% of 1.0.

upxo.pxtal.twinned_simple_3d.mc_qualification.property_tolerance_pct(shared_state, prop_name)

Per-property Property Tolerance, falling back to the single legacy MC_PROPERTY_TOLERANCE_PCT for any property that hasn’t been given its own entry in MC_PROPERTY_TOLERANCE_PCT_PER_PROP yet.

upxo.pxtal.twinned_simple_3d.mc_qualification.recompute_candidate_derived(pxt, candidates, prop_data, prop_names, outlier_trim_sides, scale_check_tolerance_pct, score_function='exp')

(Re)computes, for every candidate, the scale-factor calibration, the display-unit property stats, and the EBSD-distribution comparisons – everything that depends on outlier-trim sides / the Scale Check tolerance – from each candidate’s already-cached raw (voxel-unit) property stats (candidate[‘prop_stats_raw’]), without re-running the expensive 3D cross-sectional labelling (rank_temporal_slices_by_n / compute_slice_grain_properties).

outlier_trim_sides: {prop_name: {‘left’: bool, ‘right’: bool}}. score_function: ‘exp’ (default) or ‘reciprocal’ – see TwinnedSimple3DBase._squash_distance; controls how the representativeness_score in each property’s prop_compare entry is derived from its (dimensionless) Wasserstein/energy distances.

upxo.pxtal.twinned_simple_3d.mc_qualification.compute_shortlist_rows(candidates, prop_names, shared_state, selected_criteria=None)

Two ranking estimates plus a default ‘coupled’ one: star count as the primary sort key, aggregate score as the tie-breaker for the default view, with both individual rankings also reported so a candidate can be judged by either criterion alone.

aggregate_score: mean of per-metric “goodness” terms in [0, 1] – (1 - |Ng ratio - 1|, clipped at 0) for Ng, and KS similarity (already bounded [0, 1]) for each property. Kept dimensionless so Ng and every property contribute comparably to one blended score despite being in different units.

selected_criteria: optional set of criterion keys (‘ng’, property names, ‘scale_check’) to restrict n_stars/aggregate_score to – None (the default) means every available criterion.