p21-triage

Triage layer for Pinnacle 21 Community validation reports.

You run P21. It hands you an Excel report with 2,000 findings. p21-triage reads that report and tells you, in plain English, what each finding means, which ones share a root cause, which ones threaten your submission, and what to do about each — then tracks your decisions run-over-run and writes your SDRG summary.

This is not a validator: it never runs checks and never reads study datasets. Its only input is the P21 Excel report.

Install

pip install cdisc-p21-triage

(Requires Python 3.9+. Only dependency: openpyxl.)

Quick start

# Explain and cluster a report's findings
p21-triage triage pinnacle21-report-2022-10-20T17-56-05-191.xlsx

# Record decisions (persisted in <report>.triage.json)
p21-triage disposition report.xlsx --key "SD1076|AE|AELAT" \
    --status document --note "AELAT added for laterality; permissible per SDTMIG"
p21-triage disposition report.xlsx --list

# Compare two runs
p21-triage diff old-report.xlsx new-report.xlsx

# Annotated Excel + SDRG-ready Markdown
p21-triage export report.xlsx --xlsx annotated.xlsx --md sdrg-section5.md

# Explain one rule
p21-triage explain report.xlsx --rule CT2001

Disposition statuses: open (default), fix, document, waive. Carry decisions into the next run with --disposition-file old-report.xlsx.triage.json.

Python API

from p21_triage import (
    parse_report, cluster_findings, enrich_clusters,
    diff_reports, export_excel, export_markdown,
    save_disposition, apply_dispositions,
)

report = parse_report("pinnacle21-report-....xlsx")
clusters = enrich_clusters(cluster_findings(report), report.meta.engine)

for c in clusters:
    print(c.rule_id, c.domain, c.risk_level, c.record_count)
    print(" ", c.explanation)

# decisions persist in a JSON sidecar
save_disposition("report.xlsx", clusters[0].key, "waive", "sponsor decision")

# run-over-run
delta = diff_reports(parse_report("old.xlsx"), parse_report("new.xlsx"))
print(len(delta.added), "new clusters,", len(delta.resolved), "resolved")

export_excel(report, clusters, "annotated.xlsx", delta)
export_markdown(report, clusters, "sdrg.md", delta)

How it works

1. Parse — tabs and columns are detected by name (alias lists cover version variants), never by position. Unknown format → clear error naming what's missing. See FORMAT.md.
2. Explain — every finding gets a plain-English explanation: the report's own Rules tab first, then a built-in knowledge base of common rules (written in our own words from public rule docs), then an honest "not covered" fallback.
3. Cluster — findings collapse by RULE_ID|DOMAIN|VARIABLES into root-cause clusters. One missing codelist → one cluster, not 500 rows.
4. Risk — severity mapped to submission risk (FDA and PMDA semantics).
5. Decide — fix / document / waive per cluster, stored in a JSON sidecar; stable cluster keys carry decisions across runs.
6. Diff — run-over-run: new, resolved, and persistent clusters plus finding-level signature counts.
7. Export — annotated Excel (findings + clusters + rules + optional delta sheets) and SDRG Section 5–ready Markdown.

Report format support

Built from public documentation of the P21 Community Excel report (Datasets Summary / Issue Summary / Details / Rules tabs). Version differences (renamed tabs/columns, missing Severity column in newer versions) are handled by name-based detection — see FORMAT.md for the spec and confidence levels.

Clean-room note

Built only from Pinnacle 21's public report format and published rule documentation. No proprietary code or data was used; all test reports are synthetically generated in tests/make_sample.py.

License

MIT — see LICENSE.