1 reporting.broad_scene

reporting.broad_scene

Source-bound acquisition and export for broad rollout-scene evidence.

1.1 Classes

Name Description
BroadSceneReadout Immutable normalized tables and exact source identities for one queue.

1.1.1 BroadSceneReadout

reporting.broad_scene.BroadSceneReadout(
    source,
    attempts,
    stores,
    states,
    families,
    roots,
    prefixes,
    root_prefixes,
    root_marginals,
    root_family_opportunity,
    motion_steps,
    motion_stores,
    motion_roots,
)

Immutable normalized tables and exact source identities for one queue.

1.1.1.1 Attributes

Name Description
source Queue, ledger, lifecycle, and successful-store source identities.
attempts Every queue-ledger attempt, including rejected and failed attempts.
stores One row per canonical-valid successful store.
states One row per factual decision state in successful stores.
families One row per factual state and persisted candidate family.
roots One row per independent source root across repeated queue cycles.
prefixes One row per successful store and fixed historical factual prefix.
root_prefixes Historical prefix support and gain aggregated over repeated root cycles.
root_marginals Historical H12-to-H16 marginal support and gain by source root.
root_family_opportunity Descriptive candidate opportunity and selection by source root/family.
motion_steps One row per factual selected acquisition in successful stores.
motion_stores One row per successful store, including valid zero-step stores.
motion_roots Selected-motion support and tails reduced to independent source roots.

1.2 Functions

Name Description
broad_scene_metadata_identity Return a shallow cache key without validating queue stores.
broad_scene_motion_figures Build the shared source-root motion figure for export and Streamlit.
broad_scene_motion_summary Return motion support without mixing queue attempts and successful stores.
broad_scene_snapshot_identity Return the source and reducer identity used by retained UI results.
export_broad_scene_readout Write normalized CSV tables and one source-bound JSON index.
read_broad_scene_queue Validate and normalize a completed disk-bounded recipe queue.

1.2.1 broad_scene_metadata_identity

reporting.broad_scene.broad_scene_metadata_identity(
    queue_root,
    *,
    tiny_score_iqr=0.005,
    azimuth_bins=_DEFAULT_AZIMUTH_BINS,
    elevation_bins=_DEFAULT_ELEVATION_BINS,
    min_intervening_steps=_DEFAULT_MIN_INTERVENING_STEPS,
)

Return a shallow cache key without validating queue stores.

Small queue metadata and canonical store sidecars are content-bound while store directories are observed by filesystem identity. Full queue and store validation remains part of read_broad_scene_queue after explicit dispatch.

1.2.2 broad_scene_motion_figures

reporting.broad_scene.broad_scene_motion_figures(readout)

Build the shared source-root motion figure for export and Streamlit.

1.2.3 broad_scene_motion_summary

reporting.broad_scene.broad_scene_motion_summary(readout)

Return motion support without mixing queue attempts and successful stores.

Translation, SO(3) rotation, revisit, and occupancy distributions use one reduced value per source root. Observed event counts retain factual selected steps, while attempt counts retain rejected and failed ledger rows as a separate population. Target-frame angular cells measure selected-camera direction occupancy only; they do not measure target-surface visibility.

1.2.4 broad_scene_snapshot_identity

reporting.broad_scene.broad_scene_snapshot_identity(
    queue_root,
    *,
    tiny_score_iqr=0.005,
    azimuth_bins=_DEFAULT_AZIMUTH_BINS,
    elevation_bins=_DEFAULT_ELEVATION_BINS,
    min_intervening_steps=_DEFAULT_MIN_INTERVENING_STEPS,
)

Return the source and reducer identity used by retained UI results.

1.2.5 export_broad_scene_readout

reporting.broad_scene.export_broad_scene_readout(
    queue_root,
    output_dir,
    *,
    tiny_score_iqr=0.005,
    azimuth_bins=_DEFAULT_AZIMUTH_BINS,
    elevation_bins=_DEFAULT_ELEVATION_BINS,
    min_intervening_steps=_DEFAULT_MIN_INTERVENING_STEPS,
)

Write normalized CSV tables and one source-bound JSON index.

1.2.6 read_broad_scene_queue

reporting.broad_scene.read_broad_scene_queue(
    queue_root,
    *,
    tiny_score_iqr=0.005,
    azimuth_bins=_DEFAULT_AZIMUTH_BINS,
    elevation_bins=_DEFAULT_ELEVATION_BINS,
    min_intervening_steps=_DEFAULT_MIN_INTERVENING_STEPS,
)

Validate and normalize a completed disk-bounded recipe queue.

The ledger is a validated attempt prefix because queue contract v1 has no finite target count. Only succeeded rows may name stores, and every named store must match the queue snapshot’s canonical content identity before it contributes factual states. Rejected and failed rows remain in prefix accounting, while absent tails and whole-campaign efficiency remain unavailable.

Back to top