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_file (a pathlike object or string representing an existing file) – Moving/functional NIfTI image to register (e.g. BOLD reference).

Optional Inputs:

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

Outputs:

cost (a float) – Final BBR cost (lower is better).
out_matrix_file (a 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_file (a pathlike object or string representing an existing file) – NIfTI volume whose contrast to detect.

Optional Inputs:

lh_surface (a pathlike object or string representing an existing file) – Optional left white-matter surface for sampling.
rh_surface (a pathlike object or string representing an existing file) – Optional right white-matter surface for sampling.

Outputs:

contrast (an 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_file (a pathlike object or string representing an existing file) – Input NIfTI volume to denoise.

Optional Inputs:

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

Outputs:

out_file (a 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_file (a pathlike object or string representing an existing file) – Fixed (reference) NIfTI image.
moving_file (a pathlike object or string representing an existing file) – Moving (source) NIfTI image.

Optional Inputs:

max_iter (an integer) – Maximum optimiser iterations per level. (Nipype default value: 30)
n_bins (an integer) – Joint-histogram bins for NMI (default 64). (Nipype default value: 64)
n_levels (an integer) – Multi-resolution pyramid levels (default 4). (Nipype default value: 4)
out_matrix_file (a pathlike object or string representing a file) – Output affine transform path (moving RAS → fixed RAS).
verbose (a boolean) – Print diagnostic output. (Nipype default value: False)

Outputs:

nmi (a float) – Final NMI value (higher is better).
out_matrix_file (a 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_file (a pathlike object or string representing an existing file) – Fixed (reference) NIfTI image.
moving_file (a pathlike object or string representing an existing file) – Moving (source) NIfTI image.

Optional Inputs:

max_iter (an integer) – Maximum optimiser iterations per level. (Nipype default value: 20)
n_levels (an integer) – Multi-resolution pyramid levels (default 4). (Nipype default value: 4)
out_matrix_file (a pathlike object or string representing a file) – Output affine transform path (moving RAS → fixed RAS).
sat_k (a float) – Tukey biweight saturation constant (default 4.685). (Nipype default value: 4.685)
verbose (a boolean) – Print diagnostic output. (Nipype default value: False)

Outputs:

out_matrix_file (a pathlike object or string representing a file) – 4×4 affine transform (moving RAS → fixed RAS).
residual (a 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_files (a 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:

amap (a boolean) – Use AMAP segmentation for a refined tissue classification after the initial DeepMriPrep estimate. Maps to a command-line argument: --amap.
args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.
atlas (a 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_surf (a string) – Comma-separated surface atlas list, e.g. “‘aparc_DK40.freesurfer’,’aparc_a2009s.freesurfer’”. Maps to a command-line argument: --atlas-surf %s.
bids (a boolean) – Use BIDS derivatives naming conventions for output files. Maps to a command-line argument: --bids.
csf (a boolean) – Additionally save CSF segmentation (GM and WM are always saved when –p or –rp are set). Maps to a command-line argument: --csf.
debug (a boolean) – Enable verbose output and retain all intermediate files. Maps to a command-line argument: --debug.
downsample (a float) – Mesh downsampling factor for the initial surface extraction step. Maps to a command-line argument: --downsample %g.
environ (a 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: {})
fmriprep (a 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.
gz (a boolean) – Write compressed (.nii.gz) NIfTI outputs. Maps to a command-line argument: --gz.
initial_surf (a pathlike object or string representing a file) – Pre-existing central surface file for longitudinal processing. Maps to a command-line argument: --initial-surf %s.
lesions (a boolean) – Additionally save white-matter hyperintensity (WMH) lesion segmentation in native and/or affine space. Maps to a command-line argument: --lesions.
long_data (a 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_filter (an integer) – Number of median filter passes applied before surface extraction. Maps to a command-line argument: --median-filter %d.
no_atlas (a boolean) – Disable atlas labelling and ROI volume export. Maps to a command-line argument: --no-atlas.
no_correct_folding (a boolean) – Disable cortical thickness correction for folding effects. Maps to a command-line argument: --no-correct-folding.
no_mwp (a boolean) – Disable saving of modulated warped (MNI-space) segmentations (they are saved by default). Maps to a command-line argument: --no-mwp.
no_overwrite (a 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_retry (a 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_seg (a boolean) – Skip tissue segmentation (surface processing only). Maps to a command-line argument: --no-seg.
no_sphere_reg (a boolean) – Skip spherical surface registration and atlas resampling. Maps to a command-line argument: --no-sphere-reg.
no_surf (a boolean) – Skip cortical surface and thickness estimation. Maps to a command-line argument: --no-surf.
out_dir (a 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.
p (a boolean) – Additionally save native-space segmentation maps. Maps to a command-line argument: --p.
pial_white (a boolean) – Estimate and save pial and white matter surfaces. Maps to a command-line argument: --pial-white.
pre_fwhm (a float) – Pre-smoothing FWHM (mm) applied before marching cubes surface extraction. Maps to a command-line argument: --pre-fwhm %g.
quiet (a boolean) – Suppress progress messages (overrides the default verbose mode). Maps to a command-line argument: --quiet.
rp (a boolean) – Additionally save affine-registered segmentations. Maps to a command-line argument: --rp.
seed (an integer) – Random seed for deterministic processing. Maps to a command-line argument: --seed %d.
skip_skullstrip (a 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_only (a 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_method (1 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.
vessel (a float) – Blood-vessel correction strength (0 = disabled; default 1.0). Maps to a command-line argument: --vessel %g.
wp (a boolean) – Additionally save non-modulated warped (MNI-space) segmentations. Maps to a command-line argument: --wp.

Outputs:

label_dir (a pathlike object or string representing a directory) – Label sub-directory (atlas ROI JSON).
mri_dir (a pathlike object or string representing a directory) – MRI sub-directory (segmentations, brain mask, etc.).
out_dir (a pathlike object or string representing a directory) – Top-level output directory.
report_dir (a pathlike object or string representing a directory) – Report sub-directory (logs, QC JSON).
surf_dir (a 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:

args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.
environ (a 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_files (a 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_dir (a 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:

args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.
device (a string) – Compute device (currently reserved; default ‘cpu’). Maps to a command-line argument: --device %s.
environ (a 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_zooms (a boolean) – Force the reference (template) zooms on all outputs. Maps to a command-line argument: --force-template-zooms.
grad_quantile (a 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_consistent (a boolean) – Re-center rigid transforms around their SE(3) barycenter. Maps to a command-line argument: --inverse-consistent.
iterations (an integer) – Number of multi-scale alignment passes (default 3). Maps to a command-line argument: --iterations %d.
max_fwhm_mm (a 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_scale (a boolean) – Disable SPM-like per-volume intensity scaling. Maps to a command-line argument: --no-intensity-scale.
out_subfolders (a 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_weight (a float) – Weight of the overlap penalty term (default 0.0). Maps to a command-line argument: --overlap-penalty-weight %g.
register_to_first (a 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_resampled (a boolean) – Write resampled copies of the inputs in reference space. Maps to a command-line argument: --save-resampled.
save_template (a boolean) – Save the reference volume used as the alignment target. Maps to a command-line argument: --save-template.
set_zooms_from_sform (a boolean) – Copy pixdim/zooms from the sform when updating headers. Maps to a command-line argument: --set-zooms-from-sform.
update_headers (a boolean) – Only update the NIfTI headers with the estimated affines; do not write resampled volumes. Maps to a command-line argument: --update-headers.
use_skullstrip (a boolean) – Estimate transforms on skull-stripped copies of the inputs. Maps to a command-line argument: --use-skullstrip.
verbose (a boolean) – Print optimizer diagnostics. Maps to a command-line argument: --verbose.

Outputs:

out_dir (a 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_file (a 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_dir (a 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_dir (a 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_dir (a pathlike object or string representing a directory) – Output directory for report log files. Maps to a command-line argument: --report-dir %s.

Optional Inputs:

amap (a boolean) – Refine the initial DeepMriPrep segmentation using AMAP (Adaptive Maximum A Posteriori) tissue classification. Maps to a command-line argument: --amap.
args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.
atlas (a 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.
bids (a boolean) – Use BIDS derivatives naming conventions for output files. Maps to a command-line argument: --bids.
count (an 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.
csf (a boolean) – Save CSF segmentation probability map in addition to GM and WM. Maps to a command-line argument: --csf.
debug (a boolean) – Enable verbose output and retain all temporary files. Maps to a command-line argument: --debug.
environ (a 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: {})
gz (a boolean) – Save compressed NIfTI outputs (.nii.gz). Maps to a command-line argument: --gz.
lesions (a boolean) – Save white-matter hyperintensity (WMH) lesion segmentation in native and/or affine space. Maps to a command-line argument: --lesions.
mwp (a boolean) – Save modulated warped (MNI-space) GM and WM segmentation maps. Maps to a command-line argument: --mwp.
p (a boolean) – Save native-space probability segmentation maps. Maps to a command-line argument: --p.
rp (a boolean) – Save affine-registered segmentation maps. Maps to a command-line argument: --rp.
save_fmriprep (a 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.
seed (an integer) – Random seed for reproducibility. Maps to a command-line argument: --seed %d.
skip_skullstrip (a boolean) – Skip skull-stripping (input is already skull-stripped). Maps to a command-line argument: --skip-skullstrip. Mutually exclusive with inputs: skullstrip_only.
skullstrip_only (a boolean) – Run skull-stripping only, save outputs, then exit. Maps to a command-line argument: --skullstrip-only. Mutually exclusive with inputs: skip_skullstrip.
surf (a boolean) – Save partitioned hemisphere segmentation maps (p0 left/right) required for the subsequent surface estimation stage. Maps to a command-line argument: --surf.
verbose (a boolean) – Print progress output. Maps to a command-line argument: --verbose.
vessel (a 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.
wp (a boolean) – Save non-modulated warped (MNI-space) segmentation maps. Maps to a command-line argument: --wp.

Outputs:

label_dir (a pathlike object or string representing a directory) – Label output directory with atlas ROI JSON files.
mri_dir (a pathlike object or string representing a directory) – MRI output directory with segmentation volumes.
report_dir (a 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_dir (a 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.
bname (a 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_dir (a 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_tsv (a 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_dir (a pathlike object or string representing a directory) – Output directory for surface files. Maps to a command-line argument: --surf-dir %s.
surf_templates_dir (a 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:

args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.
atlas_surf (a 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_naming (an 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_folding (an 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)
debug (an 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)
downsample (a 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)
environ (a 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_spherereg (an 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)
fmriprep (an 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_surface (a 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_filter (an 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)
multi (an 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_ext (a 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_fwhm (a 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_script (a 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_file (a 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_count (an integer) – Total number of pipeline steps shown by the progress bar. Maps to a command-line argument: --progress-end-count %d.
progress_start_count (an integer) – Initial count offset for the progress bar (used when resuming). Maps to a command-line argument: --progress-start-count %d.
report_log (a 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_white (an 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_method (3 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)
vessel (an 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_lh (a pathlike object or string representing a file) – Left-hemisphere surface area per-vertex file.
area_rh (a pathlike object or string representing a file) – Right-hemisphere surface area per-vertex file.
central_surface_lh (a pathlike object or string representing a file) – Left-hemisphere central surface (GIFTI .gii, CAT12 naming).
central_surface_rh (a pathlike object or string representing a file) – Right-hemisphere central surface (GIFTI .gii, CAT12 naming).
pial_surface_lh (a pathlike object or string representing a file) – Left-hemisphere pial surface (saved when save_pial_white=1).
pial_surface_rh (a pathlike object or string representing a file) – Right-hemisphere pial surface (saved when save_pial_white=1).
sphere_lh (a pathlike object or string representing a file) – Left-hemisphere inflated sphere surface (saved when estimate_spherereg=1).
sphere_rh (a pathlike object or string representing a file) – Right-hemisphere inflated sphere surface (saved when estimate_spherereg=1).
spherereg_lh (a pathlike object or string representing a file) – Left-hemisphere DARTEL-registered sphere (saved when estimate_spherereg=1).
spherereg_rh (a pathlike object or string representing a file) – Right-hemisphere DARTEL-registered sphere (saved when estimate_spherereg=1).
surf_dir (a pathlike object or string representing a directory) – Surface output directory.
thickness_lh (a pathlike object or string representing a file) – Left-hemisphere cortical thickness per-vertex file.
thickness_rh (a pathlike object or string representing a file) – Right-hemisphere cortical thickness per-vertex file.
white_surface_lh (a pathlike object or string representing a file) – Left-hemisphere white matter surface (saved when save_pial_white=1).
white_surface_rh (a pathlike object or string representing a file) – Right-hemisphere white matter surface (saved when save_pial_white=1).

Release	Devel
0.1.dev420+gb5271c217	0.1.dev420
Download	Github

Table of Contents

Versions

Links

nipype.interfaces.t1prep package¶

Sub-module interfaces¶

Base classes¶

Submodules¶