nipype.interfaces.t1prep.surface module¶
Nipype interfaces for T1Prep surface processing.
T1PrepSurfaceEstimationCortical surface reconstruction for one hemisphere. Wraps
python -m t1prep.surface_estimation.
- class nipype.interfaces.t1prep.surface.T1PrepSurfaceEstimation(command=None, terminal_output=None, write_cmdline=False, **inputs)¶
Bases:
T1PrepCommandWrapped 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 inscripts/T1Prepbut runs entirely in-process via thecat_surfPython bindings. Run it separately for each hemisphere (side='left'andside='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).