1 rollouts.inspection.measurement_comparison

rollouts.inspection.measurement_comparison

Decision-focused comparison of matched candidate measurements.

The reducer in this module never renders, backprojects, or scores geometry. It compares treatment outcomes only after a caller has bound both treatments to the same physical candidate, factual state, prepared root, target reference, and captured depth raster. This keeps measurement sensitivity distinct from candidate-generation or scene-population effects.

1.1 Classes

Name	Description
CandidateMeasurementOutcome	One treatment outcome for one physically identified candidate.
CandidateScoreDelta	Signed treatment-minus-control score for one measured pair.
MeasurementOperatingPointDecision	Bounded operating-point verdict under a predeclared panel rule.
MeasurementOutcomeStatus	Typed disposition of one planned candidate/treatment measurement.
MeasurementPanelComparison	Complete matched panel comparison with state and scene denominators.
MeasurementPhysicalIdentity	Physical evidence that must stay invariant across treatments.
MeasurementStageCost	Wall-clock costs for one outcome, with shared rendering explicit.
SceneMeasurementComparison	Aggregation of state-level decisions within one physical scene.
StateMeasurementComparison	Decision evidence for one factual state before scene aggregation.

1.1.1 CandidateMeasurementOutcome

rollouts.inspection.measurement_comparison.CandidateMeasurementOutcome(
    identity,
    treatment,
    backprojection_stride,
    status,
    reason,
    score,
    root_error_m2,
    successor_error_m2,
    accuracy_m2,
    completeness_m2,
    retained_points,
    cost,
)

One treatment outcome for one physically identified candidate.

1.1.1.1 Attributes

Name	Description
identity	Physical evidence identity shared by the matched treatment pair.
treatment	Non-empty operating-point name, such as stride2.
backprojection_stride	Positive pixel stride; one distinct value is required per treatment.
status	Typed disposition; raw strings are rejected at the public boundary.
reason	Failure reason, required for unavailable outcomes and absent when measured.
score	Finite target-root gain when measured; otherwise absent.
root_error_m2	Prepared root point-mesh error in square metres, or absent when unavailable.
successor_error_m2	Successor point-mesh error in square metres, or absent when unavailable.
accuracy_m2	Successor accuracy component in square metres, or absent when unavailable.
completeness_m2	Successor completeness component in square metres, or absent when unavailable.
retained_points	Nonnegative retained candidate-point count, or absent when unavailable.
cost	Measured shared and treatment-specific wall-clock costs.

1.1.2 CandidateScoreDelta

rollouts.inspection.measurement_comparison.CandidateScoreDelta(
    candidate_id,
    delta,
)

Signed treatment-minus-control score for one measured pair.

1.1.2.1 Attributes

Name	Description
candidate_id	Candidate identity within the compared factual state.
delta	Compared-treatment score minus control score.

1.1.3 MeasurementOperatingPointDecision

rollouts.inspection.measurement_comparison.MeasurementOperatingPointDecision()

Bounded operating-point verdict under a predeclared panel rule.

1.1.4 MeasurementOutcomeStatus

rollouts.inspection.measurement_comparison.MeasurementOutcomeStatus()

Typed disposition of one planned candidate/treatment measurement.

1.1.5 MeasurementPanelComparison

rollouts.inspection.measurement_comparison.MeasurementPanelComparison(
    control_treatment,
    compared_treatment,
    tie_tolerance,
    practical_regret_tolerance,
    minimum_time_saving_fraction,
    states,
    scenes,
    decision,
    decision_reason,
    measured_support_delta,
    measurement_time_saving_fraction,
)

Complete matched panel comparison with state and scene denominators.

1.1.5.1 Attributes

