PyMVPA BIDS-App

This pipeline is developed at Stanford University and University of California, Irvine, for open-source software distribution.

Citation

Please cite Torabian et al. (2023) [paper]

Description

This pipeline takes fMRI data and generates ROI-based & searchlight MultiVariate Pattern Analysis (MVPA) results (including visualized patterns), and also runs Representational Similarity Analysis (RSA) using functionality from PyMVPA. Before running PyMVPA BIDS-App, data needs to be pre-processed using fMRIPrep.

The following describes two analysis levels of this app: - Participant Prep: For each subject, takes pre-processed functional images from fMRIPrep, and concatenates them into a single NIfTI file that will be placed under the subject folder in the output directory (/bidsdataset/derivatives/pymvpa/sub-ID). It also creates a text file next to each NIfTI for each subject which contains a list of numbers showing the number of time points in each run.

In addition, an empty "masks" folder under the output folder (/bidsdataset/derivatives/pymvpa/masks) is created at this step which should be filled with NIfTI ROIs before moving to the next step. The "Generating Masks in FSL" section below demonstrates how to generate such masks.

- Participant Test: For each subject, iterates through all the ROIs inside the "masks" folder and performs SVM classification, or generates Representational Dissimilarity Matrices (RDM). This step reports results through HTML outputs for each subject, together with visualized patterns in the NIfTI format.

Generating Masks in FSL

Here is one approach to creating masks in FSL. If the resolution of your masks doesn't match your functional images, you might need to reslice the masks. Here is one way to do this:

In Python, import the following: python from nilearn.image import resample_to_img import nibabel as nib

Next, it's time to load your source (mask) and target (functional) images: python src_img = nib.load('mask_name.nii') trgt_img = nib.load('sub-1_task-tsk_run-01_bold_space-MNI152NLin2009cAsym_preproc.nii') # using the first run here output = resample_to_img(src_img, trgt_img, interpolation='nearest') output.to_filename('mask_name.nii')

More on MVPA

Usually at least 8 runs is needed for MVPA analysis. You may also have two really long runs with long rest periods in the middle so that each run can be cut into pieces. The important point is that you need to make sure the chunks remain independent, or analyze data in a way to make them independent!

Documentation

For more information on PyMVPA, please visit http://www.pymvpa.org/, or look into the "Usage" section below.

How to report errors

