1 rollouts.inspection.scientific_diagnostics

rollouts.inspection.scientific_diagnostics

Factual motion and label-support diagnostics for one validated rollout.

These descriptive quantities help inspect generated data. They neither score the reconstruction nor establish that a learned policy can use the labels.

1.1 Classes

Name Description
FactualTailSupport Availability of observed selected-action chains, not counterfactual Q labels.
RolloutScientificDiagnostic Presentation-free descriptive evidence for one rollout.
StepScientificDiagnostic One factual state, with distinct proposal, action, and label populations.

1.1.1 FactualTailSupport

rollouts.inspection.scientific_diagnostics.FactualTailSupport(
    horizon,
    starting_states,
)

Availability of observed selected-action chains, not counterfactual Q labels.

1.1.1.1 Attributes

Name Description
horizon Number of consecutive selected acquisitions required.
starting_states States with this many observed selected acquisitions still available.

1.1.2 RolloutScientificDiagnostic

rollouts.inspection.scientific_diagnostics.RolloutScientificDiagnostic(
    rollout_row_id,
    steps,
    tails,
    physical_camera_motion_available,
    path_length_m,
    net_displacement_m,
    displacement_to_path_ratio,
)

Presentation-free descriptive evidence for one rollout.

Motion uses physical world-from-camera PoseTW layouts: row-major rotation in the first nine scalars, world translation in the last three. A missing physical root camera makes motion unavailable rather than mixing rig and camera frames. No timestamps are used, so these are pose increments, not speed, acceleration, or jerk.

1.1.2.1 Attributes

Name Description
rollout_row_id Source rollout identity in the validated store.
steps Observed step diagnostics in acquisition order.
tails Counts of factual selected-action tails at requested horizons.
physical_camera_motion_available Whether a physical root camera pose allowed consistent motion comparison.
path_length_m Sum of selected camera-origin displacements, or unavailable without a root camera.
net_displacement_m Distance from physical root camera origin to last selected origin.
displacement_to_path_ratio Net displacement / path length; unavailable when path length is zero.

1.1.3 StepScientificDiagnostic

rollouts.inspection.scientific_diagnostics.StepScientificDiagnostic(
    step_index,
    proposed_count,
    actor_valid_count,
    finite_gain_label_count,
    trainable_label_count,
    selected,
    selected_trainable,
    gain_p90_minus_p10,
    selected_gain_gap_to_best,
    translation_m,
    rotation_deg,
    revisit_prior_pose,
    backtracking,
)

One factual state, with distinct proposal, action, and label populations.

1.1.3.1 Attributes

Name Description
step_index Zero-based acquisition index in the selected trajectory.
proposed_count Number of shell-ordered proposed camera poses.
actor_valid_count Number of proposals passing the persisted actor-action mask.
finite_gain_label_count Actor-valid proposals with a finite one-step root-gain label.
trainable_label_count True Q-train mask count, or None when that mask was not supplied.
selected Whether this state has one persisted selected action.
selected_trainable Selected Q-train mask value, or None without mask or selection.
gain_p90_minus_p10 Finite actor-valid label spread; unavailable with fewer than two labels.
selected_gain_gap_to_best Best finite actor-valid gain minus selected gain; descriptive, not regret.
translation_m Selected physical-camera origin displacement from the preceding pose, in metres.
rotation_deg Geodesic SO(3) change of physical camera orientation, in degrees.
revisit_prior_pose Whether selected origin is within the threshold of an older, nonadjacent origin.
backtracking Whether consecutive translation vectors have a negative dot product.

1.2 Functions

Name Description
rollout_scientific_diagnostic Project factual motion and one-step label support from store-reader rows.

1.2.1 rollout_scientific_diagnostic

rollouts.inspection.scientific_diagnostics.rollout_scientific_diagnostic(
    rollout,
    steps,
    *,
    q_train_mask=None,
    tail_horizons=(1, 2, 3, 5, 8, 12, 16),
    revisit_radius_m=0.25,
)

Project factual motion and one-step label support from store-reader rows.

q_train_mask[s, a] follows the shell-ordered candidate axis of step s; it is the authoritative trainable-label mask. A finite gain on an actor-valid candidate is reported separately because it need not satisfy every training admission rule. For a requested horizon h, a starting state counts only if the following h steps all have selected actions.

Physical rotation is acos((trace(R_prev.T @ R_next) - 1) / 2). Revisits compare a selected origin with root/previous origins excluding the directly preceding state. Backtracking compares consecutive world translation vectors. Both are geometry proxies, not human-motion or collision proofs.

1.2.1.1 Parameters

Name Type Description Default
rollout StoredRollout One validated persisted rollout with a physical root camera pose when available. required
steps tuple[StoredStep, …] Its complete ordered persisted step rows, aligned exactly with rollout.step_row_positions. required
q_train_mask NDArray[np.bool_] | None Optional ndarray[bool, S, A] from the same store’s QH view; columns align with each step’s candidate shell. None
tail_horizons tuple[int, …] Positive unique acquisition horizons to count. (1, 2, 3, 5, 8, 12, 16)
revisit_radius_m float Nonnegative positional revisit threshold in metres. 0.25
Back to top