Atlas Preprocessing Pipeline

A bash-based pipeline for processing and normalizing T1w MRI images using the current NPNL standard. It runs a sequence of FreeSurfer and ANTs tools to register, mask, bias-field correct, and normalize intensities of brain structures.

Requirements

The script requires the following software to be installed:

• FreeSurfer (specifically mri_synthmorph and mri_synthstrip, available from version 7.4.1 onwards. See FreeSurfer Release Notes for installation instructions)
• ANTs (specifically N4BiasFieldCorrection and ImageMath. See ANTs Documentation for installation instructions)

The script expects the input T1w image to follow the BIDS naming convention: sub-[SUB]_ses-[SES]_T1w.nii.gz

The MNI template used is the MNI ICBM-152 2009a Nonlinear Symmetric template, which can be downloaded from the MNI website

Configuration

Before running the pipeline, paths to the required tool binaries and templates must be defined in the config.sh file. Edit the config.sh file located in the same directory as the script to point to the correct locations on your system:

# Example config.sh content
export ANTS_PATH="/usr/local/ANTs/bin"
export FREESURFER_HOME="/usr/local/freesurfer"
export MNI_TEMPLATE="/path/to/mni_icbm152_nlin_sym_09a.nii"

Usage

./atlas_preprocess.sh -i <T1w_image_path> -o <output_directory> [options]

Options

• -i, --img : Path to input T1w image (Required)
• -o, --outdir : Path to output directory (Required)
• -m, --mask : Path to lesion mask (Optional. If provided, the MNI affine transform will be applied to it using nearest-neighbor interpolation).
• -g, --gpu : Add this flag to enable GPU acceleration for FreeSurfer tools (mri_synthmorph, mri_synthstrip)
• -c, --cuda : Specify which CUDA device to use (e.g., 0)
• -v, --verbose : Keep all intermediate files (set to 1). Default is 0, which deletes intermediate files (N4_MNI_IMG, N4_MASKED, DYNAMIC_RANGE).
• -h, --help : Show help message

Examples

Standard CPU execution:

./atlas_preprocess.sh -i /path/to/sub-01_T1w.nii.gz -o /path/to/output_dir

Execution with GPU 0 enabled:

./atlas_preprocess.sh -i /path/to/sub-01_T1w.nii.gz -o /path/to/output_dir -g -c 0

Processing Steps

1. mri_synthmorph register: Affine registration to MNI space
2. mri_synthstrip: Extract brain mask from native space, and align MNI mask.
3. N4BiasFieldCorrection: Correct intensity inhomogeneity using native brain mask.
4. mri_synthmorph apply: Align the N4-corrected T1 to MNI space using the generated affine transform.

• (Optional) If -m is provided, align the lesion mask to MNI space using nearest-neighbor interpolation.

5. ImageMath masking: Confine MNI-aligned T1 strictly to the MNI brain region.
6. ImageMath normalization: Compute dynamic range (0.5% - 99.5%) and rescale intensity bounds to [0, 100].

Outputs

The primary output is the brain-only T1w image in MNI space with intensity normalization ([OUTDIR]/derivatives/synthmorph_affine/[SUB]/[SES]/[SUB]_[SES]_space-MNI152NLin2009aSym_desc-brainnorm_T1w.nii.gz).

If a lesion mask is provided, the MNI affine transform will be applied to it using nearest-neighbor interpolation, and the output will be saved as [OUTDIR]/derivatives/synthmorph_affine/[SUB]/[SES]/[SUB]_[SES]_space-MNI152NLin2009aSym_desc-lesion_mask.nii.gz.

Other outputs include:

• Affine transform: [OUTDIR]/derivatives/synthmorph_affine/[SUB]/[SES]/[SUB]_[SES]_orig_to_MNI152NLin2009aSym.lta
• Brain mask in native space: [OUTDIR]/derivatives/synthstrip/[SUB]/[SES]/[SUB]_[SES]_proc-synthstrip_space-orig_desc-T1brain_mask.nii.gz
• Brain mask in MNI space: [OUTDIR]/derivatives/synthstrip/[SUB]/[SES]/[SUB]_[SES]_proc-synthstrip_space-MNI152NLin2009aSym_desc-T1brain_mask.nii.gz
• N4-corrected T1w image in native space: [OUTDIR]/derivatives/ants_N4BiasFieldCorrection/[SUB]/[SES]/[SUB]_[SES]_desc-N4_T1w.nii.gz
• (If verbose = 1) N4-corrected T1w image in MNI space: [OUTDIR]/derivatives/synthmorph_affine/[SUB]/[SES]/[SUB]_[SES]_space-MNI152NLin2009aSym_desc-N4_T1w.nii.gz
• (If verbose = 1) N4-corrected and masked T1w image in MNI space: [OUTDIR]/derivatives/synthmorph_affine/[SUB]/[SES]/[SUB]_[SES]_space-MNI152NLin2009aSym_desc-N4masked_T1w.nii.gz
• (If verbose = 1) Dynamic range normalized T1w image in MNI space: [OUTDIR]/derivatives/synthmorph_affine/[SUB]/[SES]/[SUB]_[SES]_space-MNI152NLin2009aSym_desc-dynamicrange_T1w.nii.gz