nipype.algorithms.confounds module

Algorithms to compute confounds in fMRI

ACompCor

Link to code

Bases: CompCor

Anatomical compcor: for inputs and outputs, see CompCor. When the mask provided is an anatomical mask, then CompCor is equivalent to ACompCor.

Mandatory Inputs:

realigned_file (a pathlike object or string representing an existing file) – Already realigned brain image (4D).

Optional Inputs:
  • components_file (a string) – Filename to store physiological components. (Nipype default value: components_file.txt)

  • failure_mode (‘error’ or ‘NaN’) – When no components are found or convergence fails, raise an error or silently return columns of NaNs. (Nipype default value: error)

  • header_prefix (a string) – The desired header for the output tsv file (one column). If undefined, will default to “CompCor”.

  • high_pass_cutoff (a float) – Cutoff (in seconds) for “cosine” pre-filter. (Nipype default value: 128)

  • ignore_initial_volumes (an integer >= 0) – Number of volumes at start of series to ignore. (Nipype default value: 0)

  • mask_files (a list of items which are a pathlike object or string representing an existing file) – One or more mask files that determines ROI (3D). When more that one file is provided merge_method or merge_index must be provided.

  • mask_index (an integer >= 0) – Position of mask in mask_files to use - first is the default. Mutually exclusive with inputs: merge_method. Requires inputs: mask_files.

  • mask_names (a list of items which are a string) – Names for provided masks (for printing into metadata). If provided, it must be as long as the final mask list (after any merge and indexing operations).

  • merge_method (‘union’ or ‘intersect’ or ‘none’) – Merge method if multiple masks are present - union uses voxels included in at least one input mask, intersect uses only voxels present in all input masks, none performs CompCor on each mask individually. Mutually exclusive with inputs: mask_index. Requires inputs: mask_files.

  • num_components (an integer >= 1 or ‘all’) – Number of components to return from the decomposition. If num_components is all, then all components will be retained. Mutually exclusive with inputs: variance_threshold.

  • pre_filter (‘polynomial’ or ‘cosine’ or False) – Detrend time series prior to component extraction. (Nipype default value: polynomial)

  • regress_poly_degree (an integer >= 1) – The degree polynomial to use. (Nipype default value: 1)

  • repetition_time (a float) – Repetition time (TR) of series - derived from image header if unspecified.

  • save_metadata (a boolean or a pathlike object or string representing a file) – Save component metadata as text file. (Nipype default value: False)

  • save_pre_filter (a boolean or a pathlike object or string representing a file) – Save pre-filter basis as text file. (Nipype default value: False)

  • use_regress_poly (a boolean) – Use polynomial regression pre-component extraction.

  • variance_threshold (0.0 < a floating point number < 1.0) – Select the number of components to be returned automatically based on their ability to explain variance in the dataset. variance_threshold is a fractional value between 0 and 1; the number of components retained will be equal to the minimum number of components necessary to explain the provided fraction of variance in the masked time series. Mutually exclusive with inputs: num_components.

Outputs:
  • components_file (a pathlike object or string representing an existing file) – Text file containing the noise components.

  • metadata_file (a pathlike object or string representing a file) – Text file containing component metadata.

  • pre_filter_file (a pathlike object or string representing a file) – Text file containing high-pass filter basis.

CompCor

Link to code

Bases: SimpleInterface

Interface with core CompCor computation, used in aCompCor and tCompCor.

CompCor provides three pre-filter options, all of which include per-voxel mean removal:

  • 'polynomial': Legendre polynomial basis

  • 'cosine': Discrete cosine basis

  • False: mean-removal only

In the case of polynomial and cosine filters, a pre-filter file may be saved with a row for each volume/timepoint, and a column for each non-constant regressor. If no non-constant (mean-removal) columns are used, this file may be empty.

If ignore_initial_volumes is set, then the specified number of initial volumes are excluded both from pre-filtering and CompCor component extraction. Each column in the components and pre-filter files are prefixe with zeros for each excluded volume so that the number of rows continues to match the number of volumes in the input file. In addition, for each excluded volume, a column is added to the pre-filter file with a 1 in the corresponding row.

Example

