9.1.3. Pre-processing¶

Preprocessors for preprocessing data before feature extraction.

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

Abstract base class for preprocessor.

For every preprocessor, one needs to provide a concrete implementation of this abstract class.

Parameters:

onstr or list of str or None, optional: The data type(s) 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:

AttributeError: If the preprocessor does not have _VALID_DATA_TYPES attribute.
ValueError: If required input data type(s) is(are) not found.

Initialize the class.

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 type 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.

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.Smoothing(using, on, smoothing_params=None)¶

Class for smoothing.

Parameters:

using{“nilearn”, “afni”, “fsl”}

Implementation to use for smoothing:

“nilearn” : Use nilearn.image.smooth_img()
“afni” : Use AFNI’s 3dBlurToFWHM
“fsl” : Use FSL SUSAN’s susan

on{“T1w”, “T2w”, “BOLD”} or list of the options

The data type to apply smoothing to.

smoothing_paramsdict, optional

Extra parameters for smoothing as a dictionary (default None). If using="nilearn", then the valid keys are:

fmhwscalar, numpy.ndarray, tuple or list of scalar, “fast” or None
Smoothing strength, as a full-width at half maximum, in millimeters:
- If nonzero scalar, width is identical in all 3 directions.
- If numpy.ndarray, tuple, or list, it must have 3 elements, giving the FWHM along each axis. If any of the elements is 0 or None, smoothing is not performed along that axis.
- If "fast", a fast smoothing will be performed with a filter [0.2, 1, 0.2] in each direction and a normalisation to preserve the local average value.
- If None, no filtering is performed (useful when just removal of non-finite values is needed).

else if using="afni", then the valid keys are:

fwhmint or float
Smooth until the value. AFNI estimates the smoothing and then applies smoothing to reach fwhm.

else if using="fsl", then the valid keys are:

brightness_thresholdfloat
Threshold to discriminate between noise and the underlying image. The value should be set greater than the noise level and less than the contrast of the underlying image.
fwhmfloat
Spatial extent of smoothing.

Initialize the class.

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.

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

Class for warping data to other template spaces.

Parameters:

using{“fsl”, “ants”, “auto”}

Implementation to use for warping:

“fsl” : Use FSL’s applywarp
“ants” : Use ANTs’ antsApplyTransforms
“auto” : Auto-select tool when reference="T1w"

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.

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.

Raises:

ValueError: If extra_input is None when transforming to native space i.e., using "T1w" as reference.
RuntimeError: If warper could not be found in extra_input when using="auto" or converting from native space or if the data is in the correct space and does not require warping or if FSL is used when reference="T1w".

class junifer.preprocess.TemporalFilter(detrend=True, standardize=True, low_pass=None, high_pass=None, t_r=None, masks=None)¶

Class for temporal filtering.

Temporal filtering is based on nilearn.image.clean_img().

Parameters:

detrendbool, optional: If True, detrending will be applied on timeseries (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.

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.

Returns:

dict: The computed result as dictionary. If self.masks is not None, then the target data computed mask is updated for further steps.

class junifer.preprocess.TemporalSlicer(start, stop, duration=None, t_r=None)¶

Class for temporal slicing.

Parameters:

startfloat: Starting time point, in second.
stopfloat or None: Ending time point, in second. If None, stops at the last time point. Can also do negative indexing and has the same meaning as standard Python slicing except it represents time points.
durationfloat or None, optional: Time duration to add to start, in second. If None, stop is respected, else error is raised (default None).
t_rfloat or None, optional: Repetition time, in second (sampling period). If None, it will use t_r from nifti header (default None).

Raises:

ValueError: If start is negative.

Initialize the class.

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.

Raises:

RuntimeError: If no time slicing will be performed or if stop is not None when duration is provided or if calculated stop index is greater than allowed value.

class junifer.preprocess.fMRIPrepConfoundRemover(strategy=None, spike=None, scrub=None, fd_threshold=None, std_dvars_threshold=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 except "scrubbing" which will be set to False (default None). The keys of the dictionary should correspond to names of noise components to include:

motion
wm_csf
global_signal
scrubbing

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.

except scrubbing which needs to be bool.

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).

scrubint, optional

After accounting for time frames with excessive motion, further remove segments shorter than the given number. When the value is 0, remove time frames based on excessive framewise displacement and DVARS only. If None and no "scrubbing" in strategy, no scrubbing is performed, else the default value is 0. The default value is referred as full scrubbing (default None).

fd_thresholdfloat, optional

Framewise displacement threshold for scrub in mm. If None no "scrubbing" in strategy, no scrubbing is performed, else the default value is 0.5 (default None).

std_dvars_thresholdfloat, optional

Standardized DVARS threshold for scrub. DVARs is defined as root mean squared intensity difference of volume N to volume N+1. D referring to temporal derivative of timecourses, VARS referring to root mean squared variance over voxels. If None and no "scrubbing" in strategy, no scrubbing is performed, else the default value is 1.5 (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.

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.

Returns:

dict: The computed result as dictionary. If self.masks is not None, then the target data computed mask is updated for further steps.