radreport

Parse radiology free-text reports into structured data. No ML. No GPU. No dependencies.

Radiology reports come out as free-text PDFs. Downstream systems — EMRs, telehealth portals, billing platforms, research pipelines — need structured data. This library bridges that gap.

Four things it does well:

1. Parse — splits any free-text report into labeled sections, extracts measurements, links findings to anatomy
2. Detect — flags critical/urgent findings with negation awareness (no false alerts for "no pneumothorax")
3. De-identify — redacts PHI (dates, MRNs, names, contact info…) with a full audit trail, so reports can leave a controlled environment for research
4. Export — outputs FHIR R4 DiagnosticReport resources ready for any EMR

Install

pip install radreport

Zero required dependencies. Works on Python 3.9+.

Quick Start

from radreport import ReportParser, CriticalFindingsDetector, FHIRExporter
import json

report_text = """
INDICATION: Chest pain, rule out PE.

FINDINGS:
Lungs: Filling defect in the right main pulmonary artery consistent with
pulmonary embolism. No pneumothorax.

IMPRESSION:
Pulmonary embolism, right main pulmonary artery. Urgent correlation recommended.
"""

# 1. Parse
parser = ReportParser()
report = parser.parse(report_text, modality="CT")

print(report.impression)
# → "Pulmonary embolism, right main pulmonary artery. Urgent correlation recommended."

# 2. Detect critical findings
detector = CriticalFindingsDetector()
report = detector.detect(report)

for cf in report.critical_findings:
    if not cf.negated:
        print(f"[{cf.severity.upper()}] {cf.term} ({cf.category})")
        print(f"  Context: {cf.context}")
# → [CRITICAL] pulmonary embolism (pulmonary)
#     Context: Filling defect in the right main pulmonary artery consistent with pulmonary embolism.

# 3. Export to FHIR
exporter = FHIRExporter()
fhir = exporter.export(report, patient_id="pt-001")
print(json.dumps(fhir, indent=2))

CLI

After installation, the radreport command is available for single-file and batch processing:

# Parse a single report to JSON
radreport report.txt

# Parse with critical findings detection
radreport report.txt --critical

# Export as FHIR DiagnosticReport
radreport report.txt --fhir --patient-id pt-001 --modality CT

# Extract follow-up recommendations too
radreport report.txt --critical --recommend

# Redact PHI before parsing (safe to store/share the output)
radreport report.txt --deidentify --critical

