niworkflows.interfaces.images module

Image tools interfaces.

class niworkflows.interfaces.images.Conform(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Conform a series of T1w images to enable merging.

Performs two basic functions:

  1. Orient to RAS (left-right, posterior-anterior, inferior-superior)

  2. Resample to target zooms (voxel sizes) and shape (number of voxels)

Note that the output transforms are voxel-to-voxel; the RAS-to-RAS transform is the identity transform.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input image.

Optional Inputs:

  • target_shape (a tuple of the form: (an integer, an integer, an integer)) – Target shape information.

  • target_zooms (a tuple of the form: (a float, a float, a float)) – Target zoom information.

Outputs:

  • out_file (a pathlike object or string representing an existing file) – Conformed image.

  • transform (a pathlike object or string representing an existing file) – Conformation transform (voxel-to-voxel).

class niworkflows.interfaces.images.IntraModalMerge(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Calculate an average of the inputs.

If the input is 3D, returns the original image. Otherwise, splits the images and merges them after head-motion correction with FSL mcflirt.

Mandatory Inputs:

in_files (a list of items which are a pathlike object or string representing an existing file) – Input files.

Optional Inputs:

  • grand_mean_scaling (a boolean) – (Nipype default value: False)

  • hmc (a boolean) – (Nipype default value: True)

  • in_mask (a pathlike object or string representing an existing file) – Input mask for grand mean scaling.

  • to_ras (a boolean) – (Nipype default value: True)

  • zero_based_avg (a boolean) – (Nipype default value: True)

Outputs:

  • out_avg (a pathlike object or string representing an existing file) – Average image.

  • out_file (a pathlike object or string representing an existing file) – Merged image.

  • out_mats (a list of items which are a pathlike object or string representing an existing file) – Output matrices.

  • out_movpar (a list of items which are a pathlike object or string representing an existing file) – Output movement parameters.

class niworkflows.interfaces.images.RegridToZooms(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Change the resolution of an image (regrid).

Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – A file whose resolution is to change.

  • zooms (a tuple of the form: (a float, a float, a float)) – The new resolution.

Optional Inputs:

  • clip (a boolean) – Clip the data array within the original image’s range. (Nipype default value: True)

  • order (an integer) – Order of interpolator. (Nipype default value: 3)

  • smooth (a boolean or a float) – Apply gaussian smoothing before resampling. (Nipype default value: False)

Outputs:

out_file (a pathlike object or string representing an existing file)

class niworkflows.interfaces.images.RobustAverage(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Robustly estimate an average of the input.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Either a 3D reference or 4D file to average through the last axis.

Optional Inputs:

  • mc_method (‘AFNI’ or ‘FSL’ or None) – Which software to use to perform motion correction. (Nipype default value: AFNI)

  • nonnegative (a boolean) – Whether the output should be clipped below zero. (Nipype default value: True)

  • num_threads (an integer) – Number of threads.

  • t_mask (a list of items which are a boolean) – List of selected timepoints to be averaged.

  • two_pass (a boolean) – Whether two passes of correction is necessary. (Nipype default value: True)

Outputs:

  • out_drift (a list of items which are a float) – The ratio to the grand mean or global signal drift.

  • out_file (a pathlike object or string representing an existing file) – The averaged image.

  • out_hmc (a list of items which are a pathlike object or string representing an existing file) – Head-motion correction matrices.

  • out_hmc_volumes (a list of items which are a pathlike object or string representing an existing file) – Head-motion correction volumes.

  • out_volumes (a pathlike object or string representing an existing file) – The volumes selected that have been averaged.

class niworkflows.interfaces.images.SignalExtraction(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Extract mean signals from a time series within a set of ROIs.

This interface is intended to be a memory-efficient alternative to nipype.interfaces.nilearn.SignalExtraction. Not all features of nilearn.SignalExtraction are implemented at this time.

Mandatory Inputs:

  • class_labels (a list of items which are any value) – Human-readable labels for each segment in the label file, in order. The length of class_labels must be equal to the number of segments (background excluded). This list corresponds to the class labels in label_file in ascending order.

  • in_file (a pathlike object or string representing an existing file) – 4-D fMRI nii file.

  • label_files (a list of items which are a pathlike object or string representing an existing file) – A 3D label image, with 0 denoting background, or a list of 3D probability maps (one per label) or the equivalent 4D file.

Optional Inputs:

  • out_file (a pathlike object or string representing a file) – The name of the file to output to. signals.tsv by default. (Nipype default value: signals.tsv)

  • prob_thres (0.0 <= a floating point number <= 1.0) – If label_files are probability masks, threshold at specified probability. (Nipype default value: 0.5)

Outputs:

out_file (a pathlike object or string representing an existing file) – Tsv file containing the computed signals, with as many columns as there are labels and as many rows as there are timepoints in in_file, plus a header row with values from class_labels.

class niworkflows.interfaces.images.TemplateDimensions(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Finds template target dimensions for a series of anatomical images, filtering low-resolution images, if necessary.

Along each axis, the minimum voxel size (zoom) and the maximum number of voxels (shape) are found across images.

The max_scale parameter sets a bound on the degree of up-sampling performed. By default, an image with a voxel size greater than 3x the smallest voxel size (calculated separately for each dimension) will be discarded.

To select images that require no scaling (i.e. all have smallest voxel sizes), set max_scale=1.

Optional Inputs:

  • anat_list (a list of items which are a pathlike object or string representing an existing file) – Input anatomical images. Mutually exclusive with inputs: t1w_list.

  • anat_type (‘T1w’ or ‘T2w’) – Anatomical image type. (Nipype default value: T1w)

  • max_scale (a float) – Maximum scaling factor in images to accept. (Nipype default value: 3.0)

  • t1w_list (a list of items which are a pathlike object or string representing an existing file) – Mutually exclusive with inputs: anat_list.

Outputs:

  • anat_valid_list (a list of items which are any value) – Valid anatomical images.

  • out_report (a pathlike object or string representing an existing file) – Conformation report.

  • t1w_valid_list (a list of items which are any value) – Valid T1w images.

  • target_shape (a tuple of the form: (an integer, an integer, an integer)) – Target shape information.

  • target_zooms (a tuple of the form: (a float, a float, a float)) – Target zoom information.

niworkflows.interfaces.images.normalize_xform(img)[source]

Set identical, valid qform and sform matrices in an image.

Selects the best available affine (sform > qform > shape-based), and coerces it to be qform-compatible (no shears).

The resulting image represents this same affine as both qform and sform, and is marked as NIFTI_XFORM_ALIGNED_ANAT, indicating that it is valid, not aligned to template, and not necessarily preserving the original coordinates.

If header would be unchanged, returns input image.

niworkflows.interfaces.images.reorient(in_file, newpath=None)[source]

Reorient Nifti files to RAS.