Report Data Layer API Reference

The kreview.report_data module assembles the single-page report's data blob from a pipeline output directory and renders the page. It is the only place that decides what a number in the report means — the operating points, their patient-clustered intervals, the verification-bias ladder, the subgroup breakdowns and the automatic findings all originate here, so the template renders and never computes.

Two guarantees live in this module: the blob is aggregates only (a build-time PHI guard refuses to write anything sample-id-shaped), and a value that could not be sourced is reported as unknown rather than defaulted.

For conceptual explanations, see:

`kreview.report_data`

Build the data layer for the single-page evaluation report (#79): one aggregates-only JSON assembled from a pipeline output directory, plus the renderer that injects it into the self-contained HTML template. Replaces the render-time Quarto/papermill/SHAP path.

Docs: https://msk-access.github.io/kreview/report_data.html.md

`assert_no_phi(blob)`

Fail loud if the serialized report data carries anything sample-identifying.

The upstream *_model_results.json files embed thousands of real MSK DMP sample ids (oof_sample_ids); the report must only ever ship aggregates. This is the hard guarantee, enforced at build time — not a convention.

Raises:

Type	Description
`ValueError`	if a DMP-shaped id or a sample-id field survived into the output.

`build_report_data(outdir, *, trace_path=None, run_label='')`

Assemble the full report data dict from a pipeline output directory.

Aggregates-only by construction: per-sample arrays are consumed in memory and never emitted. Serialization must go through :func:write_report_data (or apply :func:assert_no_phi) so the no-identifiers guarantee is enforced.

Parameters:

Name	Type	Description	Default
`outdir`	`str \| Path`	The pipeline `--outdir` (contains `labels/`, `models/`, `matrices/`, `scoreboard_combined__all.parquet`, …).	required
`trace_path`	`str \| Path \| None`	Optional `execution_trace.txt` for the diagnostics tab.	`None`
`run_label`	`str`	Free-text label shown in the report header.	`''`

Raises:

Type	Description
`FileNotFoundError`	if the scoreboard or labels are missing — the report is meaningless without them, so this fails loud rather than emitting an empty page.

`write_report_data(data, out_path)`

Serialize report data with the PHI guarantee enforced.

`render_page(data, out_html)`

Inject report data + inlined plotly.js into the page template and write it.

Fully self-contained output (no CDN): plotly.js comes from the installed plotly python package, so the page works on air-gapped HPC nodes. The PHI guarantee is enforced on both the data blob and the final page.

`render_report(outdir, out_html, *, trace_path=None, run_label='')`

Build the report data from outdir and render the single-page report.