GLM approach

mbfmri.core.glm package

model-based fMRI - GLM version

referenece

mbfmri.core.glm.run_mbglm(bids_layout, config=None, report_path=None, overwrite=False, overwrite_latent_process=True, refit_compmodel=False, **kwargs)

Callable function of GLM approach of model-based fMRI to enable a single line usage.

  1. preprocess behavioral data to generate latent process signals.

  2. load fMRI images and latent process signals.

  3. run first-level and second-level GLM.

Parameters

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

  • config (dict or str or pathlib.PosixPath, default=None) – Dictionary for keyworded configuration, or path for yaml file. The configuration input will override the default configuration.

  • report_path (str or pathlib.PosixPath, defualt=None) – Path for saving outputs. Default path will be set as bids_root/mbmvpa/glm/ (If None)

  • overwrite (bool, default=False) – Indicate if processing multi-voxel signals is required though the files exist.

  • overwrite_latent (bool, default=False) – Indicate if generating latent process signals is required though the files exist.

  • refit_compmodel (bool, default=False) – Indicate if fitting computational model is required though the fitted results (indiv. params. and LOOIC) exist.

  • **kwargs (dict) – Dictionary for keywarded arguments. This allows users to override default configuration and config input. Argument names are same as those of wrapped modules.

    Generating multi-voxel signals document

    Generating latent process signals document

    Data loading document

    GLM document

    Parameters of the above modules can be controlled by input paramter by keywords. (e.g. run_mbfmri(…, mask_smoothing_fwhm=6, …, alpha=0.01) means mask_smoothing_fwhm will be set in VoxelFeatureGenerator and alpha will be set in ElasticNet.) Please check full list of configuration parameters <https://project-model-based-fmri.readthedocs.io/en/latest/mbfmri.core.html#full-list-of-configuration>_.

Examples

from mbfmri.core.glm import run_mbglm
import hbayesdm

_ = run_mbglm( bids_layout='mini_bornstein2017',    # data
               dm_model= 'banditNarm_lapse_decay',  # computational model
               feature_name='zoom2rgrout',          # indentifier for processed fMRI data
               task_name='multiarmedbandit',        # identifier for task
               process_name='PEchosen',             # identifier for target latent process
               subjects='all',                      # list of subjects to include
               report_path=report_path,             # save path for reporting results
               confounds=["trans_x", "trans_y",     # list of confounds to be controlled in GLM
                          "trans_z", "rot_x",
                          "rot_y", "rot_z"],
               n_core=4,                            # number of core for multi-processing in hBayesDM
               n_thread=4,                          # number of thread for multi-threading in generating voxel features
               overwrite=True,                      # indicate if re-run and overwriting are required
               refit_compmodel=True,                # indicate if refitting comp. model is required
              )
class mbfmri.core.glm.MBGLM(bids_layout, config=None, report_path=None, **kwargs)

Bases: mbfmri.core.base.MBFMRI

Class for GLM approach of model-based fMRI to enable a single line usage.

  1. preprocess behavioral data to generate latent process signals.

  2. load fMRI images and latent process signals.

  3. run first-level and second-level GLM.

Parameters

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

  • config (dict or str or pathlib.PosixPath, default=None) – Dictionary for keyworded configuration, or path for yaml file. The configuration input will override the default configuration.

  • report_path (str or pathlib.PosixPath, defualt=None) – Path for saving outputs. Default path will be set as bids_root/mbmvpa/mvpa/ (If None)

  • **kwargs (dict) – Dictionary for keywarded arguments. This allows users to override default configuration and config input. Argument names are same as those of wrapped modules.

    Generating multi-voxel signals document

    Generating latent process signals document

    Data loading document

    GLM document

    Parameters of the above modules can be controlled by input paramter by keywords. (e.g. run_mbfmri(…, mask_smoothing_fwhm=6, …, alpha=0.01) means mask_smoothing_fwhm will be set in VoxelFeatureGenerator and alpha will be set in ElasticNet.) Please check full list of configuration parameters<https://project-model-based-fmri.readthedocs.io/en/latest/mbfmri.core.html#full-list-of-configuration>_.

run(overwrite=False, overwrite_latent_process=True, refit_compmodel=False)

run model-based fMRI

Parameters

  • overwrite (bool, default=False) – Indicate if processing multi-voxel signals is required though the files exist.

  • overwrite_latent (bool, default=False) – Indicate if generating latent process signals is required though the files exist.

  • refit_compmodel (bool, default=False) – Indicate if fitting computational model is required though the fitted results (indiv. params. and LOOIC) exist.

class mbfmri.core.glm.GLM(bids_layout, task_name, process_name, fmriprep_name='fMRIPrep', fmriprep_layout=None, mbmvpa_layout=None, space_name=None, mask_path=None, mask_threshold=2.58, mask_smoothing_fwhm=6, include_default_mask=True, atlas=None, rois=[], gm_only=False, glm_save_path='.', n_core=4, bold_suffix='bold', confound_suffix='regressors', subjects='all', sessions='all', zoom=(1, 1, 1), confounds=[], t_r=None, slice_time_ref=0.5, **glm_kwargs)

Bases: object

Class for model-based fMRI analysis using GLM approach.

Parameters

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

  • 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

  • fmriprep_name (str, default=”fMRIPrep”) – Name of the derivative layout of fMRI preprocessed data.

  • fmriprep_layout (bids.layout.layout.BIDSLayout, default=None) – Derivative layout for fMRI preprocessed data. fmriprep_layout is holding primarily preprocessed fMRI images (e.g. motion corrrected, registrated,…) This package is built upon fMRIPrep by Poldrack lab at Stanford University. If None, bids_layout.derivatives[fmriprep_name] will be used.

  • mbmvpa_layout (ids.layout.layout.BIDSLayout, default=None) – Derivative layout for MB-MVPA. The preprocessed voxel features and modeled latent process will be organized within this layout. If None, bids_layout.derivatives[‘MB-MVPA’] will be used.

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

  • 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. #TODO add link for list

  • rois (list of str, default=[]) – Names or ROI when masking by ROI. #TODO add link for list

  • zoom ((int,int,int), default=(1,1,1)) – 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.

  • glm_save_path (str or pathlib.PosixPath, defualt=”.”) – Path for saving outputs.

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

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

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

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

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

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

  • **glm_kwargs (dict) – Dictionary for keywarded arguments for calling first_level_from_bids function.

run_firstlevel()

run first-level glm

run_secondlevel()

run second-level glm

run()

run glm