For issues or questions, please post to the PyMVPA mailing list (http://www.pymvpa.org/support.html), the BIDS mailing list (https://groups.google.com/forum/#!forum/bids-discussion), or NeuroStars (https://neurostars.org/) with pymvpa tag

Usage

The following shows the command line arguments of PyMVPA BIDS-App:

``` usage: run.py [-h] [-p PARTICIPANTID [PARTICIPANTID ...]] [-s SESSION] [--searchlight [SEARCHLIGHT]] [-t TASK] [-c CONDITIONSTOCLASSIFY [CONDITIONSTOCLASSIFY ...]] [--noinfolabel [NOINFOLABEL]] [--polydetrend [POLYDETREND]] [--tzscore] [--bzscore] [-i] [-f FEATURESELECT] [--cvtype CVTYPE] [--lss] [--rsa] [--surf] [--space [{fsnative,fsaverage}]] [--hemi [{l,r}]] [--mask MASK] [--dist [{correlation,euclidean,mahalanobis}]] [--nproc [NPROC]] [--skipbidsvalidator] [-v] bidsdir outputdir {participantprep,participant_test}

PyMVPA BIDS-App

positional arguments: bidsdir The input directory with dataset formatted according to BIDS standard. outputdir The directory that will store outputs. {participantprep,participanttest} Level of the analysis that will be performed. Multiple analyses can run independently in parallel.

optional arguments: -h, --help show this help message and exit -p PARTICIPANTID [PARTICIPANTID ...], --participantid PARTICIPANTID [PARTICIPANTID ...] Subjects (specified by ID) that will be analyzed. The ID corresponds to sub-<participantid> from BIDS specification. If specific IDs are not provided, all subjects will be analyzed. Multiple subjects can be specified by a space separated list. -s SESSION, --session SESSION Session ID for multi-session datasets. --searchlight [SEARCHLIGHT] Performs searchlight analysis with s being the radius of spheres/discs in volumetric/surface mode. If this flag is not enabled, ROI-based analysis will run. (default: 5.0) -t TASK, --task TASK Task to analyze. This has to be specified for both participantprep and participanttest analysis levels. -c CONDITIONSTOCLASSIFY [CONDITIONSTOCLASSIFY ...], --conditionstoclassify CONDITIONSTOCLASSIFY [CONDITIONSTOCLASSIFY ...] Conditions to classify. --noinfolabel [NOINFOLABEL] When building a sample attribute array from an event list, this will be assigned to all samples with no label. For more information, check PyMVPA's events2sampleattr. (default: 'rest') --polydetrend [POLYDETREND] Order of Legendre polynomial to remove from the data. This will remove every polynomial up to and including the provided value. If this parameter is not provided no detrending will be performed. (default: 1) --tzscore Feature-wise, run-wise z-scoring of time-series. Scales all features into approximately the same range, and removes their mean. If this parameter is not provided no normalization will be performed. --bzscore Feature-wise z-scoring of GLM beta estimates across all runs. -i, --indivtrials When (HRF) modeling the time-series, enabling this flag will estimate betas per individual trials, rather than per condition per run. This provides more but noisier estimates. A trade off between the number of training samples and noise reduction should be made by the user. -f FEATURESELECT, --featureselect FEATURESELECT Uses ANOVA to select features with highest F-scores. Will perform FixedNElementTailSelector if f > 1, and FractionTailSelector if f < 1. If this parameter is not provided no feature selection will be performed. --cvtype CVTYPE When running cross-validation on a dataset with n runs, with cvtype = 1 (default), n partition sets will be generated, where each run is sequentially left out to form one partition, with all other runs forming the other partition together. If cvtype > 1, all possible combinations of cvtype number of runs are left out. --lss Enabling this parameter will run GLM in a Least Squares Single (LSS) fashion. Default is Ordinary Least Squares (OLS). --rsa Enabling this parameter will run Representational Similarity Analysis. Default is classification. --surf Enabling this parameter will run analyses on surface. Default is volumetric. --space [{fsnative,fsaverage}] Surface space of analysis. Options are fsnative or fsaverage. --hemi [{l,r}] Hemisphere of analysis. Need to specify for surface. Options are l (left) or r (right). --mask MASK NIfTI mask used for both ROI-based analysis and searchlight. --dist [{correlation,euclidean,mahalanobis}] Distance metric to use for Representational Dissimilarity Matrices (RDM). Choices are correlation (default), euclidean, and mahalanobis. --nproc [NPROC] Number of CPUs to use (default: 8). --skipbids_validator Skipping BIDS validation -v, --version show program's version number and exit ```

The following shows how to run the app in prep mode for task "objectviewing" of participants 1 & 2: bash docker run -i --rm \ -v [path to BIDS root]:/bids_dataset:ro \ -v [path to BIDS root/derivatives/pymvpa]:/outputs \ bids/pymvpa \ /bids_dataset /outputs participant_prep -p 1 2 -t objectviewing

And, here is how to run the app in test mode, for the classification of "face"s versus "house"s, with z-scoring of time-series applied. Note that the same output folder as above should be used: bash docker run -i --rm \ -v [path to BIDS root]:/bids_dataset:ro \ -v [path to BIDS root/derivatives/pymvpa]:/outputs \ bids/pymvpa \ /bids_dataset /outputs participant_test -p 1 2 -t objectviewing -c face house --bzscore

Special Considerations

Note that functional runs get concatenated into single NIfTI files for each subject, so be mindful of your memory capacity.