nipype.algorithms.confounds module¶
Algorithms to compute confounds in fMRI
ACompCor¶
Bases: CompCor
Anatomical compcor: for inputs and outputs, see CompCor. When the mask provided is an anatomical mask, then CompCor is equivalent to ACompCor.
- realigned_filea pathlike object or string representing an existing file
Already realigned brain image (4D).
- components_filea 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_prefixa string
The desired header for the output tsv file (one column). If undefined, will default to “CompCor”.
- high_pass_cutoffa float
Cutoff (in seconds) for “cosine” pre-filter. (Nipype default value:
128
)- ignore_initial_volumesan integer >= 0
Number of volumes at start of series to ignore. (Nipype default value:
0
)- mask_filesa 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
ormerge_index
must be provided.- mask_indexan 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_namesa 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_componentsan integer >= 1 or ‘all’
Number of components to return from the decomposition. If
num_components
isall
, 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_degreean integer >= 1
The degree polynomial to use. (Nipype default value:
1
)- repetition_timea float
Repetition time (TR) of series - derived from image header if unspecified.
- save_metadataa boolean or a pathlike object or string representing a file
Save component metadata as text file. (Nipype default value:
False
)- save_pre_filtera boolean or a pathlike object or string representing a file
Save pre-filter basis as text file. (Nipype default value:
False
)- use_regress_polya boolean
Use polynomial regression pre-component extraction.
- variance_threshold0.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
.
- components_filea pathlike object or string representing an existing file
Text file containing the noise components.
- metadata_filea pathlike object or string representing a file
Text file containing component metadata.
- pre_filter_filea pathlike object or string representing a file
Text file containing high-pass filter basis.
CompCor¶
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 onlyIn the case of
polynomial
andcosine
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
- realigned_filea pathlike object or string representing an existing file
Already realigned brain image (4D).
- components_filea 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_prefixa string
The desired header for the output tsv file (one column). If undefined, will default to “CompCor”.
- high_pass_cutoffa float
Cutoff (in seconds) for “cosine” pre-filter. (Nipype default value:
128
)- ignore_initial_volumesan integer >= 0
Number of volumes at start of series to ignore. (Nipype default value:
0
)- mask_filesa 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
ormerge_index
must be provided.- mask_indexan 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_namesa 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_componentsan integer >= 1 or ‘all’
Number of components to return from the decomposition. If
num_components
isall
, 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_degreean integer >= 1
The degree polynomial to use. (Nipype default value:
1
)- repetition_timea float
Repetition time (TR) of series - derived from image header if unspecified.
- save_metadataa boolean or a pathlike object or string representing a file
Save component metadata as text file. (Nipype default value:
False
)- save_pre_filtera boolean or a pathlike object or string representing a file
Save pre-filter basis as text file. (Nipype default value:
False
)- use_regress_polya boolean
Use polynomial regression pre-component extraction.
- variance_threshold0.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
.
- components_filea pathlike object or string representing an existing file
Text file containing the noise components.
- metadata_filea pathlike object or string representing a file
Text file containing component metadata.
- pre_filter_filea pathlike object or string representing a file
Text file containing high-pass filter basis.
ComputeDVARS¶
Bases: BaseInterface
Computes the DVARS.
- in_filea pathlike object or string representing an existing file
Functional data, after HMC.
- in_maska pathlike object or string representing an existing file
A brain mask.
- figdpian integer
Output dpi for the plot. (Nipype default value:
100
)- figformat‘png’ or ‘pdf’ or ‘svg’
Output format for figures. (Nipype default value:
png
)- figsizea tuple of the form: (a float, a float)
Output figure size. (Nipype default value:
(11.7, 2.3)
)- intensity_normalizationa 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_zerovariancea boolean
Remove voxels with zero variance. (Nipype default value:
True
)- save_alla boolean
Output all DVARS. (Nipype default value:
False
)- save_nstda boolean
Save non-standardized DVARS. (Nipype default value:
False
)- save_plota boolean
Write DVARS plot. (Nipype default value:
False
)- save_stda boolean
Save standardized DVARS. (Nipype default value:
True
)- save_vxstda boolean
Save voxel-wise standardized DVARS. (Nipype default value:
False
)- series_tra float
Repetition time in sec.
- variance_tola float
Maximum variance to consider “close to” zero for the purposes of removal. (Nipype default value:
1e-07
)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_stda pathlike object or string representing an existing file
Output DVARS plot.
- fig_vxstda pathlike object or string representing an existing file
Output DVARS plot.
- out_alla pathlike object or string representing an existing file
Output text file.
- out_nstda pathlike object or string representing an existing file
Output text file.
- out_stda pathlike object or string representing an existing file
Output text file.
- out_vxstda pathlike object or string representing an existing file
Output text file.
FramewiseDisplacement¶
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.
- in_filea 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.
- figdpian integer
Output dpi for the FD plot. (Nipype default value:
100
)- figsizea tuple of the form: (a float, a float)
Output figure size. (Nipype default value:
(11.7, 2.3)
)- normalizea boolean
Calculate FD in mm/s. (Nipype default value:
False
)- out_figurea pathlike object or string representing a file
Output figure name. (Nipype default value:
fd_power_2012.pdf
)- out_filea pathlike object or string representing a file
Output file name. (Nipype default value:
fd_power_2012.txt
)- radiusa 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_plota boolean
Write FD plot. (Nipype default value:
False
)- series_tra float
Repetition time in sec.
- fd_averagea float
Average FD.
- out_figurea pathlike object or string representing a file
Output image file.
- out_filea pathlike object or string representing a file
Calculated FD per timestep.
NonSteadyStateDetector¶
Bases: BaseInterface
Returns the number of non-steady state volumes detected at the beginning of the scan.
- in_filea pathlike object or string representing an existing file
4D NIFTI EPI file.
- n_volumes_to_discardan integer
Number of non-steady state volumesdetected in the beginning of the scan.
TCompCor¶
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
- realigned_filea pathlike object or string representing an existing file
Already realigned brain image (4D).
- components_filea 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_prefixa string
The desired header for the output tsv file (one column). If undefined, will default to “CompCor”.
- high_pass_cutoffa float
Cutoff (in seconds) for “cosine” pre-filter. (Nipype default value:
128
)- ignore_initial_volumesan integer >= 0
Number of volumes at start of series to ignore. (Nipype default value:
0
)- mask_filesa 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
ormerge_index
must be provided.- mask_indexan 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_namesa 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_componentsan integer >= 1 or ‘all’
Number of components to return from the decomposition. If
num_components
isall
, then all components will be retained. Mutually exclusive with inputs:variance_threshold
.- percentile_threshold0.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_degreean integer >= 1
The degree polynomial to use. (Nipype default value:
1
)- repetition_timea float
Repetition time (TR) of series - derived from image header if unspecified.
- save_metadataa boolean or a pathlike object or string representing a file
Save component metadata as text file. (Nipype default value:
False
)- save_pre_filtera boolean or a pathlike object or string representing a file
Save pre-filter basis as text file. (Nipype default value:
False
)- use_regress_polya boolean
Use polynomial regression pre-component extraction.
- variance_threshold0.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
.
- components_filea pathlike object or string representing an existing file
Text file containing the noise components.
- high_variance_masksa list of items which are a pathlike object or string representing an existing file
Voxels exceeding the variance threshold.
- metadata_filea pathlike object or string representing a file
Text file containing component metadata.
- pre_filter_filea pathlike object or string representing a file
Text file containing high-pass filter basis.
TSNR¶
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()
- in_filea list of items which are a pathlike object or string representing an existing file
Realigned 4D file or a list of 3D files.
- detrended_filea pathlike object or string representing a file
Input file after detrending. (Nipype default value:
detrend.nii.gz
)- mean_filea pathlike object or string representing a file
Output mean file. (Nipype default value:
mean.nii.gz
)- regress_polyan integer >= 1
Remove polynomials.
- stddev_filea pathlike object or string representing a file
Output tSNR file. (Nipype default value:
stdev.nii.gz
)- tsnr_filea pathlike object or string representing a file
Output tSNR file. (Nipype default value:
tsnr.nii.gz
)
- detrended_filea pathlike object or string representing a file
Detrended input file.
- mean_filea pathlike object or string representing an existing file
Mean image file.
- stddev_filea pathlike object or string representing an existing file
Std dev image file.
- tsnr_filea 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.
[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.
- 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. Ifcomponents_criterion
isall
, 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 tomask_images
, with the ith element ofmask_names
naming the ith element ofmask_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
iscosine
.
- 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 boolean 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