presurfer-box

MATLAB-free MP2RAGE preprocessing using SPM Standalone in Docker, Singularity, or Apptainer.

presurfer-box runs presurfer workflows in the official SPM Standalone container, so it does not need a local MATLAB installation or licence. The original MATLAB implementation remains available as a Git submodule.

Status: This implementation uses SPM25 Standalone. Results have not yet been numerically validated against the historical SPM12/MATLAB pipeline.

Install

presurfer-box needs Python 3.11 or later and either Docker, Singularity, or Apptainer. Install it from PyPI:

pip install presurfer

To work on the code, clone the repository instead:

git clone https://github.com/srikash/presurfer-box.git
cd presurfer-box

Fetch the pinned legacy MATLAB submodule only when you need to inspect or run the historical implementation:

git submodule update --init --recursive

Docker

docker pull ghcr.io/spm/spm-docker:docker-matlab-25.01.02
presurfer-box --check

Singularity / Apptainer

singularity pull --name spm.sif \
  oras://ghcr.io/spm/spm-docker:singularity-matlab-25.01.02

presurfer-box --sif spm.sif --check

Quick start

# Create a bias-corrected image and bias field
presurfer-box biascorrect IMAGE.nii

# Create MPRAGEised UNI
presurfer-box MPRAGEise INV2.nii UNI.nii

# Create an INV2-derived strip mask
presurfer-box stripmask INV2.nii

# Create UNI tissue classes, brain mask, and white-matter mask
presurfer-box brainmask UNI.nii

Use a local Singularity or Apptainer image with --sif:

presurfer-box --sif spm.sif stripmask INV2.nii

Docker is the default runtime. Use --image IMAGE to select another image.

Each run writes to a new UTC timestamped directory beside its input, for example 250101T12:34:56_presurfer/presurf_INV2/. Same-second runs receive a numeric suffix. MPRAGEise's intermediate bias-correction directory begins with tmp_ and is removed after processing.

Development

uv sync
uv run ruff format --check
uv run ruff check
uv run mypy .
uv run pytest

Choose a workflow

MPRAGEise bias-corrects INV2, min-max normalises the corrected INV2, then multiplies it voxelwise with UNI. It does not run the strip-mask workflow.

Python API

from presurfer import spm_biascorrect, spm_mprageise, spm_seg, spm_stripmask

spm_biascorrect("INV2.nii")
spm_mprageise("INV2.nii", "UNI.nii")
spm_stripmask("INV2.nii")
spm_seg("UNI.nii")

All functions accept image= and runtime= keywords. Use runtime="singularity" with a local SIF path passed as image=.

Outputs

Each workflow writes its output beneath a timestamped run directory beside the input:

YYMMDDThh:mm:ss_presurfer/presurf_biascorrect/
YYMMDDThh:mm:ss_presurfer/presurf_MPRAGEise/
YYMMDDThh:mm:ss_presurfer/presurf_INV2/
YYMMDDThh:mm:ss_presurfer/presurf_UNI/

Compressed .nii.gz inputs are supported. The source file stays unchanged and the workflow creates an uncompressed working copy in the output directory.

Legacy MATLAB implementation

The original MATLAB implementation lives in srikash/presurfer and remains available here as a pinned Git submodule:

src/matlab/presurfer

For MATLAB use:

addpath('src/matlab/presurfer/func')

Update the submodule only when adopting a newer presurfer commit deliberately.

Reproducibility and validation

• Default image: ghcr.io/spm/spm-docker:docker-matlab-25.01.02
• SPM runtime: SPM25 Standalone
• Historical implementation: SPM12 with MATLAB
• Numerical equivalence has not yet been validated with reference NIfTI data.

Licence

MIT. See LICENSE.

Citation

See CITATION.cff.