nipype.interfaces.t1prep package¶

Interfaces for T1Prep – T1-weighted MRI preprocessing pipeline (PyCAT).

T1Prep performs skull-stripping, tissue segmentation, and cortical surface reconstruction using DeepMriPrep and the CAT-Surface library (via cat-surf).

Sub-module interfaces¶

T1Prep: Full pipeline: skull-strip → segment → surface estimate. Wraps python -m t1prep.t1prep.
T1PrepSegment: Segmentation stage only. Wraps python -m t1prep.segment.
T1PrepSurfaceEstimation: Surface-estimation stage for one hemisphere. Wraps python -m t1prep.surface_estimation.
T1PrepRealignLongitudinal: Rigid realignment of longitudinal T1w time-points. Wraps python -m t1prep.realign_longitudinal.

Base classes¶

Info: T1Prep package version detection.
T1PrepCommand: Base CommandLine for python -m t1prep.<module> invocations.

A focused subset of the cat_surf API — the volume-denoising and volume/ boundary registration interfaces needed to replace FreeSurfer / FSL (bbreg) / ANTs in an fMRIPrep-style pipeline — is exported directly from this package (CatSurfVolSanlm, CatSurfBbreg, CatSurfBbregDetectContrast, CatSurfVolumeRegisterNmi, CatSurfVolumeRegisterRobust). The full per-function interface set is archived for reference in the CAT-Surface repository under cat_surface_cython/examples/nipype/.

class nipype.interfaces.t1prep.CatSurfBbreg(from_file=None, resource_monitor=None, **inputs)¶

Bases: SimpleInterface

Boundary-based registration of a volume to an anatomical reference.

Wraps cat_surf.bbreg(in_file, lh_surface=…, rh_surface=…, ref_file=…, invert_contrast=…, fwhm=…, verbose=…) → (matrix, cost) and writes the 4×4 affine to out_matrix_file. This replaces FSL bbregister / flirt -bbr in an fMRIPrep-style pipeline.

The white-matter surfaces are read from disk and passed as (vertices, faces) arrays to cat_surf.bbreg.

Examples

>>> node = CatSurfBbreg()
>>> node.inputs.in_file = 'bold_ref.nii.gz'
>>> node.inputs.ref_file = 'sub-01_T1w.nii.gz'
>>> node.inputs.lh_surface = 'lh.white.sub-01.gii'
>>> node.inputs.rh_surface = 'rh.white.sub-01.gii'
>>> res = node.run()

Mandatory Inputs¶

in_filea pathlike object or string representing an existing file: Moving/functional NIfTI image to register (e.g. BOLD reference).

Optional Inputs¶

fwhma float: Pre-smoothing FWHM applied for BBR (mm). (Nipype default value: 0.0)
invert_contrastan integer: Contrast: 0 = T1/FLAIR, 1 = T2/BOLD, -1 = auto-detect. (Nipype default value: -1)
lh_surfacea pathlike object or string representing an existing file: Left white-matter surface used for the BBR cost.
out_matrix_filea pathlike object or string representing a file: Output affine transform path (moving RAS → fixed RAS).
ref_filea pathlike object or string representing an existing file: Reference T1w NIfTI used for NMI initialisation before BBR.
rh_surfacea pathlike object or string representing an existing file: Right white-matter surface used for the BBR cost.
verbosea boolean: Print diagnostic output. (Nipype default value: False)

Outputs¶

costa float: Final BBR cost (lower is better).
out_matrix_filea pathlike object or string representing a file: 4×4 affine transform (moving RAS → fixed RAS).

class nipype.interfaces.t1prep.CatSurfBbregDetectContrast(from_file=None, resource_monitor=None, **inputs)¶

Bases: SimpleInterface

Detect the image contrast (WM vs GM polarity) for BBR.

Wraps cat_surf.bbreg_detect_contrast(in_file, lh_surface=…, rh_surface=…) → int. The integer feeds CatSurfBbreg.invert_contrast.

