1 datasets.topology

datasets.topology

Read-only cross-store topology projections for scientific dataset inspection.

The topology joins rollout lineage to immutable VIN offline stores by the canonical VIN manifest hash. It reads manifests, indexes, split filenames, and artifact existence only; it never opens heavy candidate arrays or mutates a store. Streamlit, Rich CLIs, and JSON exporters consume the same presentation- neutral nodes, edges, modality rows, and selected-source evidence.

1.1 Attributes

Name Description
TopologyAvailability Whether a topology node is physically present or only declared/referenced.
TopologyResolution How one topology edge was established without inventing physical linkage.
TopologyRole Scientific role of one persisted or referenced modality.

1.2 Classes

Name Description
DatasetTopology Immutable aggregate topology and selected-source drill-down projection.
DatasetTopologyEdge One classified relationship between two topology nodes.
DatasetTopologyNode One store, artifact, identity, or modality in the cross-store graph.

1.2.1 DatasetTopology

datasets.topology.DatasetTopology(
    nodes,
    edges,
    sources=(),
    selected_source_row_id=None,
)

Immutable aggregate topology and selected-source drill-down projection.

1.2.1.1 Attributes

Name Description
nodes Graph nodes in deterministic construction order.
edges Classified graph edges in deterministic construction order.
sources Lightweight rollout source rows augmented with VIN resolution evidence.
selected_source_row_id Optional rollout source row expanded into exact sample and artifact nodes.

1.2.1.2 Methods

Name Description
node_rows Return complete graph-node rows without heavy payload data.
edge_rows Return complete classified graph-edge rows.
aggregate_node_rows Return graph nodes with shard-repeated VIN blocks grouped by role.
aggregate_edge_rows Return classified edges for aggregate_node_rows.
modality_rows Return the actor/oracle/derived/provenance modality matrix.
source_rows Return all lightweight source identities for drill-down selection.
sankey_data Return Plotly go.Sankey-compatible node and link keyword data.
to_jsonable Return the complete deterministic topology evidence projection.
plain_text_tree Render a compact Rich-compatible tree through :mod:rich_summary.
1.2.1.2.1 node_rows
datasets.topology.DatasetTopology.node_rows()

Return complete graph-node rows without heavy payload data.

1.2.1.2.2 edge_rows
datasets.topology.DatasetTopology.edge_rows()

Return complete classified graph-edge rows.

1.2.1.2.3 aggregate_node_rows
datasets.topology.DatasetTopology.aggregate_node_rows()

Return graph nodes with shard-repeated VIN blocks grouped by role.

1.2.1.2.4 aggregate_edge_rows
datasets.topology.DatasetTopology.aggregate_edge_rows()

Return classified edges for aggregate_node_rows.

1.2.1.2.5 modality_rows
datasets.topology.DatasetTopology.modality_rows()

Return the actor/oracle/derived/provenance modality matrix.

1.2.1.2.6 source_rows
datasets.topology.DatasetTopology.source_rows()

Return all lightweight source identities for drill-down selection.

1.2.1.2.7 sankey_data
datasets.topology.DatasetTopology.sankey_data()

Return Plotly go.Sankey-compatible node and link keyword data.

1.2.1.2.8 to_jsonable
datasets.topology.DatasetTopology.to_jsonable()

Return the complete deterministic topology evidence projection.

1.2.1.2.9 plain_text_tree
datasets.topology.DatasetTopology.plain_text_tree()

Render a compact Rich-compatible tree through :mod:rich_summary.

1.2.2 DatasetTopologyEdge

datasets.topology.DatasetTopologyEdge(
    source,
    target,
    relation,
    resolution,
    evidence=None,
)

One classified relationship between two topology nodes.

1.2.2.1 Attributes

Name Description
source Source node identifier.
target Target node identifier.
relation Domain relationship, for example resolves manifest hash.
resolution Evidence strength and local resolution outcome.
evidence Hash, path, identity, or concise reason supporting the classification.

1.2.2.2 Methods

Name Description
to_row Return a deterministic JSON-compatible edge row.
1.2.2.2.1 to_row
datasets.topology.DatasetTopologyEdge.to_row()

Return a deterministic JSON-compatible edge row.

1.2.3 DatasetTopologyNode

datasets.topology.DatasetTopologyNode(
    node_id,
    label,
    kind,
    role,
    availability,
    path=None,
    modality=None,
    details=dict(),
)

One store, artifact, identity, or modality in the cross-store graph.

1.2.3.1 Attributes

Name Description
node_id Stable graph-local identifier.
label Compact human-readable label.
kind Structural kind such as rollout store, VIN manifest, or mesh.
role Scientific evidence boundary represented by this node.
availability Physical or declared availability in the inspected local workspace.
path Resolved local path when a meaningful path is known.
modality Modality-matrix label; None excludes structural-only nodes.
details Small JSON-compatible evidence payload; never contains heavy arrays.

1.2.3.2 Methods

Name Description
to_row Return a deterministic JSON-compatible node row.
1.2.3.2.1 to_row
datasets.topology.DatasetTopologyNode.to_row()

Return a deterministic JSON-compatible node row.

1.3 Functions

Name Description
build_dataset_topology Build a read-only cross-store dataset and artifact topology.

1.3.1 build_dataset_topology

datasets.topology.build_dataset_topology(
    rollout_store_dir=None,
    vin_store_dirs=(),
    path_config=None,
    selected_source_row_id=None,
    report_bundle_paths=(),
    rerun_recording_paths=(),
)

Build a read-only cross-store dataset and artifact topology.

1.3.1.1 Parameters

Name Type Description Default
rollout_store_dir Path | str | None Optional rollout Zarr directory. Only its sidecar manifest and group markers are inspected. None
vin_store_dirs Sequence[Path | str] Candidate VIN offline-store roots matched by canonical manifest hash. Pass aria_nbv.data_handling.vin_store.store.discover_vin_store_dirs output when the app should search a cache root. ()
path_config PathConfig | None Filesystem resolver for ATEK and mesh locations. None
selected_source_row_id int | None Optional rollout source row to expand into its exact VIN sample, shard, scene, snippet, and mesh links. None
report_bundle_paths Sequence[Path | str] Known evidence-bundle paths linked to the rollout. ()
rerun_recording_paths Sequence[Path | str] Known .rrd paths linked to the rollout. ()

1.3.1.2 Returns

Name Type Description
DatasetTopology class:DatasetTopology with aggregate graph rows, modality rows,
DatasetTopology selected-source evidence, JSON, Sankey, and Rich-tree projections.

1.3.1.3 Notes

A matching identifier never implies a physical link. Exact unique manifest hashes become resolved pointer edges; duplicates are ambiguous and absent local artifacts remain missing.

Back to top