Skip to content

ReproNim/freesurfer-nidm_bidsapp

BranchesTags

Repository files navigation

BIDS FreeSurfer App

A BIDS App implementation for FreeSurfer 8.0.0 that provides standardized surface reconstruction and morphometric analysis with NIDM output.

Description

This BIDS App runs only FreeSurfer's recon-all pipeline on structural T1w and (optionally) T2w images from a BIDS-valid dataset. It organizes outputs in a BIDS-compliant derivatives structure and provides additional NIDM format outputs for improved interoperability.

Important Note: This app is designed to run the complete recon-all cortical reconstruction pipeline. It does not provide access to other FreeSurfer command-line tools (e.g., tkmedit, tksurfer, mri_vol2vol, etc.). For interactive FreeSurfer tools or additional analyses, you will need a full FreeSurfer installation.

The app implements:

  1. Automatic identification and processing of T1w images (required)
  2. Utilization of T2w images when available (optional)
  3. Multi-session data handling with appropriate processing paths
  4. NIDM format output generation for standardized data exchange
  5. BIDS provenance documentation for reproducibility
  6. Comprehensive version tracking for all components (FreeSurfer, BIDS app, Python packages)

Installation

Requirements

Quick Installation

Clone the repository (including submodules) using SSH:

git clone --recursive git@github.com:ReproNim/freesurfer-nidm_bidsapp.git
cd freesurfer-nidm_bidsapp

Note: The --recursive flag is required to also clone the git submodules used by this project (e.g., src/segstats_jsonld).

Container Support

This BIDS App supports both Docker and Singularity/Apptainer, allowing you to run the application in various environments including HPC clusters.

Building Containers

# Build Docker image (for local development)
python setup.py docker

# Build Singularity/Apptainer image (e.g., on a cluster)
apptainer build --fakeroot freesurfer-nidm-bidsapp.sif Singularity

# Or specify a custom output location
apptainer build --fakeroot /path/to/output/freesurfer-nidm-bidsapp.sif Singularity

Note: The --fakeroot option is recommended for cluster environments because it avoids permission issues on shared systems and does not require root privileges. If you encounter issues, contact your system administrator to ensure your user is configured for fakeroot, and make sure you have write permissions in the build directory.

Docker Usage

# Run the container
docker run -v /path/to/license.txt:/license.txt \
  -v /path/to/bids/data:/data \
  -v /path/to/output:/output \
  freesurfer-nidm-bidsapp \
  --bids_dir /data \
  --output_dir /output

Singularity/Apptainer Usage

# Run the container
apptainer run \
  --bind /path/to/license.txt:/license.txt,/path/to/bids/data:/data,/path/to/output:/output \
  /path/to/freesurfer-nidm-bidsapp.sif \
  --bids_dir /data \
  --output_dir /output

Note: The application files are included in the container image, so there's no need to bind the repository directory. Only the license file, input data, and output directory need to be bound.

HPC/Cluster Usage

After building the Singularity/Apptainer image (see Building Containers), create a job submission script like this:

#!/bin/bash
#SBATCH --job-name=freesurfer
#SBATCH --output=freesurfer_%j.out
#SBATCH --cpus-per-task=4
#SBATCH --mem=16G

# Path to the Singularity image
SIF_FILE=/path/to/freesurfer.sif
# Path to license file
LICENSE_FILE=/path/to/license.txt
# Input and output paths
BIDS_DIR=/path/to/bids/data
OUTPUT_DIR=/path/to/output

apptainer run \
  --bind $LICENSE_FILE:/license.txt,$BIDS_DIR:/data,$OUTPUT_DIR:/output \
  $SIF_FILE \
  --bids_dir /data \
  --output_dir /output \
  --participant_label sub-01 sub-02  # Add your subjects here

Command-Line Arguments

  • Positional arguments:

    • bids_dir: The directory with the input BIDS dataset
    • output_dir: The directory where the output files should be stored
    • analysis_level: Level of the analysis that will be performed. Options are: participant, group

  • Optional arguments:

    • --participant_label: The label(s) of the participant(s) to analyze (without "sub-" prefix)
    • --session_label: The label(s) of the session(s) to analyze (without "ses-" prefix)
    • --freesurfer_license: Path to FreeSurfer license file
    • --skip_bids_validator: Skip BIDS validation
    • --fs_options: Additional options to pass to recon-all only (e.g., "-parallel -openmp 4")
    • --skip_nidm: Skip NIDM output generation