Examples

>>> node = CatSurfBbregDetectContrast()
>>> node.inputs.in_file = 'bold_ref.nii.gz'
>>> res = node.run()
>>> res.outputs.contrast                     # 0, 1, or -1

Mandatory Inputs¶

in_filea pathlike object or string representing an existing file: NIfTI volume whose contrast to detect.

Optional Inputs¶

lh_surfacea pathlike object or string representing an existing file: Optional left white-matter surface for sampling.
rh_surfacea pathlike object or string representing an existing file: Optional right white-matter surface for sampling.

Outputs¶

contrastan integer: 0 = T1/FLAIR (WM brighter), 1 = T2/BOLD (WM darker), -1 = undetermined.

class nipype.interfaces.t1prep.CatSurfVolSanlm(from_file=None, resource_monitor=None, **inputs)¶

Bases: SimpleInterface

Apply SANLM (Spatially Adaptive Non-Local Means) denoising to a volume.

Wraps the file-based cat_surf.cli.vol_sanlm(in_file, out_file, is_rician=…, strength=…) (CAT_VolSanlm). T1Prep applies SANLM denoising as the first preprocessing step on the raw T1w data.

Examples

>>> node = CatSurfVolSanlm()
>>> node.inputs.in_file = 'sub-01_T1w.nii.gz'
>>> res = node.run()
>>> res.outputs.out_file            # denoised volume

Mandatory Inputs¶

in_filea pathlike object or string representing an existing file: Input NIfTI volume to denoise.

Optional Inputs¶

is_riciana boolean: Assume Rician (rather than Gaussian) noise. (Nipype default value: False)
out_filea pathlike object or string representing a file: Output denoised NIfTI path.
strengtha float: Denoising strength (default 1.0). (Nipype default value: 1.0)

Outputs¶

out_filea pathlike object or string representing a file: Denoised NIfTI volume.

class nipype.interfaces.t1prep.CatSurfVolumeRegisterNmi(from_file=None, resource_monitor=None, **inputs)¶

Bases: SimpleInterface

Cross-modal rigid registration by Normalised Mutual Information.

Wraps cat_surf.volume_register_nmi(fixed_file, moving_file, n_levels=…, n_bins=…, max_iter=…, verbose=…) → (matrix, nmi) and writes the 4×4 affine to out_matrix_file — an in-process replacement for an ANTs cross-modal affine step.

Examples

>>> node = CatSurfVolumeRegisterNmi()
>>> node.inputs.moving_file = 'sub-01_T1w.nii.gz'
>>> node.inputs.fixed_file = 'template_T1.nii.gz'
>>> res = node.run()

Mandatory Inputs¶

fixed_filea pathlike object or string representing an existing file: Fixed (reference) NIfTI image.
moving_filea pathlike object or string representing an existing file: Moving (source) NIfTI image.

Optional Inputs¶

max_iteran integer: Maximum optimiser iterations per level. (Nipype default value: 30)
n_binsan integer: Joint-histogram bins for NMI (default 64). (Nipype default value: 64)
n_levelsan integer: Multi-resolution pyramid levels (default 4). (Nipype default value: 4)
out_matrix_filea pathlike object or string representing a file: Output affine transform path (moving RAS → fixed RAS).
verbosea boolean: Print diagnostic output. (Nipype default value: False)

Outputs¶

nmia float: Final NMI value (higher is better).
out_matrix_filea pathlike object or string representing a file: 4×4 affine transform (moving RAS → fixed RAS).

class nipype.interfaces.t1prep.CatSurfVolumeRegisterRobust(from_file=None, resource_monitor=None, **inputs)¶

Bases: SimpleInterface

Same-modality rigid registration via robust (Tukey biweight) M-estimation.

Wraps cat_surf.volume_register_robust(fixed_file, moving_file, n_levels=…, sat_k=…, max_iter=…, verbose=…) → (matrix, residual) and writes the 4×4 affine to out_matrix_file. Less sensitive to intensity outliers (e.g. lesions) than the NMI variant; an in-process replacement for an ANTs same-modality affine step.

Examples

>>> node = CatSurfVolumeRegisterRobust()
>>> node.inputs.moving_file = 'sub-01_T1w.nii.gz'
>>> node.inputs.fixed_file = 'sub-01_T1w_ref.nii.gz'
>>> res = node.run()

Mandatory Inputs¶

fixed_filea pathlike object or string representing an existing file: Fixed (reference) NIfTI image.
moving_filea pathlike object or string representing an existing file: Moving (source) NIfTI image.

Optional Inputs¶

max_iteran integer: Maximum optimiser iterations per level. (Nipype default value: 20)
n_levelsan integer: Multi-resolution pyramid levels (default 4). (Nipype default value: 4)
out_matrix_filea pathlike object or string representing a file: Output affine transform path (moving RAS → fixed RAS).
sat_ka float: Tukey biweight saturation constant (default 4.685). (Nipype default value: 4.685)
verbosea boolean: Print diagnostic output. (Nipype default value: False)

Outputs¶

out_matrix_filea pathlike object or string representing a file: 4×4 affine transform (moving RAS → fixed RAS).
residuala float: Final normalised residual (lower is better).

class nipype.interfaces.t1prep.Info¶

Bases: PackageInfo

T1Prep package information.

Examples

>>> from nipype.interfaces.t1prep import Info
>>> Info.version()

static parse_version(raw_info)¶

classmethod version()¶

class nipype.interfaces.t1prep.T1Prep(command=None, terminal_output=None, write_cmdline=False, **inputs)¶

Bases: T1PrepCommand

Wrapped 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.T1PrepCommand(command=None, terminal_output=None, write_cmdline=False, **inputs)¶

Bases: CommandLine

Wrapped executable: python.

Base class for T1Prep command-line interfaces.

Sub-classes set _module to the dotted name of the T1Prep sub-module to invoke (e.g. "t1prep.segment"). The full command is assembled lazily from sys.executable so the active interpreter is always used, even if it changes after import.

Optional Inputs¶

argsa string: Additional parameters to the command. Maps to a command-line argument: %s.
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: {})

property cmd¶: sets base command, immutable

property version¶: interfaces should implement a version property

class nipype.interfaces.t1prep.T1PrepRealignLongitudinal(command=None, terminal_output=None, write_cmdline=False, **inputs)¶

Bases: T1PrepCommand

Wrapped executable: python.

Nipype interface for the T1Prep longitudinal realignment module.

Estimates per-timepoint rigid (6-DoF) transforms and optionally refines them against a mean template, then writes resampled volumes and/or updates NIfTI headers in place. Mirrors SPM’s realign module.

Invoked as python -m t1prep.realign_longitudinal.

Examples

>>> ra = T1PrepRealignLongitudinal()
>>> ra.inputs.in_files = ['sub-01_ses-01_T1w.nii.gz', 'sub-01_ses-02_T1w.nii.gz']
>>> ra.inputs.out_dir = 'derivatives/realign'
>>> ra.inputs.save_resampled = True
>>> ra.cmdline
'python -m t1prep.realign_longitudinal --inputs sub-01_ses-01_T1w.nii.gz sub-01_ses-02_T1w.nii.gz --out-dir derivatives/realign --save-resampled'

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 NIfTI images (one per longitudinal time-point). Maps to a command-line argument: --inputs %s.
out_dira pathlike object or string representing a directory: Output directory for realigned volumes and transforms. Maps to a command-line argument: --out-dir %s.

Optional Inputs¶

argsa string: Additional parameters to the command. Maps to a command-line argument: %s.
devicea string: Compute device (currently reserved; default ‘cpu’). Maps to a command-line argument: --device %s.
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: {})
force_template_zoomsa boolean: Force the reference (template) zooms on all outputs. Maps to a command-line argument: --force-template-zooms.
grad_quantilea float: Quantile threshold for the gradient sampler (only used when sample_strategy=’gradient’; default 0.80). Maps to a command-line argument: --grad-quantile %g.
inverse_consistenta boolean: Re-center rigid transforms around their SE(3) barycenter. Maps to a command-line argument: --inverse-consistent.
iterationsan integer: Number of multi-scale alignment passes (default 3). Maps to a command-line argument: --iterations %d.
max_fwhm_mma float: Maximum smoothing FWHM in mm for the multi-scale pyramid (default 6.0). Maps to a command-line argument: --max-fwhm-mm %g.
no_intensity_scalea boolean: Disable SPM-like per-volume intensity scaling. Maps to a command-line argument: --no-intensity-scale.
out_subfoldersa list of items which are a string: Per-input output subfolder names (must match the number of inputs). Maps to a command-line argument: --out-subfolders %s.
output_naming‘bids’ or ‘legacy’: Output naming convention: ‘bids’ (default) or ‘legacy’. Maps to a command-line argument: --output-naming %s.
overlap_penalty_weighta float: Weight of the overlap penalty term (default 0.0). Maps to a command-line argument: --overlap-penalty-weight %g.
register_to_firsta boolean: Register all volumes to the first input (skip mean-template refinement). Maps to a command-line argument: --register-to-first.
sample_strategy‘grid’ or ‘gradient’: Sample-point selection: ‘grid’ (default) or ‘gradient’. Maps to a command-line argument: --sample-strategy %s.
save_resampleda boolean: Write resampled copies of the inputs in reference space. Maps to a command-line argument: --save-resampled.
save_templatea boolean: Save the reference volume used as the alignment target. Maps to a command-line argument: --save-template.
set_zooms_from_sforma boolean: Copy pixdim/zooms from the sform when updating headers. Maps to a command-line argument: --set-zooms-from-sform.
update_headersa boolean: Only update the NIfTI headers with the estimated affines; do not write resampled volumes. Maps to a command-line argument: --update-headers.
use_skullstripa boolean: Estimate transforms on skull-stripped copies of the inputs. Maps to a command-line argument: --use-skullstrip.
verbosea boolean: Print optimizer diagnostics. Maps to a command-line argument: --verbose.

Outputs¶

out_dira pathlike object or string representing a directory: Top-level output directory.

class nipype.interfaces.t1prep.T1PrepSegment(command=None, terminal_output=None, write_cmdline=False, **inputs)¶

Bases: T1PrepCommand

Wrapped 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=True to 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.

class nipype.interfaces.t1prep.T1PrepSurfaceEstimation(command=None, terminal_output=None, write_cmdline=False, **inputs)¶

Bases: T1PrepCommand

Wrapped executable: python.

Nipype interface for the T1Prep surface estimation module.

Reconstructs the cortical central surface from hemisphere partition maps (produced by T1PrepSegment) and computes per-vertex cortical thickness, surface area, and optionally pial/white surfaces, spherical inflation, and DARTEL-based atlas registration.

The module mirrors the surface_estimation() bash function in scripts/T1Prep but runs entirely in-process via the cat_surf Python bindings. Run it separately for each hemisphere (side='left' and side='right').

Invoked as python -m t1prep.surface_estimation.

Examples

Left hemisphere with default settings:

>>> surf = T1PrepSurfaceEstimation()
>>> surf.inputs.bname = 'sub-01_T1w'
>>> surf.inputs.side = 'left'
>>> surf.inputs.mri_dir = 'out/mri'
>>> surf.inputs.surf_dir = 'out/surf'
>>> surf.inputs.names_tsv = '/opt/T1Prep/src/t1prep/data/Names.tsv'
>>> surf.inputs.surf_templates_dir = '/opt/T1Prep/src/t1prep/data/templates_surfaces_32k'
>>> surf.inputs.atlas_templates_dir = '/opt/T1Prep/src/t1prep/data/atlases_surfaces_32k'
>>> surf.cmdline
'python -m t1prep.surface_estimation --bname sub-01_T1w --side left ...'

Skip spherical registration (faster, no atlas parcellation):

>>> surf.inputs.estimate_spherereg = 0
>>> surf.inputs.save_pial_white = 0

References

https://github.com/ChristianGaser/T1Prep https://github.com/ChristianGaser/CAT-Surface

Mandatory Inputs¶

atlas_templates_dira pathlike object or string representing a directory: Directory containing surface atlas annotation files used for atlas-based parcellation (e.g. atlases_surfaces_32k). Maps to a command-line argument: --atlas-templates-dir %s.
bnamea string: Subject basename – the filename stem of the T1w NIfTI without path or extension (e.g. ‘sub-01_T1w’). Maps to a command-line argument: --bname %s.
mri_dira pathlike object or string representing a directory: Directory containing the MRI volumes produced by t1prep.segment (e.g. hemisphere partition maps p0 left/right). Maps to a command-line argument: --mri-dir %s.
names_tsva pathlike object or string representing an existing file: Path to the Names.tsv file that defines the mapping between internal pipeline codes and output filenames for both CAT12 and BIDS naming conventions. Maps to a command-line argument: --names-tsv %s.
side‘left’ or ‘right’: Hemisphere to process (‘left’ or ‘right’). Maps to a command-line argument: --side %s.
surf_dira pathlike object or string representing a directory: Output directory for surface files. Maps to a command-line argument: --surf-dir %s.
surf_templates_dira pathlike object or string representing a directory: Directory containing the FreeSurfer-average surface template files used for spherical registration (e.g. templates_surfaces_32k). Maps to a command-line argument: --surf-templates-dir %s.

Optional Inputs¶

argsa string: Additional parameters to the command. Maps to a command-line argument: %s.
atlas_surfa string: Comma-separated surface atlas list for annotation resampling, e.g. ‘aparc_DK40.freesurfer,aparc_a2009s.freesurfer’. Maps to a command-line argument: --atlas-surf %s.
bids_namingan integer: Use BIDS derivatives naming conventions (0 = CAT12-style, 1 = BIDS; default 0). Maps to a command-line argument: --bids-naming %d. (Nipype default value: 0)
correct_foldingan integer: Apply folding-based cortical thickness correction (0 = no, 1 = yes; default 0). Maps to a command-line argument: --correct-folding %d. (Nipype default value: 0)
debugan integer: Retain intermediate files and write extra debug outputs (0 = no, 1 = yes; default 0). Maps to a command-line argument: --debug %d. (Nipype default value: 0)
downsamplea float: Target mesh downsampling factor. 0 = apply a fixed 4:1 quadric-based reduction after marching cubes; >0 = keep the mesh at native resolution (default 0). Maps to a command-line argument: --downsample %g. (Nipype default value: 0.0)
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: {})
estimate_sphereregan integer: Perform spherical inflation + DARTEL registration + atlas resampling (0 = skip, 1 = run; default 1). Maps to a command-line argument: --estimate-spherereg %d. (Nipype default value: 1)
fmriprepan integer: Generate additional fMRIPrep-compatible surface outputs: curvature (sulcal depth), cortex mask, and mid-surface inflated sphere (0 = no, 1 = yes; default 0). Maps to a command-line argument: --fmriprep %d. (Nipype default value: 0)
initial_surfacea pathlike object or string representing a file: Path to a pre-existing central surface file. When provided the marching-cubes step is skipped and this surface is used as the starting point (longitudinal processing). Maps to a command-line argument: --initial-surface %s.
median_filteran integer: Number of median filter passes applied before surface extraction (default 2). Maps to a command-line argument: --median-filter %d. (Nipype default value: 2)
multian integer: Number of parallel worker threads for CAT-Surface operations (-1 = auto-detect available CPUs; default -1). Maps to a command-line argument: --multi %d. (Nipype default value: -1)
nii_exta string: File extension for NIfTI volume outputs (default ‘nii.gz’). Maps to a command-line argument: --nii-ext %s. (Nipype default value: nii.gz)
pre_fwhma float: Pre-smoothing FWHM (mm) applied to the hemisphere volume before marching cubes (default 1.0). Maps to a command-line argument: --pre-fwhm %g. (Nipype default value: 1.0)
progress_bar_scripta pathlike object or string representing a file: Path to the progress_bar_multi.sh script. Maps to a command-line argument: --progress-bar %s.
progress_count_filea pathlike object or string representing a file: Path to the shared progress counter file (updated by all hemisphere processes). Maps to a command-line argument: --progress-count-file %s.
progress_end_countan integer: Total number of pipeline steps shown by the progress bar. Maps to a command-line argument: --progress-end-count %d.
progress_start_countan integer: Initial count offset for the progress bar (used when resuming). Maps to a command-line argument: --progress-start-count %d.
report_loga pathlike object or string representing a file: Path to the subject’s log file for timing and step information. Maps to a command-line argument: --report-log %s.
save_pial_whitean integer: Estimate and save pial and white matter surfaces (0 = no, 1 = yes; default 1). Maps to a command-line argument: --save-pial-white %d. (Nipype default value: 1)
thickness_method3 or 1 or 2: Cortical thickness estimation method: 1 = Tfs-distance (FreeSurfer-like, PBT-based); 2 = pial-to-white surface distance; 3 = pure projection-based thickness (PBT; default). Maps to a command-line argument: --thickness-method %d. (Nipype default value: 3)
vesselan integer: Apply blood-vessel intensity correction to the thickness volume (0 = no, 1 = yes; default 1). Maps to a command-line argument: --vessel %d. (Nipype default value: 1)

