aslprep.niworkflows.interfaces.images module

Image tools interfaces.

class Conform(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Conform a series of T1w images to enable merging.

Performs two basic functions: #. Orient to RAS (left-right, posterior-anterior, inferior-superior) #. 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 DemeanImage(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• in_file (a pathlike object or string representing an existing file) – Image to be demeaned.

• in_mask (a pathlike object or string representing an existing file) – Mask where median will be calculated.

Optional Inputs:

only_mask (a boolean) – Demean only within mask. (Nipype default value: False)

Outputs:

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

class FilledImageLike(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Image to be demeaned.

Optional Inputs:

• dtype (‘float32’ or ‘uint8’) – Force output data type. (Nipype default value: float32)

• fill_value (a float) – Value to fill. (Nipype default value: 1.0)

Outputs:

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

class IntraModalMerge(from_file=None, resource_monitor=None, **inputs)

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 MatchHeader(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• in_file (a pathlike object or string representing an existing file) – NIfTI file which header will be checked.

• reference (a pathlike object or string representing an existing file) – NIfTI file with reference header.

Outputs:

out_file (a pathlike object or string representing an existing file) – NIfTI file with fixed header.

class RegridToZooms(from_file=None, resource_monitor=None, **inputs)

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)

Outputs:

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

class SignalExtraction(from_file=None, resource_monitor=None, **inputs)

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 TemplateDimensions(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Finds template target dimensions for a series of T1w 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.

Mandatory Inputs:

t1w_list (a list of items which are a pathlike object or string representing an existing file) – Input T1w images.

Optional Inputs:

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

Outputs:

• 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.

class ValidateImage(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Check the correctness of x-form headers (matrix and code).

This interface implements the following logic:

valid quaternions	qform_code > 0	sform_code > 0	qform == sform	actions
True	True	True	True	None
True	True	False		sform, scode <- qform, qcode
		True	False	qform, qcode <- sform, scode
	False	True		qform, qcode <- sform, scode
	False	False		sform, qform <- best affine; scode, qcode <- 1
False		False		sform, qform <- best affine; scode, qcode <- 1

Mandatory Inputs:

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

Outputs:

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

• out_report (a pathlike object or string representing an existing file) – HTML segment containing warning.

demean(in_file, in_mask, only_mask=False, newpath=None)

Demean in_file within the mask defined by in_mask.

nii_ones_like(in_file, value, dtype, newpath=None)

Create a NIfTI file filled with value, matching properties of in_file.

normalize_xform(img)

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.

reorient(in_file, newpath=None)

Reorient Nifti files to RAS.