nipype.interfaces.t1prep.preprocess module¶
Nipype interfaces for the T1Prep segmentation pipeline.
T1Prep – full pipeline (skull-strip → segment → surface).
T1PrepSegment – segmentation stage (python -m t1prep.segment).
- class nipype.interfaces.t1prep.preprocess.T1Prep(command=None, terminal_output=None, write_cmdline=False, **inputs)¶
Bases:
T1PrepCommandWrapped executable:
python.Nipype interface for the T1Prep T1-weighted MRI preprocessing pipeline.
T1Prep preprocesses T1-weighted MRI data through three stages:
Skull-stripping – deep-learning-based brain extraction via DeepMriPrep / deepbet.
Tissue segmentation – GM / WM / CSF probability maps and optional nonlinear warp to MNI space via DeepMriPrep; optionally refined with AMAP.
Cortical surface estimation – central, pial and white matter surfaces, thickness, area, sulcal depth, and optional spherical atlas-based parcellation via CAT-Surface (
cat-surf).
Output naming follows CAT12 conventions by default; BIDS derivatives naming is selected with
bids=True.This interface invokes
python -m t1prep.t1prep(the pure-Python pipeline entry point). For multi-subject parallelism prefer running multiple nodes in a nipype workflow rather than using--multi.Examples
Full pipeline with BIDS naming:
>>> t1 = T1Prep() >>> t1.inputs.in_files = ['sub-01_T1w.nii.gz'] >>> t1.inputs.out_dir = 'derivatives' >>> t1.inputs.bids = True >>> t1.cmdline 'python -m t1prep.t1prep --bids --out-dir derivatives sub-01_T1w.nii.gz'
Segmentation only (skip surface estimation):
>>> t1 = T1Prep() >>> t1.inputs.in_files = ['sub-01_T1w.nii.gz'] >>> t1.inputs.no_surf = True >>> t1.inputs.p = True >>> t1.cmdline 'python -m t1prep.t1prep --no-surf --p sub-01_T1w.nii.gz'
References
https://github.com/ChristianGaser/T1Prep
Mandatory Inputs¶
- in_filesa list of items which are a pathlike object or string representing an existing file
Input T1-weighted NIfTI file(s) (.nii or .nii.gz). Maps to a command-line argument:
%s(position: -1).
Optional Inputs¶
- amapa boolean
Use AMAP segmentation for a refined tissue classification after the initial DeepMriPrep estimate. Maps to a command-line argument:
--amap.- argsa string
Additional parameters to the command. Maps to a command-line argument:
%s.- atlasa string
Comma-separated volumetric atlas list for ROI estimation, e.g. “‘neuromorphometrics’,’suit’”. Default: “‘neuromorphometrics’, ‘cobra’”. Maps to a command-line argument:
--atlas %s.- atlas_surfa string
Comma-separated surface atlas list, e.g. “‘aparc_DK40.freesurfer’,’aparc_a2009s.freesurfer’”. Maps to a command-line argument:
--atlas-surf %s.- bidsa boolean
Use BIDS derivatives naming conventions for output files. Maps to a command-line argument:
--bids.- csfa boolean
Additionally save CSF segmentation (GM and WM are always saved when –p or –rp are set). Maps to a command-line argument:
--csf.- debuga boolean
Enable verbose output and retain all intermediate files. Maps to a command-line argument:
--debug.- downsamplea float
Mesh downsampling factor for the initial surface extraction step. Maps to a command-line argument:
--downsample %g.- environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value:
{})- fmriprepa boolean
Save fMRIPrep-compatible outputs: ANTs/ITK .h5 deformation fields, dseg files, cortex mask, inflated surfaces, and spatially registered data at 2 mm resolution. Maps to a command-line argument:
--fmriprep.- gza boolean
Write compressed (.nii.gz) NIfTI outputs. Maps to a command-line argument:
--gz.- initial_surfa pathlike object or string representing a file
Pre-existing central surface file for longitudinal processing. Maps to a command-line argument:
--initial-surf %s.- lesionsa boolean
Additionally save white-matter hyperintensity (WMH) lesion segmentation in native and/or affine space. Maps to a command-line argument:
--lesions.- long_dataa pathlike object or string representing a directory
Longitudinal mode: process the volume at PATH but keep output naming and folder structure based on the primary input file. Maps to a command-line argument:
--long-data %s.- median_filteran integer
Number of median filter passes applied before surface extraction. Maps to a command-line argument:
--median-filter %d.- no_atlasa boolean
Disable atlas labelling and ROI volume export. Maps to a command-line argument:
--no-atlas.- no_correct_foldinga boolean
Disable cortical thickness correction for folding effects. Maps to a command-line argument:
--no-correct-folding.- no_mwpa boolean
Disable saving of modulated warped (MNI-space) segmentations (they are saved by default). Maps to a command-line argument:
--no-mwp.- no_overwritea string
Skip a subject when files matching this glob pattern already exist (e.g. ‘surf/lh.thickness.’). Maps to a command-line argument:
--no-overwrite %s.- no_retrya boolean
Disable automatic retry of failed processing steps (by default a failed step is retried once). Maps to a command-line argument:
--no-retry.- no_sega boolean
Skip tissue segmentation (surface processing only). Maps to a command-line argument:
--no-seg.- no_sphere_rega boolean
Skip spherical surface registration and atlas resampling. Maps to a command-line argument:
--no-sphere-reg.- no_surfa boolean
Skip cortical surface and thickness estimation. Maps to a command-line argument:
--no-surf.- out_dira pathlike object or string representing a directory
Base output directory. If unset, results are placed in subfolders of the input file’s directory. Maps to a command-line argument:
--out-dir %s.- pa boolean
Additionally save native-space segmentation maps. Maps to a command-line argument:
--p.- pial_whitea boolean
Estimate and save pial and white matter surfaces. Maps to a command-line argument:
--pial-white.- pre_fwhma float
Pre-smoothing FWHM (mm) applied before marching cubes surface extraction. Maps to a command-line argument:
--pre-fwhm %g.- quieta boolean
Suppress progress messages (overrides the default verbose mode). Maps to a command-line argument:
--quiet.- rpa boolean
Additionally save affine-registered segmentations. Maps to a command-line argument:
--rp.- seedan integer
Random seed for deterministic processing. Maps to a command-line argument:
--seed %d.- skip_skullstripa boolean
Skip skull-stripping (assumes the input is already skull-stripped with background close to zero). Maps to a command-line argument:
--skip-skullstrip. Mutually exclusive with inputs:skullstrip_only.- skullstrip_onlya boolean
Run skull-stripping only, write skull-stripped image and brain mask to the MRI output folder, then exit. Maps to a command-line argument:
--skullstrip-only. Mutually exclusive with inputs:skip_skullstrip.- thickness_method1 or 2 or 3
Cortical thickness estimation method: 1 = Tfs-distance (FreeSurfer-like, PBT-based); 2 = pial-to-white surface distance; 3 = pure projection-based thickness (PBT). Maps to a command-line argument:
--thickness-method %d.- vessela float
Blood-vessel correction strength (0 = disabled; default 1.0). Maps to a command-line argument:
--vessel %g.- wpa boolean
Additionally save non-modulated warped (MNI-space) segmentations. Maps to a command-line argument:
--wp.
Outputs¶
- label_dira pathlike object or string representing a directory
Label sub-directory (atlas ROI JSON).
- mri_dira pathlike object or string representing a directory
MRI sub-directory (segmentations, brain mask, etc.).
- out_dira pathlike object or string representing a directory
Top-level output directory.
- report_dira pathlike object or string representing a directory
Report sub-directory (logs, QC JSON).
- surf_dira pathlike object or string representing a directory
Surface sub-directory (central, pial, white surfaces).
- class nipype.interfaces.t1prep.preprocess.T1PrepSegment(command=None, terminal_output=None, write_cmdline=False, **inputs)¶
Bases:
T1PrepCommandWrapped executable:
python.Nipype interface for the T1Prep segmentation module (
t1prep.segment).Performs skull-stripping, bias field correction, and tissue segmentation (GM / WM / CSF) on a single T1-weighted NIfTI image using DeepMriPrep. Optionally applies AMAP refinement, blood-vessel correction, WMH lesion detection, nonlinear warping to MNI space, and atlas-based ROI volume export.
This is the segmentation stage of the T1Prep pipeline and can be run independently of surface estimation. Pass
surf=Trueto also emit the hemisphere partition maps (p0 left/right) needed for the surface stage.Invoked as
python -m t1prep.segment.Examples
>>> seg = T1PrepSegment() >>> seg.inputs.in_file = 'sub-01_T1w.nii.gz' >>> seg.inputs.mri_dir = 'out/mri' >>> seg.inputs.report_dir = 'out/report' >>> seg.inputs.label_dir = 'out/label' >>> seg.inputs.surf = True >>> seg.inputs.gz = True >>> seg.cmdline 'python -m t1prep.segment --gz --surf --input sub-01_T1w.nii.gz --label-dir out/label --mri-dir out/mri --report-dir out/report'
Save native-space GM and WM maps plus CSF:
>>> seg = T1PrepSegment() >>> seg.inputs.in_file = 'sub-01_T1w.nii.gz' >>> seg.inputs.mri_dir = 'out/mri' >>> seg.inputs.report_dir = 'out/report' >>> seg.inputs.label_dir = 'out/label' >>> seg.inputs.p = True >>> seg.inputs.csf = True >>> seg.cmdline 'python -m t1prep.segment --csf --p --input sub-01_T1w.nii.gz --label-dir out/label --mri-dir out/mri --report-dir out/report'
Mandatory Inputs¶
- in_filea pathlike object or string representing an existing file
Input T1-weighted NIfTI image (.nii or .nii.gz). Maps to a command-line argument:
--input %s.- label_dira pathlike object or string representing a directory
Output directory for label and atlas-ROI JSON outputs. Maps to a command-line argument:
--label-dir %s.- mri_dira pathlike object or string representing a directory
Output directory for MRI volumes (segmentations, brain mask, deformations). Maps to a command-line argument:
--mri-dir %s.- report_dira pathlike object or string representing a directory
Output directory for report log files. Maps to a command-line argument:
--report-dir %s.
Optional Inputs¶
- amapa boolean
Refine the initial DeepMriPrep segmentation using AMAP (Adaptive Maximum A Posteriori) tissue classification. Maps to a command-line argument:
--amap.- argsa string
Additional parameters to the command. Maps to a command-line argument:
%s.- atlasa string
Comma-separated atlas list for ROI estimation, e.g. “Neuromorphometrics,SUIT”. Leave empty to disable ROI export. Maps to a command-line argument:
--atlas %s.- bidsa boolean
Use BIDS derivatives naming conventions for output files. Maps to a command-line argument:
--bids.- countan integer
Total number of pipeline steps for the progress bar (used when called from the T1Prep orchestration script). Maps to a command-line argument:
--count %d.- csfa boolean
Save CSF segmentation probability map in addition to GM and WM. Maps to a command-line argument:
--csf.- debuga boolean
Enable verbose output and retain all temporary files. Maps to a command-line argument:
--debug.- environa dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’
Environment variables. (Nipype default value:
{})- gza boolean
Save compressed NIfTI outputs (.nii.gz). Maps to a command-line argument:
--gz.- lesionsa boolean
Save white-matter hyperintensity (WMH) lesion segmentation in native and/or affine space. Maps to a command-line argument:
--lesions.- mwpa boolean
Save modulated warped (MNI-space) GM and WM segmentation maps. Maps to a command-line argument:
--mwp.- pa boolean
Save native-space probability segmentation maps. Maps to a command-line argument:
--p.- rpa boolean
Save affine-registered segmentation maps. Maps to a command-line argument:
--rp.- save_fmriprepa boolean
Save ANTs/ITK-compatible HDF5 (.h5) deformation fields, discrete segmentation (dseg), and brain mask for fMRIPrep compatibility. Maps to a command-line argument:
--save-fmriprep.- seedan integer
Random seed for reproducibility. Maps to a command-line argument:
--seed %d.- skip_skullstripa boolean
Skip skull-stripping (input is already skull-stripped). Maps to a command-line argument:
--skip-skullstrip. Mutually exclusive with inputs:skullstrip_only.- skullstrip_onlya boolean
Run skull-stripping only, save outputs, then exit. Maps to a command-line argument:
--skullstrip-only. Mutually exclusive with inputs:skip_skullstrip.- surfa boolean
Save partitioned hemisphere segmentation maps (p0 left/right) required for the subsequent surface estimation stage. Maps to a command-line argument:
--surf.- verbosea boolean
Print progress output. Maps to a command-line argument:
--verbose.- vessela float
Blood-vessel correction strength (0 = disabled; default 1.0). Reduces vessel-related intensity artefacts before segmentation. Maps to a command-line argument:
--vessel %g.- wpa boolean
Save non-modulated warped (MNI-space) segmentation maps. Maps to a command-line argument:
--wp.
Outputs¶
- label_dira pathlike object or string representing a directory
Label output directory with atlas ROI JSON files.
- mri_dira pathlike object or string representing a directory
MRI output directory with segmentation volumes.
- report_dira pathlike object or string representing a directory
Report output directory with log files.