>>> ccinterface = CompCor()
>>> ccinterface.inputs.realigned_file = 'functional.nii'
>>> ccinterface.inputs.mask_files = 'mask.nii'
>>> ccinterface.inputs.num_components = 1
>>> ccinterface.inputs.pre_filter = 'polynomial'
>>> ccinterface.inputs.regress_poly_degree = 2
Mandatory Inputs:

realigned_file (a pathlike object or string representing an existing file) – Already realigned brain image (4D).

Optional Inputs:
  • components_file (a string) – Filename to store physiological components. (Nipype default value: components_file.txt)

  • failure_mode (‘error’ or ‘NaN’) – When no components are found or convergence fails, raise an error or silently return columns of NaNs. (Nipype default value: error)

  • header_prefix (a string) – The desired header for the output tsv file (one column). If undefined, will default to “CompCor”.

  • high_pass_cutoff (a float) – Cutoff (in seconds) for “cosine” pre-filter. (Nipype default value: 128)

  • ignore_initial_volumes (an integer >= 0) – Number of volumes at start of series to ignore. (Nipype default value: 0)

  • mask_files (a list of items which are a pathlike object or string representing an existing file) – One or more mask files that determines ROI (3D). When more that one file is provided merge_method or merge_index must be provided.

  • mask_index (an integer >= 0) – Position of mask in mask_files to use - first is the default. Mutually exclusive with inputs: merge_method. Requires inputs: mask_files.

  • mask_names (a list of items which are a string) – Names for provided masks (for printing into metadata). If provided, it must be as long as the final mask list (after any merge and indexing operations).

  • merge_method (‘union’ or ‘intersect’ or ‘none’) – Merge method if multiple masks are present - union uses voxels included in at least one input mask, intersect uses only voxels present in all input masks, none performs CompCor on each mask individually. Mutually exclusive with inputs: mask_index. Requires inputs: mask_files.

  • num_components (an integer >= 1 or ‘all’) – Number of components to return from the decomposition. If num_components is all, then all components will be retained. Mutually exclusive with inputs: variance_threshold.

  • pre_filter (‘polynomial’ or ‘cosine’ or False) – Detrend time series prior to component extraction. (Nipype default value: polynomial)

  • regress_poly_degree (an integer >= 1) – The degree polynomial to use. (Nipype default value: 1)

  • repetition_time (a float) – Repetition time (TR) of series - derived from image header if unspecified.

  • save_metadata (a boolean or a pathlike object or string representing a file) – Save component metadata as text file. (Nipype default value: False)

  • save_pre_filter (a boolean or a pathlike object or string representing a file) – Save pre-filter basis as text file. (Nipype default value: False)

  • use_regress_poly (a boolean) – Use polynomial regression pre-component extraction.

  • variance_threshold (0.0 < a floating point number < 1.0) – Select the number of components to be returned automatically based on their ability to explain variance in the dataset. variance_threshold is a fractional value between 0 and 1; the number of components retained will be equal to the minimum number of components necessary to explain the provided fraction of variance in the masked time series. Mutually exclusive with inputs: num_components.

Outputs:
  • components_file (a pathlike object or string representing an existing file) – Text file containing the noise components.

  • metadata_file (a pathlike object or string representing a file) – Text file containing component metadata.

  • pre_filter_file (a pathlike object or string representing a file) – Text file containing high-pass filter basis.

ComputeDVARS

Link to code

Bases: BaseInterface

Computes the DVARS.

Mandatory Inputs:
  • in_file (a pathlike object or string representing an existing file) – Functional data, after HMC.

  • in_mask (a pathlike object or string representing an existing file) – A brain mask.

Optional Inputs:
  • figdpi (an integer) – Output dpi for the plot. (Nipype default value: 100)

  • figformat (‘png’ or ‘pdf’ or ‘svg’) – Output format for figures. (Nipype default value: png)

  • figsize (a tuple of the form: (a float, a float)) – Output figure size. (Nipype default value: (11.7, 2.3))

  • intensity_normalization (a float) – Divide value in each voxel at each timepoint by the median calculated across all voxelsand timepoints within the mask (if specified)and then multiply by the value specified bythis parameter. By using the default (1000)output DVARS will be expressed in x10 % BOLD units compatible with Power et al.2012. Set this to 0 to disable intensitynormalization altogether. (Nipype default value: 1000.0)

  • remove_zerovariance (a boolean) – Remove voxels with zero variance. (Nipype default value: True)

  • save_all (a boolean) – Output all DVARS. (Nipype default value: False)

  • save_nstd (a boolean) – Save non-standardized DVARS. (Nipype default value: False)

  • save_plot (a boolean) – Write DVARS plot. (Nipype default value: False)

  • save_std (a boolean) – Save standardized DVARS. (Nipype default value: True)

  • save_vxstd (a boolean) – Save voxel-wise standardized DVARS. (Nipype default value: False)

  • series_tr (a float) – Repetition time in sec.

  • variance_tol (a float) – Maximum variance to consider “close to” zero for the purposes of removal. (Nipype default value: 1e-07)