Name	Description
control_treatment	Name of the reference operating point.
compared_treatment	Name of the challenged operating point.
tie_tolerance	Absolute score band used for top ties and undefined near-constant ranks.
practical_regret_tolerance	Maximum admitted upper reference regret in score units.
minimum_time_saving_fraction	Required fractional reduction in treatment-specific wall time.
states	Per-state comparisons retaining planned and measured denominators.
scenes	State-first scene aggregates; candidate rows are never pooled directly.
decision	Bounded operating-point verdict under the declared panel rule.
decision_reason	Human-readable rule branch that determined decision.
measured_support_delta	Compared minus control measured-candidate count over the full panel.
measurement_time_saving_fraction	Exclusive-stage fractional saving, absent when control time is zero.

1.1.6 MeasurementPhysicalIdentity

rollouts.inspection.measurement_comparison.MeasurementPhysicalIdentity(
    scene_id,
    state_id,
    candidate_id,
    candidate_pose_sha256,
    state_sha256,
    root_points_sha256,
    target_mesh_vertices_sha256,
    target_mesh_faces_sha256,
    target_extent_sha256,
    depth_raster_sha256,
)

Physical evidence that must stay invariant across treatments.

1.1.6.1 Attributes

Name	Description
scene_id	Stable physical-scene identifier.
state_id	Stable factual-state identifier within scene_id.
candidate_id	Stable candidate identifier within the factual state.
candidate_pose_sha256	SHA-256 identity of the candidate world-camera pose tensor.
state_sha256	SHA-256 identity of the complete factual state used for scoring.
root_points_sha256	SHA-256 identity of the prepared root reconstruction points.
target_mesh_vertices_sha256	SHA-256 identity of the target-reference mesh vertices.
target_mesh_faces_sha256	SHA-256 identity of the target-reference mesh faces.
target_extent_sha256	SHA-256 identity of the target crop extent.
depth_raster_sha256	SHA-256 identity of the captured depth raster shared by treatments.

1.1.7 MeasurementStageCost

rollouts.inspection.measurement_comparison.MeasurementStageCost(
    shared_render_seconds,
    backproject_seconds,
    preparation_seconds,
    metric_seconds,
)

Wall-clock costs for one outcome, with shared rendering explicit.

Costs are attributed to one candidate outcome. shared_render_seconds is that candidate’s allocation of the one raster reused by both stride treatments; allocations across a factual state must sum to the raster’s measured render time. The remaining stages are treatment-specific. Failed attempts retain elapsed work in the stage where it occurred.

1.1.7.1 Attributes

Name	Description
shared_render_seconds	Allocated wall seconds from the one raster shared by both treatments.
backproject_seconds	Wall seconds spent in treatment-specific depth backprojection.
preparation_seconds	Wall seconds spent preparing treatment-specific metric inputs.
metric_seconds	Wall seconds spent evaluating treatment-specific metrics.
exclusive_seconds	Return treatment-specific work, excluding the shared render.

1.1.8 SceneMeasurementComparison

rollouts.inspection.measurement_comparison.SceneMeasurementComparison(
    scene_id,
    state_count,
    planned_candidate_count,
    measured_pair_count,
    rank_defined_state_count,
    practical_change_state_count,
    practical_comparable_state_count,
    mean_defined_spearman,
    median_reference_regret_min,
    max_reference_regret_max,
    shared_render_seconds,
    control_exclusive_seconds,
    treatment_exclusive_seconds,
)

Aggregation of state-level decisions within one physical scene.

1.1.8.1 Attributes

Name	Description
scene_id	Physical-scene identifier.
state_count	Number of factual states aggregated within the scene.
planned_candidate_count	All planned candidates across the scene’s states.
measured_pair_count	Candidates measured by both treatments across the scene’s states.
rank_defined_state_count	States with an identified rank correlation.
practical_change_state_count	Comparable states whose top-set change exceeds practical regret.
practical_comparable_state_count	States with enough common support for the practical-change statistic.
mean_defined_spearman	Mean of defined state Spearman values, absent when none are defined.
median_reference_regret_min	Median state minimum reference regret, absent without comparable states.
max_reference_regret_max	Largest state upper reference regret, absent without comparable states.
shared_render_seconds	Shared-raster wall seconds summed once across factual states.
control_exclusive_seconds	Control-only measurement-stage wall seconds across the scene.
treatment_exclusive_seconds	Compared-treatment-only measurement-stage wall seconds across the scene.

