nipype.interfaces.t1prep.cat_surf module

Nipype interfaces for the cat_surf volume denoising and registration API.

These wrap the small subset of the CAT-Surface (cat-surf) Python API needed to stand in for FreeSurfer / FSL (bbregister) / ANTs affine registration in an fMRIPrep-style workflow:

Volume operations

Registration

Each interface is file-based: it reads its inputs from disk, calls the cat_surf wrapper, and writes its outputs (denoised volume / affine matrix) to disk, so nodes pass file paths rather than pickled numpy arrays.

The full set of per-function cat_surf interfaces (surface I/O, geometry, smoothing, resampling, DARTEL / Spherical Demons registration) is kept as an archived reference in the CAT-Surface repository under cat_surface_cython/examples/nipype/cat_surf_interfaces_full.py.

References

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

class nipype.interfaces.t1prep.cat_surf.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.cat_surf.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.cat_surf.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.cat_surf.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.cat_surf.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).