9.1.3. Pre-processing#

Provide imports for preprocess sub-package.

class junifer.preprocess.BOLDWarper(using, reference)#

Class for warping BOLD NIfTI images.

Deprecated since version 0.0.3: BOLDWarper will be removed in v0.0.4, it is replaced by SpaceWarper because the latter works also with T1w data.

Parameters:

using{“fsl”, “ants”}

Implementation to use for warping:

“fsl” : Use FSL’s applywarp
“afni” : Use ANTs’ antsApplyTransforms

referencestr

The data type to use as reference for warping, can be either a data type like “T1w” or a template space like “MNI152NLin2009cAsym”.

Raises:

ValueError: If using is invalid or if reference is invalid.

Notes

If you are setting reference to a template space like “MNI152NLin2009cAsym”, make sure ANTs is available for the transformation else it will fail during runtime. It is tricky to validate this beforehand and difficult to enforce this as a requirement, hence the heads-up.

Initialize the class.

get_output_type(input_type)#

Get output type.

Parameters:

input_typestr: The data type input to the preprocessor.

Returns:

str: The data type output by the preprocessor.

get_valid_inputs()#

Get valid data types for input.

Returns:

list of str: The list of data types that can be used as input for this preprocessor.

preprocess(input, extra_input=None)#

Preprocess.

Parameters:

inputdict: The BOLD input from the Junifer Data object.
extra_inputdict, optional: The other fields in the Junifer Data object. Must include the Warp and ref value’s keys if native space transformation is needed.

Returns:

dict: The computed result as dictionary.
None: Extra “helper” data types as dictionary to add to the Junifer Data object.

Raises:

ValueError: If extra_input is None when transforming to native space i.e., using “T1w” as reference.
RuntimeError: If warp / transformation file extension is not “.mat” or “.h5” when transforming to native space or if the BOLD data is in the correct space and does not require warping.

class junifer.preprocess.BasePreprocessor(on=None, required_data_types=None)#

Abstract base class for all preprocessors.

For every interface that is required, one needs to provide a concrete implementation of this abstract class.

Parameters:

onstr or list of str or None, optional: The data type to apply the preprocessor on. If None, will work on all available data types (default None).
required_data_typesstr or list of str, optional: The data types needed for computation. If None, will be equal to on (default None).

Raises:

ValueError: If required input data type(s) is(are) not found.

Initialize the class.

abstract get_output_type(input_type)#

Get output type.

Parameters:

input_typestr: The data type input to the preprocessor.

Returns:

str: The data type output by the preprocessor.

abstract get_valid_inputs()#

Get valid data types for input.

Returns:

list of str: The list of data types that can be used as input for this preprocessor.

abstract preprocess(input, extra_input=None)#

Preprocess.

Parameters:

inputdict: A single input from the Junifer Data object to preprocess.
extra_inputdict, optional: The other fields in the Junifer Data object. Useful for accessing other data kind that needs to be used in the computation. For example, the confound removers can make use of the confounds if available (default None).

Returns:

dict: The computed result as dictionary.
dict or None: Extra “helper” data types as dictionary to add to the Junifer Data object. For example, computed BOLD mask can be passed via this. If no new “helper” data types is created, None is to be passed.

validate_input(input)#

Validate input.

Parameters:

inputlist of str: The input to the pipeline step. The list must contain the available Junifer Data dictionary keys.

Returns:

list of str: The actual elements of the input that will be processed by this pipeline step.

Raises:

ValueError: If the input does not have the required data.

class junifer.preprocess.SpaceWarper(using, reference, on)#

Class for warping data to other template spaces.

Parameters:

using{“fsl”, “ants”}

Implementation to use for warping:

“fsl” : Use FSL’s applywarp
“ants” : Use ANTs’ antsApplyTransforms

referencestr

The data type to use as reference for warping, can be either a data type like "T1w" or a template space like "MNI152NLin2009cAsym". Use "T1w" for native space warping and named templates for template space warping.

on{“T1w”, “T2w”, “BOLD”, “VBM_GM”, “VBM_WM”, “VBM_CSF”, “fALFF”, “GCOR”, “LCOR”} or list of the options

The data type to warp.

Raises:

ValueError: If using is invalid or if reference is invalid.

Initialize the class.

get_output_type(input_type)#

Get output type.

Parameters:

input_typestr: The data type input to the preprocessor.

Returns:

str: The data type output by the preprocessor.

get_valid_inputs()#

Get valid data types for input.

Returns:

list of str: The list of data types that can be used as input for this preprocessor.

preprocess(input, extra_input=None)#

Preprocess.

Parameters:

inputdict: The input from the Junifer Data object.
extra_inputdict, optional: The other fields in the Junifer Data object.

Returns:

dict: The computed result as dictionary.
None: Extra “helper” data types as dictionary to add to the Junifer Data object.

Raises:

ValueError: If extra_input is None when transforming to native space i.e., using "T1w" as reference.
RuntimeError: If the data is in the correct space and does not require warping or if FSL is used for template space warping.

class junifer.preprocess.fMRIPrepConfoundRemover(strategy=None, spike=None, detrend=True, standardize=True, low_pass=None, high_pass=None, t_r=None, masks=None)#

Class for confound removal using fMRIPrep confounds format.

Read confound files and select columns according to a pre-defined strategy.

Confound removal is based on nilearn.image.clean_img().

Parameters:

strategydict, optional

The strategy to use for each component. If None, will use the full strategy for all components (default None). The keys of the dictionary should correspond to names of noise components to include:

motion
wm_csf
global_signal

The values of dictionary should correspond to types of confounds extracted from each signal:

basic : only the confounding time series
power2 : signal + quadratic term
derivatives : signal + derivatives
full : signal + deriv. + quadratic terms + power2 deriv.

spikefloat, optional

If None, no spike regressor is added. If spike is a float, it will add a spike regressor for every point at which framewise displacement exceeds the specified float (default None).

detrendbool, optional

If True, detrending will be applied on timeseries, before confound removal (default True).

standardizebool, optional

If True, returned signals are set to unit variance (default True).

low_passfloat, optional

Low cutoff frequencies, in Hertz. If None, no filtering is applied (default None).

high_passfloat, optional

High cutoff frequencies, in Hertz. If None, no filtering is applied (default None).

t_rfloat, optional

Repetition time, in second (sampling period). If None, it will use t_r from nifti header (default None).

masksstr, dict or list of dict or str, optional

The specification of the masks to apply to regions before extracting signals. Check Using Masks for more details. If None, will not apply any mask (default None).

Initialize the class.

get_output_type(input_type)#

Get output type.

Parameters:

input_typestr: The input to the preprocessor.

Returns:

str: The data type output by the preprocessor.

get_valid_inputs()#

Get valid data types for input.

Returns:

list of str: The list of data types that can be used as input for this preprocessor.

preprocess(input, extra_input=None)#

Preprocess.

Parameters:

inputdict: A single input from the Junifer Data object to preprocess.
extra_inputdict, optional: The other fields in the Junifer Data object. Must include the BOLD_confounds key.

Returns:

dict: The computed result as dictionary.
dict or None: If self.masks is not None, then the target data computed mask is returned else None.