1 reporting.results

reporting.results

Immutable values, tables, figures, and provenance for scientific reports.

1.1 Classes

Name	Description
NamedQuantity	One named scalar linked to provenance and optional canonical notation.
ReportColumn	One ordered table column and its canonical notation binding.
ReportExplanation	Presentation-free interpretation attached to one scientific result.
ReportFigure	Canonical Plotly figure shared by Streamlit and static export.
ReportSnapshot	Immutable transaction consumed by Streamlit and static/Typst export.
ReportTable	Canonical immutable table with typed scalar cells.
SourceIdentity	Frozen identity and provenance for one materialized evidence source.

1.1.1 NamedQuantity

reporting.results.NamedQuantity(
    id,
    value,
    unit,
    n,
    aggregation,
    source_ids,
    symbol_id,
)

One named scalar linked to provenance and optional canonical notation.

1.1.1.1 Attributes

Name	Description
id	Globally unique result identifier.
value	Typed scalar; missing values remain None rather than fabricated zeroes.
unit	Physical or reporting unit, when meaningful.
n	Population size underlying the quantity, when available.
aggregation	Code-owned aggregation name such as mean or count.
source_ids	Source identities that support the value.
symbol_id	Canonical Typst symbol ID; None is an explicit operational opt-out.

1.1.2 ReportColumn

reporting.results.ReportColumn(id, symbol_id)

One ordered table column and its canonical notation binding.

1.1.2.1 Attributes

Name	Description
id	Persisted column identifier.
symbol_id	Canonical Typst symbol ID; None is an explicit operational opt-out.

1.1.3 ReportExplanation

reporting.results.ReportExplanation(
    metric_id,
    question,
    answer,
    narrative,
    evidence_role,
    population,
    unit,
    support_result_ids,
    source_fields,
    theory,
)

Presentation-free interpretation attached to one scientific result.

The explanation names supporting result IDs instead of rebuilding factual counts or reductions. Its theory field carries registry identifiers only; aria_nbv.reporting.notation.resolve_theory validates and projects those identifiers from the generated canonical notation owner.

1.1.3.1 Attributes

Name	Description
metric_id	Persisted metric identifier whose values the narrative interprets.
question	Reader-facing question answered by the result.
answer	Concise interpretation of the observed result.
narrative	Ordered supporting paragraphs covering meaning and limitations.
evidence_role	Information role of the interpreted values.
population	Actual rows or entities summarized by the result.
unit	Human-readable unit or dimensionless scale of the metric.
support_result_ids	Report quantity or table IDs carrying factual support and missingness.
source_fields	Persisted source fields from which the result was reduced.
theory	Required canonical equation, symbol, and glossary identifiers.

1.1.4 ReportFigure

reporting.results.ReportFigure(
    id,
    plotly_json,
    source_ids,
    source_result_ids,
    symbol_ids,
    uses_webgl,
)

Canonical Plotly figure shared by Streamlit and static export.

1.1.4.1 Attributes

Name	Description
id	Globally unique result identifier.
plotly_json	UTF-8 canonical Plotly JSON with sorted keys and no trace UIDs.
source_ids	Source identities supporting the figure.
source_result_ids	Snapshot quantity/table results consumed by the figure builder.
symbol_ids	Canonical symbol IDs used by axes, legend, or explanation.
uses_webgl	Whether static export must use the configured raster profile.

1.1.5 ReportSnapshot

reporting.results.ReportSnapshot(
    schema_version,
    evidence_status,
    config_sha256,
    notation_sha256,
    source_identities,
    quantities,
    tables,
    figures,
    resolved_recipe,
    snapshot_sha256,
)

Immutable transaction consumed by Streamlit and static/Typst export.

Exporters accept this object, never a report config. Consequently an export cannot reacquire W&B history, reread a rollout store, or recompute a figure after the user has previewed it.

1.1.5.1 Attributes

Name	Description
schema_version	Closed snapshot schema version.
evidence_status	Evidence class enforced during acquisition and publication.
config_sha256	Digest of the canonical validated recipe.
notation_sha256	Digest of the generated canonical notation registry.
source_identities	Source identities sorted by stable ID.
quantities	Named quantities sorted by result ID.
tables	Tables sorted by result ID.
figures	Figures sorted by result ID.
resolved_recipe	Validated TOML recipe frozen at build time.
snapshot_sha256	Digest of all preceding snapshot fields.

1.1.5.2 Methods

Name	Description
create	Canonicalize ordering and seal a snapshot with its content digest.
result	Return one result by stable ID or raise KeyError.

1.1.5.2.1 create

reporting.results.ReportSnapshot.create(
    evidence_status,
    config_sha256,
    notation_sha256,
    source_identities,
    quantities,
    tables,
    figures,
    resolved_recipe,
    schema_version='aria-nbv-report-snapshot-v1',
)

Canonicalize ordering and seal a snapshot with its content digest.

1.1.5.2.2 result

reporting.results.ReportSnapshot.result(result_id)

Return one result by stable ID or raise KeyError.

1.1.6 ReportTable

reporting.results.ReportTable(id, columns, rows, source_ids)

Canonical immutable table with typed scalar cells.

1.1.6.1 Attributes

Name	Description
id	Globally unique result identifier.
columns	Ordered column contract.
rows	Canonical row-major scalar values.
source_ids	Source identities supporting the table.

1.1.7 SourceIdentity

reporting.results.SourceIdentity(id, kind, sha256, provenance)

Frozen identity and provenance for one materialized evidence source.

1.1.7.1 Attributes

Name	Description
id	Stable recipe-local source identifier.
kind	Owning source family.
sha256	Digest of the normalized source identity and acquired evidence.
provenance	Sorted non-secret provenance key/value pairs.

1.2 Functions

Name	Description
canonical_plotly_json	Return canonical Plotly JSON with generated trace UIDs removed.
theory_for_initial_metric	Return canonical references for the first reward/reconstruction metrics.

1.2.1 canonical_plotly_json

reporting.results.canonical_plotly_json(payload)

Return canonical Plotly JSON with generated trace UIDs removed.

1.2.2 theory_for_initial_metric

reporting.results.theory_for_initial_metric(metric)

Return canonical references for the first reward/reconstruction metrics.

The identifiers select definitions from the generated registry. Formulas remain owned by docs/typst/shared and are never copied into Python.