niworkflows.interfaces.confounds module

Select terms for a confound model, and compute any requisite expansions.

class niworkflows.interfaces.confounds.ExpandModel(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Expand a confound model according to a specified formula.

Mandatory Inputs:

confounds_file (a pathlike object or string representing an existing file) – TSV containing confound time series for expansion according to the specified formula.

Optional Inputs:

• model_formula (a string) – Formula for generating model expansions. By default, the 32-parameter expansion will be generated. Note that any expressions to be expanded must be in parentheses, even if they include only a single variable (e.g., (x)^2, not x^2).

  Examples:

  • rps + wm + csf + gsr : 9-parameter model. rps denotes realignment parameters, wm denotes mean white matter signal, csf denotes mean cerebrospinal fluid signal, and gsr denotes mean global signal.

  • (dd1(rps + wm + csf + gsr))^^2 : 36-parameter expansion. rps + wm + csf + gsr denotes that realignment parameters and mean WM, CSF, and global signals should be included. dd1 denotes that these signals should be augmented with their first temporal derivatives. ^^2 denotes that the original signals and temporal derivatives should be augmented with quadratic expansions.

  • (dd1(rps))^^2 : 24-parameter expansion. rps denotes that realignment parameters should be included. dd1 and ^^2 denote temporal derivative and quadratic expansions as above.

  • (dd1(rps + wm + csf + gsr))^^2 + others : generate all expansion terms necessary for a 36-parameter model as above, and concatenate those expansion terms to all other regressor columns in the confounds file.

  (Nipype default value: (dd1(rps + wm + csf + gsr))^^2 + others)

• output_file (a pathlike object or string representing a file) – Output path.

Outputs:

confounds_file (a pathlike object or string representing an existing file) – Output confounds file.

class niworkflows.interfaces.confounds.NormalizeMotionParams(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Convert input motion parameters into the designated convention.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – The input parameters file.

Optional Inputs:

format (‘FSL’ or ‘AFNI’ or ‘FSFAST’ or ‘NIPY’) – Output format. (Nipype default value: FSL)

Outputs:

out_file (a pathlike object or string representing an existing file) – Written file path.

class niworkflows.interfaces.confounds.SpikeRegressors(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Generate spike regressors.

Mandatory Inputs:

confounds_file (a pathlike object or string representing an existing file) – TSV containing criterion time series (e.g., framewise displacement, DVARS) to be used for creating spike regressors.

Optional Inputs:

• concatenate (a boolean) – Indicates whether to concatenate spikes to existing confounds or return spikes only. (Nipype default value: True)

• dvars_thresh (a float) – Minimum standardised DVARS threshold for flagging a frame as a spike. (Nipype default value: 1.5)

• fd_thresh (a float) – Minimum framewise displacement threshold for flagging a frame as a spike. (Nipype default value: 0.5)

• header_prefix (a string) – Prefix for spikes in the output TSV header. (Nipype default value: motion_outlier)

• lags (a list of items which are an integer) – Relative indices of lagging frames to flag for each flagged frame. (Nipype default value: [0])

• minimum_contiguous (an integer or None) – Minimum number of contiguous volumes required to avoid flagging as a spike. (Nipype default value: None)

• output_file (a pathlike object or string representing a file) – Output path.

• output_format (‘spikes’ or ‘mask’) – Format of output (spikes or mask). (Nipype default value: spikes)

Outputs:

confounds_file (a pathlike object or string representing an existing file) – Output confounds file.

niworkflows.interfaces.confounds.exponential_terms(order, variables, data)

Compute exponential expansions.

Parameters:

• order (list of int) – A list of exponential terms to include. For instance, [1, 2] indicates that the first and second exponential terms should be added. To retain the original terms, 1 must be included in the list.

• variables (list of str) – List of variables for which exponential terms should be computed.

• data (DataFrame) – Table of values of all observations of all variables.

Returns:

• variables_exp (list) – A list of variables to include in the final data frame after adding the specified exponential terms.

• data_exp (DataFrame) – Table of values of all observations of all variables, including any specified exponential terms.

niworkflows.interfaces.confounds.parse_expression(expression, parent_data)

Parse an expression in a model formula.

Parameters:

• expression (str) – Formula expression: either a single variable or a variable group paired with an operation (exponentiation or differentiation).

• parent_data (DataFrame) – The source data for the model expansion.

Returns:

• variables (list) – A list of variables in the provided formula expression.

• data (DataFrame) – A tabulation of all terms in the provided formula expression.

niworkflows.interfaces.confounds.parse_formula(model_formula, parent_data, unscramble=False)

Parse a confound manipulation formula.

Recursively parse a model formula by breaking it into additive atoms and tracking grouping symbol depth.

Parameters:

• model_formula (str) – Expression for the model formula, e.g. (a + b)^^2 + dd1(c + (d + e)^3) + f Note that any expressions to be expanded must be in parentheses, even if they include only a single variable (e.g., (x)^2, not x^2). Temporal derivative options:

  • d6(variable) for the 6th temporal derivative

  • dd6(variable) for all temporal derivatives up to the 6th

  • d4-6(variable) for the 4th through 6th temporal derivatives

  • 0 must be included in the temporal derivative range for the original term to be returned when temporal derivatives are computed.

  Exponential options:

  • (variable)^6 for the 6th power

  • (variable)^^6 for all powers up to the 6th

  • (variable)^4-6 for the 4th through 6th powers

  • 1 must be included in the powers range for the original term to be returned when exponential terms are computed.

  Temporal derivatives and exponential terms are computed for all terms in the grouping symbols that they adjoin.

• parent_data (DataFrame) – A tabulation of all values usable in the model formula. Each additive term in model_formula should correspond either to a variable in this data frame or to instructions for operating on a variable (for instance, computing temporal derivatives or exponential terms).

Returns:

• variables (list of str) – A list of variables included in the model parsed from the provided formula.

• data (DataFrame) – All values in the complete model.

niworkflows.interfaces.confounds.spike_regressors(data, criteria=None, header_prefix='motion_outlier', lags=None, minimum_contiguous=None, concatenate=True, output='spikes')

Add spike regressors to a confound/nuisance matrix.

Parameters:

• data (DataFrame) – A tabulation of observations from which spike regressors should be estimated.

• criteria (dict of (str, '>' or '<' or float)) – Criteria for generating a spike regressor. If, for a given frame, the value of the variable corresponding to the key exceeds the threshold indicated by the value, then a spike regressor is created for that frame. By default, the strategy from [Power2014] is implemented: any frames with FD greater than 0.5 or standardised DV greater than 1.5 are flagged for censoring.

• header_prefix (str) – The prefix used to indicate spike regressors in the output data table.

• lags (list of int) – A list indicating the frames to be censored relative to each flag. For instance, [0] censors the flagged frame, while [0, 1] censors both the flagged frame and the following frame.

• minimum_contiguous (int or None) – The minimum number of contiguous frames that must be unflagged for spike regression. If any series of contiguous unflagged frames is shorter than the specified minimum, then all of those frames will additionally have spike regressors implemented.

• concatenate (bool) – Indicates whether the returned object should include only spikes (if false) or all input time series and spikes (if true, default).

• output (str) – Indicates whether the output should be formatted as spike regressors (‘spikes’, a separate column for each outlier) or as a temporal mask (‘mask’, a single output column indicating the locations of outliers).

Returns:

data – The input DataFrame with a column for each spike regressor.

Return type:

DataFrame

References

[Power2014]

Power JD, et al. (2014) Methods to detect, characterize, and remove motion artifact in resting state fMRI. NeuroImage. doi:10.1016/j.neuroimage.2013.08.048.

niworkflows.interfaces.confounds.temporal_derivatives(order, variables, data)

Compute temporal derivative terms by the method of backwards differences.

Parameters:

• order (list of int) – A list of temporal derivative terms to include. For instance, [1, 2] indicates that the first and second derivative terms should be added. To retain the original terms, 0 must be included in the list.

• variables (list of str) – List of variables for which temporal derivative terms should be computed.

• data (DataFrame) – Table of values of all observations of all variables.

Returns:

• variables_deriv (list) – A list of variables to include in the final data frame after adding the specified derivative terms.

• data_deriv (DataFrame) – Table of values of all observations of all variables, including any specified derivative terms.