Note: The --fs_options parameter only accepts recon-all specific options. This app does not expose other FreeSurfer commands or tools.

Examples

Process a single subject:

# Using Docker (for local development)
docker run -v /path/to/bids_dataset:/bids_dataset:ro \
           -v /path/to/output:/output \
           -v /path/to/freesurfer/license.txt:/license.txt \
           bids/freesurfer:8.0.0 \
           /bids_dataset /output participant --participant_label 01

# Using Apptainer (for clusters)
apptainer run \
  --bind /path/to/license.txt:/license.txt,/path/to/bids_dataset:/data,/path/to/output:/output \
  freesurfer.sif \
  --bids_dir /data \
  --output_dir /output \
  --participant_label 01

Process multiple subjects in parallel (using FreeSurfer's built-in parallelization):

# Using Docker (for local development)
docker run -v /path/to/bids_dataset:/bids_dataset:ro \
           -v /path/to/output:/output \
           -v /path/to/freesurfer/license.txt:/license.txt \
           bids/freesurfer:8.0.0 \
           /bids_dataset /output participant --fs_options="-parallel -openmp 4" \
           --participant_label 01 02 03

# Using Apptainer (for clusters)
apptainer run \
  --bind /path/to/license.txt:/license.txt,/path/to/bids_dataset:/data,/path/to/output:/output \
  freesurfer.sif \
  --bids_dir /data \
  --output_dir /output \
  --fs_options="-parallel -openmp 4" \
  --participant_label 01 02 03

Outputs

Output Directory Structure

The container writes all results under a single freesurfer-nidm_bidsapp/ subdirectory inside the specified output_dir. There are three sub-trees: BIDS-organised derivatives, the raw FreeSurfer SUBJECTS_DIR, and the NIDM Turtle files.

<output_dir>/
└── freesurfer-nidm_bidsapp/
    ├── dataset_description.json          # BIDS derivative dataset description
    ├── README                            # Auto-generated derivatives readme
    │
    ├── sub-<id>/                         # BIDS-organised derivatives (single-session)
    │   ├── anat/
    │   │   ├── sub-<id>_desc-brain_T1w.nii.gz
    │   │   ├── sub-<id>_desc-aparcaseg_dseg.nii.gz
    │   │   └── sub-<id>_desc-wmparc_dseg.nii.gz
    │   └── stats/
    │       ├── sub-<id>_aseg.stats
    │       ├── sub-<id>_lh.aparc.stats
    │       └── sub-<id>_rh.aparc.stats
    │
    ├── sub-<id>/                         # BIDS-organised derivatives (multi-session)
    │   └── ses-<session>/
    │       ├── anat/
    │       │   ├── sub-<id>_ses-<session>_desc-brain_T1w.nii.gz
    │       │   ├── sub-<id>_ses-<session>_desc-aparcaseg_dseg.nii.gz
    │       │   └── sub-<id>_ses-<session>_desc-wmparc_dseg.nii.gz
    │       └── stats/
    │           ├── sub-<id>_ses-<session>_aseg.stats
    │           ├── sub-<id>_ses-<session>_lh.aparc.stats
    │           └── sub-<id>_ses-<session>_rh.aparc.stats
    │
    ├── freesurfer/                       # Raw FreeSurfer SUBJECTS_DIR
    │   ├── processing_summary.json       # Per-run processing summary with version info
    │   └── sub-<id>[_ses-<session>]/     # Standard recon-all output directory
    │       ├── mri/
    │       │   ├── brain.mgz
    │       │   ├── aparc.DKTatlas+aseg.mgz
    │       │   └── wmparc.mgz
    │       ├── surf/
    │       │   ├── lh.pial
    │       │   ├── lh.white
    │       │   ├── rh.pial
    │       │   └── rh.white
    │       ├── label/
    │       ├── stats/
    │       │   ├── aseg.stats
    │       │   ├── lh.aparc.stats
    │       │   └── rh.aparc.stats
    │       └── scripts/
    │           └── recon-all.done        # Completion marker
    │
    └── nidm/                             # NIDM Turtle outputs (flat structure)
        ├── sub-<id>.ttl                  # Single-session dataset
        └── sub-<id>_ses-<session>.ttl    # Multi-session dataset

Notes:

  • BIDS-organised derivative files use BIDS-compliant naming (e.g., _desc-brain_T1w.nii.gz, _desc-aparcaseg_dseg.nii.gz) and are placed directly under freesurfer-nidm_bidsapp/sub-<id>/.
  • The freesurfer/sub-<id>[_ses-<session>]/ directory is the standard FreeSurfer subject directory created by recon-all and contains the full set of recon-all outputs.
  • For multi-session datasets the FreeSurfer subject ID is sub-<id>_ses-<session> (e.g. sub-01_ses-baseline).
  • NIDM outputs use a flat directory structure (all .ttl files directly in nidm/). In BABS workflows each job produces one .ttl file named after the subject (and session if applicable).

FreeSurfer Output

The freesurfer/ subdirectory is the FreeSurfer SUBJECTS_DIR. Key files copied into the BIDS-organised tree include:

  • Brain-extracted T1w (brain.mgz → sub-<id>_desc-brain_T1w.nii.gz)
  • Cortical parcellation (aparc.DKTatlas+aseg.mgz → sub-<id>_desc-aparcaseg_dseg.nii.gz)
  • White-matter parcellation (wmparc.mgz → sub-<id>_desc-wmparc_dseg.nii.gz)
  • Surface meshes (lh.white, rh.white, lh.pial, rh.pial)
  • Statistical measures (aseg.stats, lh.aparc.stats, rh.aparc.stats)

NIDM Output

The NIDM outputs are provided in Turtle (.ttl) format with files named according to BIDS conventions (e.g., sub-01.ttl, sub-01_ses-baseline.ttl). The output includes:

  • Comprehensive version information:
    • FreeSurfer version and source (from base image)
    • BIDS app version (from setup.py)
    • Python environment and package versions
  • Processing provenance
  • Volume measurements for brain structures
  • Cortical thickness and surface area measurements
  • Standard identifiers for interoperability

Implementation Notes

This BIDS App uses the pre-built FreeSurfer Docker image vnmd/freesurfer_8.0.0 from Neurodesk as its base image. Neurodesk is a containerized data analysis environment for neuroimaging that provides a suite of neuroimaging tools in Docker containers. These containers are built using Neurodocker, a command-line tool that generates custom Dockerfiles for neuroimaging software.

Using the Neurodesk FreeSurfer image offers several advantages:

  1. Faster build times - no need to download and install FreeSurfer during build
  2. Smaller container size - uses the optimized FreeSurfer image
  3. Improved reliability - uses a verified and tested FreeSurfer installation
  4. Compatibility with FreeSurfer's license terms
  5. Standardized environment - built using the community-supported Neurodocker tool
  6. Regular maintenance - benefits from the Neurodesk project's updates and improvements

License

This BIDS App is licensed under MIT License.

Acknowledgments

References

If you use this BIDS App in your research, please cite:

  1. Fischl B. (2012). FreeSurfer. NeuroImage, 62(2), 774–781. https://doi.org/10.1016/j.neuroimage.2012.01.021
  2. Gorgolewski, K. J., Auer, T., Calhoun, V. D., Craddock, R. C., Das, S., Duff, E. P., Flandin, G., Ghosh, S. S., Glatard, T., Halchenko, Y. O., Handwerker, D. A., Hanke, M., Keator, D., Li, X., Michael, Z., Maumet, C., Nichols, B. N., Nichols, T. E., Pellman, J., Poline, J. B., … Poldrack, R. A. (2016). The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments. Scientific data, 3, 160044. https://doi.org/10.1038/sdata.2016.44
  3. Maumet, C., Auer, T., Bowring, A., Chen, G., Das, S., Flandin, G., Ghosh, S., Glatard, T., Gorgolewski, K. J., Helmer, K. G., Jenkinson, M., Keator, D. B., Nichols, B. N., Poline, J. B., Reynolds, R., Sochat, V., Turner, J., & Nichols, T. E. (2016). Sharing brain mapping statistical results with the neuroimaging data model. Scientific data, 3, 160102. https://doi.org/10.1038/sdata.2016.102
  4. Renton, A.I., Dao, T.T., Johnstone, T. et al. Neurodesk: an accessible, flexible and portable data analysis environment for reproducible neuroimaging. Nat Methods 21, 804–808 (2024). https://doi.org/10.1038/s41592-023-02145-x

About

A BIDS App implementation for FreeSurfer that provides standardized surface reconstruction and morphometric analysis with NIDM output.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

3 watching

Forks

4 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages