Skip to content
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 \
  /data /output participant \
  --participant-label 01 \
  --fs-license-file /license.txt

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 \
  /data /output participant \
  --participant-label 01 \
  --fs-license-file /license.txt

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 \
  /data /output participant \
  --participant-label sub-01 \
  --fs-license-file /license.txt

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: Processing level. Choices are participant and session.

  • Optional arguments:

    • --participant-label: One participant label, with or without the sub- prefix.
    • --session-label: One session label, with or without the ses- prefix. It is accepted in participant mode for BABS session-wise jobs.
    • --fs-license-file: Path to the FreeSurfer license file.
    • --skip-bids-validation: Skip PyBIDS validation.
    • --skip-freesurfer: Reuse a completed recon-all directory and run only the remaining export steps.
    • --skip-nidm: Skip NIDM output generation.
    • --nidm-input-dir: Directory containing an existing NIDM document to augment.
    • --verbose: Enable debug logging.

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 \
           freesurfer-nidm-bidsapp \
           /bids_dataset /output participant \
           --participant-label 01 --fs-license-file /license.txt

# Using Apptainer (for clusters)
apptainer run \
  --bind /path/to/license.txt:/license.txt,/path/to/bids_dataset:/data,/path/to/output:/output \
  freesurfer.sif \
  /data /output participant \
  --participant-label 01 \
  --fs-license-file /license.txt

Process one session explicitly:

apptainer run \
  --bind /path/to/license.txt:/license.txt,/path/to/bids_dataset:/data,/path/to/output:/output \
  freesurfer.sif \
  /data /output session \
  --participant-label 01 \
  --session-label baseline \
  --fs-license-file /license.txt

The CLI processes one participant or participant/session pair per invocation. Use a scheduler or BABS job array for dataset-level parallelism.

BABS compatibility

The app supports both the original BABS project layout and the configurable BIDS-study layout introduced by PennLINC/babs PR #369. The new layout places the analysis DataLad dataset at the BABS project root and its RIA stores beneath .babs/:

analysis_path: "."
input_ria_path: ".babs/input_ria"
output_ria_path: ".babs/output_ria"

See examples/babs-freesurfer-nidm-bids-study.yaml for a complete template. It requires a BABS revision containing PR #369. Omit those three path settings to use the legacy analysis/, input_ria/, and output_ria/ layout.

BABS invokes the standard positional analysis level participant for both subject-wise and session-wise jobs. For a session-wise job, configure $SESSION_SELECTION_FLAG: "--session-label"; this app honors that explicit label and only falls back to auto-detection when exactly one session is visible. If an upstream NIDM dataset is used, configure --nidm-input-dir explicitly in the BABS YAML.

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
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

3 watching

Forks

4 forks
Report repository

Releases

Packages

Used by

Contributors

Languages