report_gen.md

Automatic dataset generation

This pipeline expects the dataset to be in the classical BraTS2023 layout:

<DATASET_ROOT>/
  BraTS-GLI-XXXXXX/
    BraTS-GLI-00001-t1n.nii.gz
    BraTS-GLI-00001-t1c.nii.gz
    BraTS-GLI-00001-t2f.nii.gz
    BraTS-GLI-00001-t2w.nii.gz
    BraTS-GLI-00001-seg.nii.gz
  BraTS-GLI-XXXXXX/
    ...

Every root passed to the scripts below (the dataset and each intermediate output) must contain only subject folders: subjects are paired across BraTS_CC, BraTS_atlas and BraTS_eloquent by sorted folder name, so a stray file breaks the pairing.

Prerequisites

• Install the environment as described in the README (uv sync). This installs the repo as a package, so the scripts can be run by path from any directory.
• Atlas registration (steps 2 and 4) uses ANTs through antspyx (already a dependency). SyN registration runs on CPU and is the slowest step; no GPU is needed.
• The atlases, eloquent-cortex masks and legend used by default are shipped in report_generation/resources/.

If an output directory already exists, each script asks whether to delete it: y deletes and recreates it, n aborts without touching it.

How To Run

1. Create connected-component segmentations

python report_generation/autogen/run_cc_segmentation.py \
  --image-path /path/to/brats_dataset \
  --output-path /path/to/BraTS_CC

Option	Default	Description
--image-path	required	BraTS dataset root (reads <sub>/<sub>-seg.nii.gz).
--output-path	required	Output root.
--num-workers	8	DataLoader workers.

Output: <output-path>/<sub>/<sub>-cc.nii.gz (connected-component tumour labels).

2. Register atlas to each subject

python report_generation/autogen/generate_atlas.py \
  --input-dir /path/to/brats_dataset \
  --output-dir /path/to/BraTS_atlas

Option	Default	Description
--input-dir	required	BraTS dataset root (reads <sub>/<sub>-t1n.nii.gz).
--output-dir	required	Output root.
--t1-atlas-path	resources/T1_brain.nii.gz	T1 atlas (intensity image) registered to each subject.
--areas-atlas-path	resources/areas.nii.gz	Labelled brain-areas atlas warped into subject space.

Output, per subject:

<output-dir>/<sub>/
  <sub>-t1n.nii.gz     copy of the subject T1 (used as reference by steps 3 and 4)
  areas.nii.gz         areas atlas warped to subject space
  transforms/
    fwd_*              atlas -> subject transforms
    inv_*              subject -> atlas transforms

3. Fill tiny holes in atlas labels — mandatory: step 5 reads areas-fill.nii.gz, which only this step creates.

python report_generation/autogen/fill_atlas.py \
  --input-path /path/to/BraTS_atlas

Option	Default	Description
--input-path	required	Output of step 2. Files are written in place.
--num-workers	32	DataLoader workers.

Output: <sub>/<name>-fill.nii.gz next to every label map in the subject folder (e.g. areas-fill.nii.gz). Background voxels inside the brain at distance 1 from a label take the nearest label.

4. Warp eloquent masks from atlas space to each subject

python report_generation/autogen/generate_eloquent.py \
  --input-path /path/to/BraTS_atlas \
  --output-path /path/to/BraTS_eloquent

Option	Default	Description
--input-path	required	Output of step 2 (uses <sub>-t1n.nii.gz and transforms/fwd_*).
--output-path	required	Output root.
--num-workers	4	Worker threads.
--motor-path	resources/motor.nii.gz	Motor-cortex mask in atlas space.
--speech-motor-path	resources/speech_motor.nii.gz	Speech-motor mask in atlas space.
--speech-receptive-path	resources/speech_receptive.nii.gz	Speech-receptive mask in atlas space.
--vision-path	resources/vision.nii.gz	Visual-cortex mask in atlas space.

Output: <output-path>/<sub>/{motor,speech_motor,speech_receptive,vision}.nii.gz.

5. Generate final structured/text reports

python report_generation/autogen/generate_reports.py \
  --cc-path /path/to/BraTS_CC \
  --atlas-path /path/to/BraTS_atlas \
  --eloquent-path /path/to/BraTS_eloquent \
  --output-root /path/to/output \
  --thresholds 0.0

Option	Default	Description
--cc-path	required	Output of step 1.
--atlas-path	required	Output of steps 2–3.
--eloquent-path	required	Output of step 4.
--output-root	required	Where the ReportX_t* folders are created.
--legend-path	resources/legend_postprocessed.csv	Atlas label legend.
--thresholds	0.0	One or more region-inclusion thresholds (e.g. 0.0 0.2 0.5); one dataset is generated per value.
--num-workers	8	DataLoader workers.

What It Produces

Given subject-level MRI/segmentation data, the pipeline builds:

• connected-component tumor labels (BraTS_CC)
• subject-space anatomical atlas labels (BraTS_atlas)
• subject-space eloquent masks (BraTS_eloquent)
• final generated outputs, one folder per threshold named ReportX_t<threshold×100> (e.g. ReportX_t0, ReportX_t20), each subject containing:
  • eng.json (structured representation)
  • eng.txt (natural-language report)

This layout can be passed directly to the agreement scripts and to the CCS/TA notebook.