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_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.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_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.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_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.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_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.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_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).