# Batch process multiple files → JSON array
radreport reports/*.txt --critical -o batch.json

# Specify modality for all files
radreport *.txt --modality MRI --fhir -o fhir_batch.json

# Flat CSV for research/analytics (one row per report)
radreport reports/*.txt --critical --recommend --format csv -o cohort.csv

Flags:

Parsing

Sections

The parser recognizes standard radiology report sections regardless of formatting style:

report = parser.parse(text, modality="MRI")

findings = report.get_section("findings")
print(findings.raw_text)

impression = report.get_section("impression")
print(impression.raw_text)

Measurements

All measurements are extracted and normalized to millimeters:

for m in report.all_measurements:
    print(f"  Raw: {m.raw}")
    print(f"  Normalized (mm): {m.dimensions_mm}")
    print(f"  Largest dimension: {m.largest_dimension_mm} mm")

# Raw: 2.3 x 1.8 cm
# Normalized (mm): [23.0, 18.0]
# Largest dimension: 23.0 mm

Handles: 1.2 x 0.8 cm, 12mm, 1.2cm, 12 x 8 x 5 mm, 1.2 x 0.8 x 0.5 cm

Findings by anatomy

findings_section = report.get_section("findings")
for finding in findings_section.findings:
    print(f"Anatomy: {finding.anatomy or 'unspecified'}")
    print(f"Text: {finding.text}")

Batch processing

reports = parser.parse_batch(list_of_texts, modality="CT")
# Returns list[ParsedReport | None] — None for empty/unparseable inputs
active = [r for r in reports if r is not None]

JSON serialization

report = parser.parse(text, modality="CT")

# As dict
d = report.to_dict()

# As JSON string (shorthand)
json_str = report.to_json()
json_str = report.to_json(indent=4)

Critical Findings Detection

Rule-based. Fully auditable. No black boxes.

Covers 45+ terms across 7 categories:

Negation awareness

# "No pneumothorax identified" → negated=True, won't trigger alert
# "Pneumothorax present" → negated=False, triggers alert

active = [cf for cf in report.critical_findings if not cf.negated]

Negation is scoped to the sentence and fails safe:

• A negation in one sentence never carries into the next — "No acute hemorrhage. Large subdural hematoma is present." flags the hematoma as active.
• When a term appears more than once, an active (non-negated) mention always wins over a negated one — "No pneumothorax at the apex. Large pneumothorax at the base." flags pneumothorax as active. A term is reported as negated only when every mention is negated. This prevents a real critical finding from being silently suppressed by an earlier "no ..." phrase.

Severity levels

• critical — requires immediate action (PE, subdural hematoma, pneumothorax)
• urgent — requires same-day follow-up (DVT, bowel obstruction, appendicitis)
• significant — requires follow-up (malignancy, metastasis)

Extending the term list

from radreport.critical_findings import CRITICAL_TERMS

CRITICAL_TERMS["tension pneumothorax"] = ("pulmonary", "critical")
CRITICAL_TERMS["septic emboli"] = ("vascular", "urgent")

Follow-up Recommendations

Extract structured follow-up imaging recommendations from the recommendation and impression sections — interval, modality, and urgency.

from radreport import ReportParser, RecommendationExtractor

report = ReportParser().parse(text, modality="CT")
report = RecommendationExtractor().extract(report)

for rec in report.recommendations:
    print(rec.interval, rec.modality, rec.urgency)

# "Recommend follow-up CT in 6 months."
# → interval="6 months", modality="CT", urgency="routine"

Negation-aware: "No follow-up imaging indicated" yields no recommendation. Identical recommendations are deduplicated.

De-identification

Strip Protected Health Information (PHI) from a report before it leaves a controlled environment — for research collaboration, analytics warehouses, or off-site processing. Like everything else in this library, it is rule-based and fully auditable: every removal is a traceable regular-expression match, recorded with its original offset. No ML, no cloud NER service — the kind of thing hospital IT will actually approve.

from radreport import Deidentifier

deid = Deidentifier()
result = deid.deidentify(raw_report_text)

print(result.text)              # scrubbed report, safe to share
print(result.redaction_count)   # e.g. 11
print(result.category_counts()) # {"date": 3, "mrn": 1, "name": 2, ...}

# Audit trail — every removed span, keyed to the original text
for r in result.redactions:
    print(r.category, r.original, "→", r.replacement, f"@{r.start}:{r.end}")

What it detects

Categories map to the HIPAA Safe Harbor identifiers that are reliably matchable from text alone:

Clinical content is preserved: a 6 mm nodule or a 90 mm mass is never mistaken for PHI, because age matching requires an explicit age cue.

Configuration

# Redact only dates and names, and use a custom placeholder for names
deid = Deidentifier(
    categories=["date", "name"],
    placeholders={"name": "XXXX"},
)

Scope and limitations. Rule-based de-identification is a strong first pass, not a compliance guarantee. Names that appear in free narrative without a title or header label are not caught. Always review the output before PHI leaves a controlled environment. This tool does not certify HIPAA Safe Harbor compliance.

FHIR Export

Outputs a valid FHIR R4 DiagnosticReport resource.

from datetime import datetime

fhir = exporter.export(
    report,
    patient_id="pt-001",       # Optional: links to FHIR Patient resource
    report_id="rpt-20240315",   # Optional: custom resource ID
    issued_dt=datetime.now(),   # Optional: defaults to UTC now
)

What's included

• resourceType: DiagnosticReport
• status: final
• code: LOINC code matched to modality (CT, MRI, US, etc.)
• conclusion: impression text
• presentedForm: full report text as base64 attachment
• contained: FHIR Observations for each active (non-negated) critical finding
• extension: structured sections for downstream parsing
• subject: patient reference (when patient_id provided)

Full Pipeline Example

import json
from radreport import ReportParser, CriticalFindingsDetector, FHIRExporter

parser   = ReportParser()
detector = CriticalFindingsDetector()
exporter = FHIRExporter()

def process_report(text: str, modality: str, patient_id: str) -> dict:
    report = parser.parse(text, modality=modality)
    report = detector.detect(report)

    active_criticals = [cf for cf in report.critical_findings if not cf.negated]
    if active_criticals:
        print(f"WARNING: {len(active_criticals)} critical finding(s) detected")

    return exporter.export(report, patient_id=patient_id)

fhir_json = process_report(report_text, modality="CT", patient_id="pt-001")
print(json.dumps(fhir_json, indent=2))

See examples/full_pipeline.py for a runnable end-to-end example.

Design Principles

No dependencies. The library installs with no third-party packages. This matters in hospital environments where every dependency goes through security review.

Rule-based, not ML-based. Every decision the library makes is traceable to a specific rule. No model weights, no GPU, no probabilistic outputs. Clinical teams can audit exactly why a finding was flagged.

Negation-aware. A library that can't distinguish "no pneumothorax" from "pneumothorax" is dangerous in clinical contexts. Negation detection is built into the core.

Auditable de-identification. PHI redaction runs locally with no ML and no external calls, and every removed span is logged with its original offset — so a privacy officer can review exactly what left the building and why.

FHIR-first output. Every modern EMR speaks FHIR. The export format is designed to drop into existing integrations without transformation.

Running Tests

pip install radreport[dev]
pytest tests/ -v

Roadmap

• CLI tool for single-file and batch processing (radreport command)
• parse_batch() API for processing lists of reports
• to_json() convenience method on ParsedReport
• Structured output for follow-up recommendations (RecommendationExtractor)
• CSV export mode for research/analytics workflows (--format csv)
• Rule-based PHI de-identification with audit trail (Deidentifier)
• Template matching for common report types (Chest XR, CT Abdomen, MRI Brain)
• Structured comparison / prior-study extraction (new / increased / stable / resolved)
• Additional FHIR resource types (ImagingStudy, Condition)

Disclaimer

This library is a developer tool for structuring report text. It is not a medical device and is not intended for direct clinical decision-making. Critical findings detection is designed to assist human review workflows, not replace radiologist judgment.

License

MIT