Outputs¶

area_lha pathlike object or string representing a file: Left-hemisphere surface area per-vertex file.
area_rha pathlike object or string representing a file: Right-hemisphere surface area per-vertex file.
central_surface_lha pathlike object or string representing a file: Left-hemisphere central surface (GIFTI .gii, CAT12 naming).
central_surface_rha pathlike object or string representing a file: Right-hemisphere central surface (GIFTI .gii, CAT12 naming).
pial_surface_lha pathlike object or string representing a file: Left-hemisphere pial surface (saved when save_pial_white=1).
pial_surface_rha pathlike object or string representing a file: Right-hemisphere pial surface (saved when save_pial_white=1).
sphere_lha pathlike object or string representing a file: Left-hemisphere inflated sphere surface (saved when estimate_spherereg=1).
sphere_rha pathlike object or string representing a file: Right-hemisphere inflated sphere surface (saved when estimate_spherereg=1).
spherereg_lha pathlike object or string representing a file: Left-hemisphere DARTEL-registered sphere (saved when estimate_spherereg=1).
spherereg_rha pathlike object or string representing a file: Right-hemisphere DARTEL-registered sphere (saved when estimate_spherereg=1).
surf_dira pathlike object or string representing a directory: Surface output directory.
thickness_lha pathlike object or string representing a file: Left-hemisphere cortical thickness per-vertex file.
thickness_rha pathlike object or string representing a file: Right-hemisphere cortical thickness per-vertex file.
white_surface_lha pathlike object or string representing a file: Left-hemisphere white matter surface (saved when save_pial_white=1).
white_surface_rha pathlike object or string representing a file: Right-hemisphere white matter surface (saved when save_pial_white=1).

Release	Devel
1.12.0	1.12.0
Download	Github

Table of Contents

Versions

Links

nipype.interfaces.t1prep package¶

Sub-module interfaces¶

Base classes¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Optional Inputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Mandatory Inputs¶

Optional Inputs¶

Outputs¶

Submodules¶