Outputs:
  • avg_nstd (a float)

  • avg_std (a float)

  • avg_vxstd (a float)

  • fig_nstd (a pathlike object or string representing an existing file) – Output DVARS plot.

  • fig_std (a pathlike object or string representing an existing file) – Output DVARS plot.

  • fig_vxstd (a pathlike object or string representing an existing file) – Output DVARS plot.

  • out_all (a pathlike object or string representing an existing file) – Output text file.

  • out_nstd (a pathlike object or string representing an existing file) – Output text file.

  • out_std (a pathlike object or string representing an existing file) – Output text file.

  • out_vxstd (a pathlike object or string representing an existing file) – Output text file.

FramewiseDisplacement

Link to code

Bases: BaseInterface

Calculate the FD as in [Power2012]. This implementation reproduces the calculation in fsl_motion_outliers

[Power2012] (1,2)

Power et al., Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion, NeuroImage 59(3), 2012. doi:10.1016/j.neuroimage.2011.10.018.

Mandatory Inputs:
  • in_file (a pathlike object or string representing an existing file) – Motion parameters.

  • parameter_source (‘FSL’ or ‘AFNI’ or ‘SPM’ or ‘FSFAST’ or ‘NIPY’) – Source of movement parameters.

Optional Inputs:
  • figdpi (an integer) – Output dpi for the FD plot. (Nipype default value: 100)

  • figsize (a tuple of the form: (a float, a float)) – Output figure size. (Nipype default value: (11.7, 2.3))

  • normalize (a boolean) – Calculate FD in mm/s. (Nipype default value: False)

  • out_figure (a pathlike object or string representing a file) – Output figure name. (Nipype default value: fd_power_2012.pdf)

  • out_file (a pathlike object or string representing a file) – Output file name. (Nipype default value: fd_power_2012.txt)

  • radius (a float) – Radius in mm to calculate angular FDs, 50mm is the default since it is used in Power et al. 2012. (Nipype default value: 50)

  • save_plot (a boolean) – Write FD plot. (Nipype default value: False)

  • series_tr (a float) – Repetition time in sec.

Outputs:
  • fd_average (a float) – Average FD.

  • out_figure (a pathlike object or string representing a file) – Output image file.

  • out_file (a pathlike object or string representing a file) – Calculated FD per timestep.

NonSteadyStateDetector

Link to code

Bases: BaseInterface

Returns the number of non-steady state volumes detected at the beginning of the scan.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – 4D NIFTI EPI file.

Outputs:

n_volumes_to_discard (an integer) – Number of non-steady state volumesdetected in the beginning of the scan.

TCompCor

Link to code

Bases: CompCor

Interface for tCompCor. Computes a ROI mask based on variance of voxels.

Example

>>> ccinterface = TCompCor()
>>> ccinterface.inputs.realigned_file = 'functional.nii'
>>> ccinterface.inputs.mask_files = 'mask.nii'
>>> ccinterface.inputs.num_components = 1
>>> ccinterface.inputs.pre_filter = 'polynomial'
>>> ccinterface.inputs.regress_poly_degree = 2
>>> ccinterface.inputs.percentile_threshold = .03
Mandatory Inputs:

realigned_file (a pathlike object or string representing an existing file) – Already realigned brain image (4D).