1.1.9 StateMeasurementComparison

rollouts.inspection.measurement_comparison.StateMeasurementComparison(
    scene_id,
    state_id,
    planned_candidate_count,
    measured_pair_count,
    control_measured_treatment_unavailable_count,
    treatment_measured_control_unavailable_count,
    execution_failure_count,
    control_outcomes,
    treatment_outcomes,
    rank_support_count,
    spearman,
    spearman_unavailable_reason,
    control_top_candidate_ids,
    treatment_top_candidate_ids,
    top_set_overlap_count,
    top_set_union_count,
    reference_regret_min,
    reference_regret_max,
    practical_decision_change,
    score_deltas,
    shared_render_seconds,
    control_exclusive_seconds,
    treatment_exclusive_seconds,
)

Decision evidence for one factual state before scene aggregation.

Rank, top-set, and regret fields describe only common measured support. Separate support-loss/gain counts prevent that intersection from being mistaken for the full treatment choice population.

1.1.9.1 Attributes

Name	Description
scene_id	Physical-scene identifier.
state_id	Factual-state identifier within the scene.
planned_candidate_count	All planned candidate identities, including unavailable measurements.
measured_pair_count	Candidates measured by both treatments.
control_measured_treatment_unavailable_count	Control-valid candidates unavailable under the compared treatment.
treatment_measured_control_unavailable_count	Compared-treatment-valid candidates unavailable under control.
execution_failure_count	Execution-failed treatment attempts across the planned population.
control_outcomes	Control outcome counts over all planned candidates.
treatment_outcomes	Compared-treatment outcome counts over all planned candidates.
rank_support_count	Common measured support used for rank and top-set statistics.
spearman	Common-support Spearman correlation, absent when rank is undefined.
spearman_unavailable_reason	Reason spearman is absent, otherwise absent itself.
control_top_candidate_ids	Control candidates within the declared absolute tie band.
treatment_top_candidate_ids	Compared-treatment candidates within the declared absolute tie band.
top_set_overlap_count	Identity overlap between common-support top sets.
top_set_union_count	Identity union size of common-support top sets.
reference_regret_min	Minimum control-score regret across the treatment top tie set.
reference_regret_max	Maximum control-score regret across the treatment top tie set.
practical_decision_change	Whether disjoint top sets exceed practical regret; absent without support.
score_deltas	Per-candidate score differences on common measured support.
shared_render_seconds	Wall seconds for shared rasters, counted once per factual state.
control_exclusive_seconds	Control-only measurement-stage wall seconds over planned candidates.
treatment_exclusive_seconds	Compared-treatment-only measurement-stage wall seconds over candidates.

1.2 Functions

Name	Description
compare_measurement_panel	Compare two treatments over a complete matched candidate panel.

1.2.1 compare_measurement_panel

rollouts.inspection.measurement_comparison.compare_measurement_panel(
    outcomes,
    *,
    control_treatment,
    compared_treatment,
    tie_tolerance,
    practical_regret_tolerance,
    minimum_time_saving_fraction,
)

Compare two treatments over a complete matched candidate panel.

Ranking uses only candidate identities measured by both treatments. Its denominator remains separate from the full planned population. Spearman is unavailable when fewer than two pairs exist or either score vector lies wholly inside the declared tie band. Top sets contain every candidate within tie_tolerance of that treatment’s maximum.

Reference regret evaluates the treatment top set under control scores. A tie therefore yields a range rather than an arbitrary winning row: control_max - max(control_at_treatment_top) through control_max - min(control_at_treatment_top). A state has a practical decision change only when the top sets are disjoint and the minimum regret exceeds practical_regret_tolerance.