MRI Data Anonymisation & QC Toolkit

A set of Python scripts for anonymising neuroimaging datasets and visually quality-checking brain scans in a web browser. Claude Code generated.

---

Scripts

1. anonymize.py — File Path Anonymisation

Detects patient names embedded in file paths and replaces them with subject IDs. Optionally renames files and folders on disk. Supports two input modes.

Expected path structure:

.../subject_ID/PatientName-YYYY.MM.DD/PatientName-YYYY.MM.DD_scaninfo.nii

After anonymisation:

.../subject_ID/subject_ID-YYYY.MM.DD/subject_ID-YYYY.MM.DD_scaninfo.nii

Usage:

python anonymize.py

The script will first ask you to select a mode:

[0] Metadata CSV mode — use when you have a spreadsheet listing the files you want to anonymise.

The script will prompt you to:

1. Provide the path to your metadata file (.csv or .xlsx)
2. Provide the path to the directory where the output file should be saved
3. Select which column contains the subject IDs
4. Select which columns contain file paths to anonymise
5. Choose between a dry run (preview only) or a live run (rename files on disk)

[1] File list mode — use when you want to process all files in a directory tree, including files not listed in any spreadsheet. Generate the file list first with:

find /path/to/directory -type f > file_list.txt

The script will prompt you to:

1. Provide the path to your file list
2. Provide the path to the directory where the output file should be saved
3. Choose between a dry run (preview only) or a live run (rename files on disk)

Subject IDs are inferred automatically from the path structure. Metadata is extracted per file type:

• .nii / .nii.gz — image dimensions and voxel sizes from the NIfTI header
• .json — acquisition metadata (field strength, manufacturer, series description, echo/repetition time, etc.)
• All other file types — metadata fields set to NA

Output: An annotated Excel file (anonymized_metadata.xlsx) containing file paths, subject IDs, extracted metadata, anonymised paths, the mv shell command for each rename, and a _check_status column confirming whether patient names were successfully removed (pass or fail).

Key settings (edit at the top of the script):

Variable	Default	Description
DRY_RUN	True	Set to False to actually rename files
INCLUDE_ORIGINAL	True	Include original paths in the output file

---

2. qc_report.py — Visual QC Report Generator

Generates a self-contained HTML report for visually inspecting T1w brain scans in a web browser. For each scan, middle slices for axial, coronal, and sagittal planes are visualized alongside key acquisition metadata. Scans from the same subject are colour-grouped for easy visual comparison.

Features:

• Reads NIfTI (.nii / .nii.gz) and JSON sidecar paths from a spreadsheet that is fed to script
• Corrects for non-isotropic voxels so slices are not squashed
• Embeds all images directly in the HTML — no external files needed
• Groups multiple scans per subject with a shared background colour
• Shows file paths (truncated for readability, full path on hover)

Usage:

python qc_report.py

The script will prompt you to:

1. Provide the path to your metadata file (.csv or .xlsx)
2. Provide the path to the directory where the output file should be saved
3. Select which column contains the subject ID (used for colour grouping)
4. Select which column contains the NIfTI paths
5. Select which column contains the JSON sidecar paths

Output: qc_report.html saved to the directory you specify — open in any web browser.

open qc_report.html

Metadata displayed per scan:

Field	Source
Dimensions (voxels)	NIfTI header
Voxel Size (mm)	NIfTI header
NIfTI / JSON paths	Input spreadsheet
Slice Thickness	JSON sidecar
Manufacturer & Model	JSON sidecar
Field Strength	JSON sidecar
Series / Protocol Name	JSON sidecar

Dependencies:

pip install nibabel numpy Pillow pandas openpyxl

---

3. (Additional) create_mock_files.py — Test Dataset Generator

This is a script that ca be used to create mock files and experiment with the file anoymization script - if you are feeling nervy. It creates empty placeholder NIfTI files at the paths listed in metadata-example.csv. Run this once to set up a test dataset before running anonymize.py, without needing real scan data.

Usage:

python create_mock_files.py

Reads metadata-example.csv from the same folder and creates empty files at every path listed in the nifti_path column, including any intermediate folders.

---

Requirements

• Python 3.8+
• nibabel — reading NIfTI brain scan files
• numpy — array operations on image data
• Pillow — image processing and PNG export
• pandas — reading CSV / Excel spreadsheets
• openpyxl — Excel file support for pandas

Install all dependencies:

pip install nibabel numpy Pillow pandas openpyxl

---

Typical Workflow

1. create_mock_files.py   →   IF NEEDED: set up a test dataset from metadata-example.csv for experimentation
2. anonymize.py           →   replace patient names in file paths with subject IDs; automatically verifies removal
3. qc_report.py           →   visually inspect anonymised scans before sharing the dataset