Optional Inputs:
  • components_file (a string) – Filename to store physiological components. (Nipype default value: components_file.txt)

  • failure_mode (‘error’ or ‘NaN’) – When no components are found or convergence fails, raise an error or silently return columns of NaNs. (Nipype default value: error)

  • header_prefix (a string) – The desired header for the output tsv file (one column). If undefined, will default to “CompCor”.

  • high_pass_cutoff (a float) – Cutoff (in seconds) for “cosine” pre-filter. (Nipype default value: 128)

  • ignore_initial_volumes (an integer >= 0) – Number of volumes at start of series to ignore. (Nipype default value: 0)

  • mask_files (a list of items which are a pathlike object or string representing an existing file) – One or more mask files that determines ROI (3D). When more that one file is provided merge_method or merge_index must be provided.

  • mask_index (an integer >= 0) – Position of mask in mask_files to use - first is the default. Mutually exclusive with inputs: merge_method. Requires inputs: mask_files.

  • mask_names (a list of items which are a string) – Names for provided masks (for printing into metadata). If provided, it must be as long as the final mask list (after any merge and indexing operations).

  • merge_method (‘union’ or ‘intersect’ or ‘none’) – Merge method if multiple masks are present - union uses voxels included in at least one input mask, intersect uses only voxels present in all input masks, none performs CompCor on each mask individually. Mutually exclusive with inputs: mask_index. Requires inputs: mask_files.

  • num_components (an integer >= 1 or ‘all’) – Number of components to return from the decomposition. If num_components is all, then all components will be retained. Mutually exclusive with inputs: variance_threshold.

  • percentile_threshold (0.0 < a floating point number < 1.0) – The percentile used to select highest-variance voxels, represented by a number between 0 and 1, exclusive. By default, this value is set to .02. That is, the 2% of voxels with the highest variance are used. (Nipype default value: 0.02)

  • pre_filter (‘polynomial’ or ‘cosine’ or False) – Detrend time series prior to component extraction. (Nipype default value: polynomial)

  • regress_poly_degree (an integer >= 1) – The degree polynomial to use. (Nipype default value: 1)

  • repetition_time (a float) – Repetition time (TR) of series - derived from image header if unspecified.

  • save_metadata (a boolean or a pathlike object or string representing a file) – Save component metadata as text file. (Nipype default value: False)

  • save_pre_filter (a boolean or a pathlike object or string representing a file) – Save pre-filter basis as text file. (Nipype default value: False)

  • use_regress_poly (a boolean) – Use polynomial regression pre-component extraction.

  • variance_threshold (0.0 < a floating point number < 1.0) – Select the number of components to be returned automatically based on their ability to explain variance in the dataset. variance_threshold is a fractional value between 0 and 1; the number of components retained will be equal to the minimum number of components necessary to explain the provided fraction of variance in the masked time series. Mutually exclusive with inputs: num_components.

Outputs:
  • components_file (a pathlike object or string representing an existing file) – Text file containing the noise components.

  • high_variance_masks (a list of items which are a pathlike object or string representing an existing file) – Voxels exceeding the variance threshold.

  • metadata_file (a pathlike object or string representing a file) – Text file containing component metadata.

  • pre_filter_file (a pathlike object or string representing a file) – Text file containing high-pass filter basis.

TSNR

Link to code

Bases: BaseInterface

Computes the time-course SNR for a time series

Typically you want to run this on a realigned time-series.

Example

>>> tsnr = TSNR()
>>> tsnr.inputs.in_file = 'functional.nii'
>>> res = tsnr.run() 
Mandatory Inputs:

in_file (a list of items which are a pathlike object or string representing an existing file) – Realigned 4D file or a list of 3D files.

Optional Inputs:
  • detrended_file (a pathlike object or string representing a file) – Input file after detrending. (Nipype default value: detrend.nii.gz)

  • mean_file (a pathlike object or string representing a file) – Output mean file. (Nipype default value: mean.nii.gz)

  • regress_poly (an integer >= 1) – Remove polynomials.

  • stddev_file (a pathlike object or string representing a file) – Output tSNR file. (Nipype default value: stdev.nii.gz)

  • tsnr_file (a pathlike object or string representing a file) – Output tSNR file. (Nipype default value: tsnr.nii.gz)

Outputs:
  • detrended_file (a pathlike object or string representing a file) – Detrended input file.

  • mean_file (a pathlike object or string representing an existing file) – Mean image file.

  • stddev_file (a pathlike object or string representing an existing file) – Std dev image file.

  • tsnr_file (a pathlike object or string representing an existing file) – Tsnr image file.

nipype.algorithms.confounds.combine_mask_files(mask_files, mask_method=None, mask_index=None)

Combines input mask files into a single nibabel image

A helper function for CompCor

