algorithms.confounds

ACompCor

Link to code

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

Inputs:

[Mandatory]
realigned_file: (a pathlike object or string representing an existing
          file)
        already realigned brain image (4D)

[Optional]
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
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: mask_index
        requires: mask_files
mask_index: (a long integer >= 0)
        Position of mask in `mask_files` to use - first is the default.
        mutually_exclusive: merge_method
        requires: mask_files
mask_names: (a list of items which are a unicode 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).
components_file: (a unicode string, nipype default value:
          components_file.txt)
        Filename to store physiological components
num_components: (a long 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: variance_threshold
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: num_components
pre_filter: ('polynomial' or 'cosine' or False, nipype default value:
          polynomial)
        Detrend time series prior to component extraction
use_regress_poly: (a boolean)
        use polynomial regression pre-component extraction
regress_poly_degree: (a long integer >= 1, nipype default value: 1)
        the degree polynomial to use
header_prefix: (a unicode string)
        the desired header for the output tsv file (one column). If
        undefined, will default to "CompCor"
high_pass_cutoff: (a float, nipype default value: 128)
        Cutoff (in seconds) for "cosine" pre-filter
repetition_time: (a float)
        Repetition time (TR) of series - derived from image header if
        unspecified
save_pre_filter: (a boolean or a pathlike object or string
          representing a file, nipype default value: False)
        Save pre-filter basis as text file
save_metadata: (a boolean or a pathlike object or string representing
          a file, nipype default value: False)
        Save component metadata as text file
ignore_initial_volumes: (a long integer >= 0, nipype default value:
          0)
        Number of volumes at start of series to ignore
failure_mode: ('error' or 'NaN', nipype default value: error)
        When no components are found or convergence fails, raise an error or
        silently return columns of NaNs.

Outputs:

components_file: (a pathlike object or string representing an
          existing file)
        text file containing the noise components
pre_filter_file: (a pathlike object or string representing a file)
        text file containing high-pass filter basis
metadata_file: (a pathlike object or string representing a file)
        text file containing component metadata

References:

None

CompCor

Link to code

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

Inputs:

[Mandatory]
realigned_file: (a pathlike object or string representing an existing
          file)
        already realigned brain image (4D)

[Optional]
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
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: mask_index
        requires: mask_files
mask_index: (a long integer >= 0)
        Position of mask in `mask_files` to use - first is the default.
        mutually_exclusive: merge_method
        requires: mask_files
mask_names: (a list of items which are a unicode 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).
components_file: (a unicode string, nipype default value:
          components_file.txt)
        Filename to store physiological components
num_components: (a long 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: variance_threshold
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: num_components
pre_filter: ('polynomial' or 'cosine' or False, nipype default value:
          polynomial)
        Detrend time series prior to component extraction
use_regress_poly: (a boolean)
        use polynomial regression pre-component extraction
regress_poly_degree: (a long integer >= 1, nipype default value: 1)
        the degree polynomial to use
header_prefix: (a unicode string)
        the desired header for the output tsv file (one column). If
        undefined, will default to "CompCor"
high_pass_cutoff: (a float, nipype default value: 128)
        Cutoff (in seconds) for "cosine" pre-filter
repetition_time: (a float)
        Repetition time (TR) of series - derived from image header if
        unspecified
save_pre_filter: (a boolean or a pathlike object or string
          representing a file, nipype default value: False)
        Save pre-filter basis as text file
save_metadata: (a boolean or a pathlike object or string representing
          a file, nipype default value: False)
        Save component metadata as text file
ignore_initial_volumes: (a long integer >= 0, nipype default value:
          0)
        Number of volumes at start of series to ignore
failure_mode: ('error' or 'NaN', nipype default value: error)
        When no components are found or convergence fails, raise an error or
        silently return columns of NaNs.

Outputs:

components_file: (a pathlike object or string representing an
          existing file)
        text file containing the noise components
pre_filter_file: (a pathlike object or string representing a file)
        text file containing high-pass filter basis
metadata_file: (a pathlike object or string representing a file)
        text file containing component metadata

References:

None

ComputeDVARS

Link to code

Computes the DVARS.

Inputs:

[Mandatory]
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]
remove_zerovariance: (a boolean, nipype default value: True)
        remove voxels with zero variance
save_std: (a boolean, nipype default value: True)
        save standardized DVARS
save_nstd: (a boolean, nipype default value: False)
        save non-standardized DVARS
save_vxstd: (a boolean, nipype default value: False)
        save voxel-wise standardized DVARS
save_all: (a boolean, nipype default value: False)
        output all DVARS
series_tr: (a float)
        repetition time in sec.
save_plot: (a boolean, nipype default value: False)
        write DVARS plot
figdpi: (an integer (int or long), nipype default value: 100)
        output dpi for the plot
figsize: (a tuple of the form: (a float, a float), nipype default
          value: (11.7, 2.3))
        output figure size
figformat: ('png' or 'pdf' or 'svg', nipype default value: png)
        output format for figures
intensity_normalization: (a float, nipype default value: 1000.0)
        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.

Outputs:

out_std: (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_vxstd: (a pathlike object or string representing an existing
          file)
        output text file
out_all: (a pathlike object or string representing an existing file)
        output text file
avg_std: (a float)
avg_nstd: (a float)
avg_vxstd: (a float)
fig_std: (a pathlike object or string representing an existing file)
        output DVARS plot
fig_nstd: (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

References:

None None

FramewiseDisplacement

Link to code

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.

Inputs:

[Mandatory]
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]
radius: (a float, nipype default value: 50)
        radius in mm to calculate angular FDs, 50mm is the default since it
        is used in Power et al. 2012
out_file: (a pathlike object or string representing a file, nipype
          default value: fd_power_2012.txt)
        output file name
out_figure: (a pathlike object or string representing a file, nipype
          default value: fd_power_2012.pdf)
        output figure name
series_tr: (a float)
        repetition time in sec.
save_plot: (a boolean, nipype default value: False)
        write FD plot
normalize: (a boolean, nipype default value: False)
        calculate FD in mm/s
figdpi: (an integer (int or long), nipype default value: 100)
        output dpi for the FD plot
figsize: (a tuple of the form: (a float, a float), nipype default
          value: (11.7, 2.3))
        output figure size

Outputs:

out_file: (a pathlike object or string representing a file)
        calculated FD per timestep
out_figure: (a pathlike object or string representing a file)
        output image file
fd_average: (a float)
        average FD

References:

None

NonSteadyStateDetector

Link to code

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

Inputs:

[Mandatory]
in_file: (a pathlike object or string representing an existing file)
        4D NIFTI EPI file

Outputs:

n_volumes_to_discard: (an integer (int or long))
        Number of non-steady state volumesdetected in the beginning of the
        scan.

TCompCor

Link to code

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

Inputs:

[Mandatory]
realigned_file: (a pathlike object or string representing an existing
          file)
        already realigned brain image (4D)

[Optional]
percentile_threshold: (0.0 < a floating point number < 1.0, nipype
          default value: 0.02)
        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.
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
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: mask_index
        requires: mask_files
mask_index: (a long integer >= 0)
        Position of mask in `mask_files` to use - first is the default.
        mutually_exclusive: merge_method
        requires: mask_files
mask_names: (a list of items which are a unicode 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).
components_file: (a unicode string, nipype default value:
          components_file.txt)
        Filename to store physiological components
num_components: (a long 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: variance_threshold
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: num_components
pre_filter: ('polynomial' or 'cosine' or False, nipype default value:
          polynomial)
        Detrend time series prior to component extraction
use_regress_poly: (a boolean)
        use polynomial regression pre-component extraction
regress_poly_degree: (a long integer >= 1, nipype default value: 1)
        the degree polynomial to use
header_prefix: (a unicode string)
        the desired header for the output tsv file (one column). If
        undefined, will default to "CompCor"
high_pass_cutoff: (a float, nipype default value: 128)
        Cutoff (in seconds) for "cosine" pre-filter
repetition_time: (a float)
        Repetition time (TR) of series - derived from image header if
        unspecified
save_pre_filter: (a boolean or a pathlike object or string
          representing a file, nipype default value: False)
        Save pre-filter basis as text file
save_metadata: (a boolean or a pathlike object or string representing
          a file, nipype default value: False)
        Save component metadata as text file
ignore_initial_volumes: (a long integer >= 0, nipype default value:
          0)
        Number of volumes at start of series to ignore
failure_mode: ('error' or 'NaN', nipype default value: error)
        When no components are found or convergence fails, raise an error or
        silently return columns of NaNs.

Outputs:

high_variance_masks: (a list of items which are a pathlike object or
          string representing an existing file)
        voxels exceeding the variance threshold
components_file: (a pathlike object or string representing an
          existing file)
        text file containing the noise components
pre_filter_file: (a pathlike object or string representing a file)
        text file containing high-pass filter basis
metadata_file: (a pathlike object or string representing a file)
        text file containing component metadata

References:

None

TSNR

Link to code

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() # doctest: +SKIP

Inputs:

[Mandatory]
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]
regress_poly: (a long integer >= 1)
        Remove polynomials
tsnr_file: (a pathlike object or string representing a file, nipype
          default value: tsnr.nii.gz)
        output tSNR file
mean_file: (a pathlike object or string representing a file, nipype
          default value: mean.nii.gz)
        output mean file
stddev_file: (a pathlike object or string representing a file, nipype
          default value: stdev.nii.gz)
        output tSNR file
detrended_file: (a pathlike object or string representing a file,
          nipype default value: detrend.nii.gz)
        input file after detrending

Outputs:

tsnr_file: (a pathlike object or string representing an existing
          file)
        tsnr image 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
detrended_file: (a pathlike object or string representing a file)
        detrended input file

combine_mask_files()

Link to code

Combines input mask files into a single nibabel image

A helper function for CompCor

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: a list of nibabel images

compute_dvars()

Link to code

Compute the DVARS [Power2012].

Particularly, the standardized DVARS [Nichols2013] are computed.

[Nichols2013]Nichols T, Notes on creating a standardized version of DVARS, 2013.

Note

Implementation details

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

param numpy.ndarray func:
 functional data, after head-motion-correction.
param numpy.ndarray mask:
 a 3D mask of the brain
param bool output_all:
 write out all dvars
param str out_file:
 a path to which the standardized dvars should be saved.
return:the standardized DVARS

compute_noise_components()

Link to code

Compute the noise components from the imgseries 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.

Filter options:

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.

cosine_filter()

Link to code

fallback_svd()

Link to code

is_outlier()

Link to code

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

param nparray points:
 an numobservations by numdimensions numpy array of observations
param float thresh:
 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.
return: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.

plot_confound()

Link to code

A helper function to plot fMRI confounds.

regress_poly()

Link to code

Returns data with degree polynomial regressed out.

param bool remove_mean:
 whether or not demean data (i.e. degree 0),
param int axis:numpy array axes along which regression is performed