mbfmri.preprocessing

This module is for processing fMRI images and behavioral data. For fMRI images (*_bold.nii), mbfmri.preprocessing.bold.VoxelFeatureGenerator masks, smoothes, and cleans input images to generate multi-voxel signals. For behavioral data (*_events.tsv), mbfmri.preprocessing.events.LatentProcessGenerator` fits computational models, selects best model, extracts latent process and generate latent process signals.

The outputfiles will be saved in new BIDS derivatives layout (named as MB-MVPA).

The below figure is an example of generated signals.

example

Submodules

mbfmri.preprocessing.bold

class mbfmri.preprocessing.bold.VoxelFeatureGenerator(bids_layout, subjects='all', sessions='all', save_path=None, task_name=None, space_name=None, feature_name='unnamed', fmriprep_name='fMRIPrep', mask_path=None, mask_threshold=1.65, mask_smoothing_fwhm=6, include_default_mask=True, gm_only=False, atlas=None, rois=[], zoom=(2, 2, 2), smoothing_fwhm=6, standardize=True, high_pass=0.0078125, detrend=True, confounds=[], n_thread=4, ignore_original=True, t_r=None, slice_time_ref=0.5, bold_suffix='bold', confound_suffix='regressors', **kwargs)

Bases: object

VoxelFeatureGenerator is for masking fMRI data (“events.tsv”) to make voxel features. The mask image will be obtained by union of given mask images, which are recommended to be downloaded from Neurosynth. The output files will be stored in the derivative BIDS layout for the package. Users can expect a voxel feature npy file with shape=(time,feature_num) for each run of bold.nii files.

Parameters

  • bids_layout (str or pathlib.PosixPath or bids.layout.layout.BIDSLayout or BIDSController) – Root for input data. It should follow BIDS convention.

  • subjects (list of str or “all”,default=”all”) – List of subject IDs to load. If “all”, all the subjects found in the layout will be loaded.

  • sessions (list of str or “all”, default=”all”) – List of valid session IDs. If “all”, all the sessions found in the layout will be loaded.

  • save_path (str or pathlib.PosixPath, default=None) – Path for saving preprocessed results. If not given, the derivatives directory will be used.

  • task_name (str, default=None) – Name of the task. If not given, the most common task name will be automatically selected.

  • feature_name (str, default=”unnamed”) – Name for indicating preprocessed feature. This is adopted for distinguishing different configuration of feature processing.

  • fmriprep_name (str, default=”fMRIPrep”) – Name for derivatve BIDS layout for fmriprep. As default, it is “fMRIPrep”, which is the name of preprocessing by fMRIPrep. (https://fmriprep.org/en/stable/)

  • mask_path (str or pathlib.PosixPath, default=None) – Path for directory containing mask files. If None, the default mask_path is ‘BIDS_ROOT/masks.’ Then, images in mask_path/include will be used to create a mask to include and images in mask_path/exclude will be used to create a mask to exclude Mask files are nii files recommended to be downloaded from Neurosynth. (https://neurosynth.org/) As default, each of the nii files is regarded as a probablistic map, and the mask_trheshold will be used as the cut-off value for binarizing. The absolute values are used for thresholding. The binarized maps will be integrated by union operation to be a single binary image.

  • mask_threshold (float, default=1.65) – Cut-off value for thresholding mask images. The default value (=1.65) means the boundary of upper 90% in normal distribution.

  • mask_smoothing_fwhm (float, default=6) – Size in millimeters of the spatial smoothing of mask images. If None, smoothing is skipped.

  • include_default_mask (bool, default=True) – Indicate if the default mask (mni space) should be applied.

  • gm_only (bool, default=False) – Indicate if gray matter mask should be applied

  • atlas (str, default=None) – Name of atlas when masking by ROIs. See `Atlas-ROI list <>`_.

  • rois (list of str, default=[]) – Names or ROI when masking by ROI. See `Atlas-ROI list <>`_.

  • zoom ((int,int,int), default=(2,2,2)) – Window size for zooming fMRI images. Each of three components means x, y ,z axis respectively. The size of voxels will be enlarged by the factor of corresponding component value. Ex. zoom = (2,2,2) means the original 2 mm^3 voxels will be 4mm^3, so reducing the total number of voxels in a single image.

  • smoothing_fwhm (float, default=None) – Size in millimeters of the spatial smoothing of fMRI. If None, smoothing is skipped.

  • standardize (boolean, default=True) – Indicate tf standardization is required for fMRI.

  • high_pass (float, default = 1/128) – Value for high pass filter. [Hz]

  • detrend (boolean, default=False) – If True, remove a global linear trend in data.

  • confounds (list of str, default=[]) – Names of confound factors to be regressed out. Each should be in the columns of confound files.

  • n_thread (int, default=4) – Number of threads for multi-processing. Please consider your computing capcity and enter the affordable number.

  • ignore_original (boolean, default=True) – Indicate whether it would cover behaviroal data in the original BIDSLayout. If True, it will only consider data in the derivative layout for fMRI preprocessed data.

  • space_name (str, default=None) – Name of template space. If not given, the most common space in input layout will be selected.

  • t_r (float, default=None) – Time resolution in second. It will be overrided by value from input data if applicable.

  • slice_time_ref (float, default=.5) – Slice time reference in ratio in 0,1]. It will be overrided by value from input data if applicable.

  • bold_suffix (str, default=’regressors’) – Name of suffix indicating preprocessed fMRI file

  • confound_suffix (str, default=’regressors’) – Name of suffix indicating confounds file

summary()
run(feature_name=None, overwrite=False, confounds=None, n_thread=None, **kwargs)

Generate multi-voxel feature data (masking & zooming & cleaning).

Atlas-ROIs information

mbfmri.preprocessing.events

class mbfmri.preprocessing.events.LatentProcessGenerator(bids_layout, subjects='all', sessions='all', save_path=None, task_name=None, process_name='unnamed', dm_model='unnamed', adjust_function=None, filter_function=None, latent_function=None, adjust_function_dfwise=None, filter_function_dfwise=None, latent_function_dfwise=None, computational_model=None, individual_params=None, skip_compmodel=False, criterion='looic', hrf_model='glover', onset_name='onset', duration_name='duration', end_name=None, use_1sec_duration=True, mask_duration=False, t_r=None, slice_time_ref=0.5, n_core=4, ignore_fmriprep=False, fmriprep_name='fMRIPrep', event_suffix='events', **kwargs)

Bases: object

LatetentPrecessGenerator is for converting behavior data (“events.tsv”) to BOLD-like signals, so the time dimension of them can match the time diemnsion of voxel feature data. The output files will be stored in the derivative BIDS layout for the package. You can expect a modulation tsv file with onset, duration, modulation, a time mask npy file, a binary map for indicating valid time points, and a BOLD-like signal npy file for each run of events.tsv files.

Parameters

  • bids_layout (str or pathlib.PosixPath or bids.layout.layout.BIDSLayout or BIDSController) – Root for input data. It should follow BIDS convention.

  • subjects (list of str or “all”, default=”all”) – List of valid subject IDs. If “all”, all the subjects found in the layout will be loaded.

  • sessions (list of str or “all”, default=”all”) – List of valid session IDs. If “all”, all the sessions found in the layout will be loaded.

  • save_path (str or pathlib.PosixPath, default=None) – Path for saving preprocessed results. If not given, the derivatives directory will be used.

  • task_name (str, default=None) – Name of the task. If not given, the most common task name will be automatically selected.

  • process_name (str, default=”unnamed”) – Name of the target latent process. It should be match the name defined in computational modeling

  • dm_model (str, default=”unnamed”) – Name for computational modeling by hBayesDM. You can still use this parameter to assign the name of the model, even you would not choose to emloy hBayesDM.

  • adjust_function (function(pandas.Series, dict)-> pandas.Series, default=None) – User-defined row-wise function for modifying each row of behavioral data. adjust_function (a row of DataFrame) : a row of DataFrame with modified behavior data If None, it does nothing.

  • filter_function (function(pandas.Series, dict)-> boolean, default=None) – User-defined row-wise function for filtering each row of behavioral data. filter_function (a row of DataFrame) : True or False If None, it does nothing.

  • latent_function (function(pandas.Series, dict)-> pandas.Series, default=None) – User-defined row wise function for calculating latent process. The values will be indexed by ‘modulation’ column name. latent_function (a row of DataFrame)-> a row of DataFrame with modulation

  • adjust_function_dfwise (function(pandas.DataFrame, dict)-> pandas.DataFrame, default=None) – User-defined dataframe-wise function for modifying each row of behavioral data. If not given, it will be made by using adjust_function. If given, it will override adjust_function.

  • filter_function_dfwise (function(pandas.DataFrame, dict)-> pandas.DataFrame, default=None) – User-defined dataframe-wise function for filtering each row of behavioral data. If not given, it will be made by using filter_function. If given, it will override filter_function.

  • latent_function_dfwise (function(pandas.DataFrame, dict)-> pandas.DataFrame, default=None) – User-defined dataframe-wise function for calculating latent process. If not given, it will be made by using latent_function. If given, it will override latent_function.

  • individual_params (str or pathlib.PosixPath or pandas.DataFrame, default=None) – Path or loaded DataFrame for tsv file with individual parameter values. If not given, find the file from the default path MB-MVPA_root/task-*task_name*_model-*model_name*_individual_params.tsv If the path is empty, it will remain None indicating a need for running hBayesDM. So, it will be set after runniing hBayesDM package.

  • skip_compmodel (boolean, default=False) – Indicate if computational modeling should be skipped, which means the user provided precalculated latent process.

  • criterion (str, default=’looic’) – Criterion for model comparison. Currently, LOOIC is avaliable.

  • hrf_model (str, default=”glover”) – Name for hemodynamic response function, which will be convoluted with event data to make BOLD-like signal. The below notes are retrieved from the code of “nilearn.glm.first_level.hemodynamic_models.compute_regressor” (https://github.com/nilearn/nilearn/blob/master/nilearn/glm/first_level/hemodynamic_models.py)

    The different hemodynamic models can be understood as follows:

    • “spm”: this is the hrf model used in SPM.

    • “glover”: this one corresponds to the Glover hrf.

  • onset_name (str, default=”onset”) – Column name indicating onset values.

  • duration_name (str, default=”duration”) – Column name indicating duration values.

  • end_name (str, default=None) – Column name indicating end of valid time. If given, end-onset will be used as duration and override duration_name. If None, it would be ignored and duration_name will be used.

  • use_1sec_duration (bool, default=True) – If True, duration will be fixed as 1 second. This parameter will override duration_name and end_name.

  • mask_duration (boolean, default=False) – If True use “duration” column to make a time mask, if False all the gaps following trials after valid trials would be included in the time mask.

  • t_r (float, default=None) – Time resolution in second. It will be overrided by value from input data if applicable.

  • slice_time_ref (float, default=.5) – Slice time reference in ratio in 0,1]. It will be overrided by value from input data if applicable.

  • n_core (int, default=4) – Number of core in hBayesDM.

  • ignore_fmriprep (boolean, default=False) – Indicate whether it can ignore fMRIPrep layout. It should be True if users don’t have fMRIPrep, but still want to run computational modeling.

  • fmriprep_name (str, default=’fMRIPrep’) – Name of derivative layout for preprocessed fMRI.

  • event_suffix (str, default=’events’) – Suffix name for behavioral data file.

summary()
set_computational_model(refit_compmodel=False, individual_params=None, df_events=None, adjust_function_dfwise=None, filter_function_dfwise=None, n_core=None, **kwargs)

Set computationl model for latent process extraction (model fitting & selection).

Parameters

refit_compmodel (bool, default=False) – Indicate if re-fitting computational models is required.

run(overwrite=True, process_name=None, modeling_kwargs={})

Generate latent process signal by computational modeling.

Parameters

overwrite (bool, default=False) – Indicate if overwriting processed outputs is required.