Parameters:
  • mask_files (a list) – one or more binary mask files

  • mask_method (enum (‘union’, ‘intersect’, ‘none’)) – determines how to combine masks

  • mask_index (an integer) – determines which file to return (mutually exclusive with mask_method)

Returns:

masks

Return type:

a list of nibabel images

nipype.algorithms.confounds.compute_dvars(in_file, in_mask, remove_zerovariance=False, intensity_normalization=1000, variance_tol=0.0)

Compute the DVARS [Power2012].

Particularly, the standardized DVARS [Nichols2013] are computed.

Note

Implementation details

Uses the implementation of the Yule-Walker equations from nitime for the AR filtering of the fMRI signal.

Parameters:
  • func (numpy.ndarray) – functional data, after head-motion-correction.

  • mask (numpy.ndarray) – a 3D mask of the brain

  • output_all (bool) – write out all dvars

  • out_file (str) – a path to which the standardized dvars should be saved.

Returns:

the standardized DVARS

nipype.algorithms.confounds.compute_noise_components(imgseries, mask_images, components_criterion=0.5, filter_type=False, degree=0, period_cut=128, repetition_time=None, failure_mode='error', mask_names=None)

Compute the noise components from the image series for each mask.

Parameters:
  • imgseries (nibabel image) – Time series data to be decomposed.

  • mask_images (list) – List of nibabel images. Time series data from img_series is subset according to the spatial extent of each mask, and the subset data is then decomposed using principal component analysis. Masks should be coextensive with either anatomical or spatial noise ROIs.

  • components_criterion (float) – Number of noise components to return. If this is a decimal value between 0 and 1, then create_noise_components will instead return the smallest number of components necessary to explain the indicated fraction of variance. If components_criterion is all, then all components will be returned.

  • filter_type (str) –

    Type of filter to apply to time series before computing noise components.

    • ‘polynomial’ - Legendre polynomial basis

    • ‘cosine’ - Discrete cosine (DCT) basis

    • False - None (mean-removal only)

  • failure_mode (str) – Action to be taken in the event that any decomposition fails to identify any components. error indicates that the routine should raise an exception and exit, while any other value indicates that the routine should return a matrix of NaN values equal in size to the requested decomposition matrix.

  • mask_names (list or None) – List of names for each image in mask_images. This should be equal in length to mask_images, with the ith element of mask_names naming the ith element of mask_images.

  • degree (int) – Order of polynomial used to remove trends from the timeseries

  • period_cut (float) – Minimum period (in sec) for DCT high-pass filter

  • repetition_time (float) – Time (in sec) between volume acquisitions. This must be defined if the filter_type is cosine.

Returns:

  • components (numpy array) – Numpy array containing the requested set of noise components

  • basis (numpy array) – Numpy array containing the (non-constant) filter regressors

  • metadata (OrderedDict{str: numpy array}) – Dictionary of eigenvalues, fractional explained variances, and cumulative explained variances.

nipype.algorithms.confounds.cosine_filter(data, timestep, period_cut, remove_mean=True, axis=- 1, failure_mode='error')
nipype.algorithms.confounds.fallback_svd(a, full_matrices=True, compute_uv=True)
nipype.algorithms.confounds.is_outlier(points, thresh=3.5)

Returns a boolean array with True if points are outliers and False otherwise.

Parameters:
  • points (nparray) – an numobservations by numdimensions numpy array of observations

  • thresh (float) – the modified z-score to use as a threshold. Observations with a modified z-score (based on the median absolute deviation) greater than this value will be classified as outliers.

Returns:

A bolean mask, of size numobservations-length array.

Note

References

Boris Iglewicz and David Hoaglin (1993), “Volume 16: How to Detect and Handle Outliers”, The ASQC Basic References in Quality Control: Statistical Techniques, Edward F. Mykytka, Ph.D., Editor.

nipype.algorithms.confounds.plot_confound(tseries, figsize, name, units=None, series_tr=None, normalize=False)

A helper function to plot fMRI confounds.

nipype.algorithms.confounds.regress_poly(degree, data, remove_mean=True, axis=- 1, failure_mode='error')

Returns data with degree polynomial regressed out.

Parameters:
  • remove_mean (bool) – whether or not demean data (i.e. degree 0),

  • axis (int) – numpy array axes along which regression is performed