[vtorlima]

DICOM reliability, report robustness, and integration examples

Summary

Continues the pyaslreport reliability work from #66 by strengthening the DICOM metadata path, improving report-generation robustness, and completing the example-based integration layer with real BIDS and DICOM characterization datasets.

Testing against real vendor data exposed several existing issues in DICOM processing: anonymization-damaged GE values, unreliable representative-header selection, incorrect GE timing units, inconsistent vendor return shapes, and supplementary-JSON discovery conflicts. This PR fixes those behaviors and adds regression coverage around them. It also extends the integration runner from BIDS-only examples to a single auto-detecting BIDS/DICOM workflow and commits six real examples, so the integration job now exercises actual datasets in CI.

Together with #66, this PR completes my Google Summer of Code 2026 work with OSIPI on pyaslreport. The final GSoC commit is 72d753ff; any commits after it are post-GSoC.

What's included

DICOM metadata reliability

• Adds conservative in-memory repair for anonymization-damaged GE ASL private tags, without modifying the original DICOM files
• Makes GE header reads and value normalization null-safe
• Reads candidate DICOM headers deterministically and selects the most informative representative header based on ASL metadata completeness and sequence compatibility
• Extracts AcquisitionVoxelSize from PixelSpacing and SliceThickness, with a warning when geometry is unavailable
• Normalizes GE LabelingDuration / PostLabelingDelay values from scanner milliseconds to the BIDS-seconds metadata contract, including eASL timing calculations
• Adds supplementary-JSON discovery and metadata overlays, with aliases and diagnostics for added/replaced values
• Prevents integration/report JSON files such as expected_output.json from being mistaken for supplementary metadata
• Normalizes get_bids_metadata() so vendor paths consistently return (metadata, asl_context)

Report-generation robustness

• Handles missing M0 preparation timing without crashing, falling back to RepetitionTime when available
• Improves M0 inconsistency wording
• Refactors the ASL Methods paragraph into smaller conditional clauses so missing metadata only removes the affected prose
• Reports GE deltaM acquisitions as control-label pairs
• Caps report numbers to approximately four significant figures
• Collapses near-identical timing arrays when values agree within 1%
• Omits acquisition totals when the pair pattern is zero or unknown
• Accepts aslcontext.tsv volume types regardless of quoting

Integration testing

• Extends the existing example runner to automatically detect and run both BIDS and DICOM example folders
• Mirrors the production DICOM report flow: metadata extraction → supplementary JSON → temporary ASL JSON/context TSV → report generation
• Adds synthetic GE and Siemens DICOM helpers so the DICOM integration path is exercised on every push
• Improves golden failures to report all differing keys at once and provide a readable unified diff for generated report text
• Keeps the existing full-output characterization contract, including Methods prose

Committed characterization examples

• BIDS
  • bids_ge_pcasl_spiral — GE single-PLD PCASL
  • bids_pcasl_3dgrase — Siemens Prisma single-PLD PCASL
  • bids_pcasl_multipld — Siemens multi-PLD PCASL
  • bids_pasl — Siemens multi-PLD FAIR PASL
• DICOM
  • ge_pcasl_basic
  • ge_pcasl_easl

These examples intentionally characterize a range of current clean, warning, and error outputs. Their purpose is to make future behavioral changes explicit, not to require every committed example to represent an already-perfect report.

The anonymized DICOM example datasets were provided by the project mentors for use in this project.

Regression coverage

• GE anonymization repair and representative-header selection
• M0 timing fallback and missing-timing behavior
• Methods-prose helpers and formatting behavior
• Timing-array tolerance collapse
• DICOM voxel-geometry extraction and missing-geometry warnings
• GE timing-unit round trip
• Supplementary-JSON precedence and propagation into generated prose
• Siemens DICOM end-to-end report generation
• Sidecar discovery excluding golden/output JSON files
• BIDS and DICOM golden-output behavior

[Shubham-Padkonde]

Hi Vitor, I'm Shubham. Would a small test-only follow-up for the sidecar selection in this PR be useful?

At 4e75866, discover_sidecars() lists scan-folder JSONs before parent-folder JSONs, and apply_sidecar_overrides() applies only the first, warning about the others. The tests cover a single parent sidecar and output-file exclusion, but I didn't see a conflicting local/parent case. Is preferring the scan-folder file intentional?

If so, could a maintainer delegate tests for that precedence, sorted selection within one folder, and the ignored-files warning, coordinated with you? I'd use synthetic JSON fixtures and check the selected values and unchanged files on disk. I've reviewed the source and tests; I haven't run the package yet. Your implementation would remain the basis for this test scope.