Skip to content

Latest commit

 

History

History
169 lines (145 loc) · 9.98 KB

README.md

File metadata and controls

169 lines (145 loc) · 9.98 KB

PyMVPA BIDS-App

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

DOI

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 (/bids_dataset/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 (/bids_dataset/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:

from nilearn.image import resample_to_img
import nibabel as nib

Next, it's time to load your source (mask) and target (functional) images:

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 PARTICIPANT_ID [PARTICIPANT_ID ...]] [-s SESSION]
              [--searchlight [SEARCHLIGHT]] [-t TASK]
              [-c CONDITIONS_TO_CLASSIFY [CONDITIONS_TO_CLASSIFY ...]]
              [--noinfolabel [NOINFOLABEL]] [--poly_detrend [POLY_DETREND]]
              [--tzscore] [--bzscore] [-i] [-f FEATURE_SELECT]
              [--cvtype CVTYPE] [--lss] [--rsa] [--surf]
              [--space [{fsnative,fsaverage}]] [--hemi [{l,r}]] [--mask MASK]
              [--dist [{correlation,euclidean,mahalanobis}]] [--nproc [NPROC]]
              [--skip_bids_validator] [-v]
              bids_dir output_dir {participant_prep,participant_test}

PyMVPA BIDS-App

positional arguments:
  bids_dir              The input directory with dataset formatted according
                        to BIDS standard.
  output_dir            The directory that will store outputs.
  {participant_prep,participant_test}
                        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 PARTICIPANT_ID [PARTICIPANT_ID ...], --participant_id PARTICIPANT_ID [PARTICIPANT_ID ...]
                        Subjects (specified by ID) that will be analyzed. The
                        ID corresponds to sub-<participant_id> 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
                        participant_prep and participant_test analysis levels.
  -c CONDITIONS_TO_CLASSIFY [CONDITIONS_TO_CLASSIFY ...], --conditions_to_classify CONDITIONS_TO_CLASSIFY [CONDITIONS_TO_CLASSIFY ...]
                        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
                        events2sample_attr. (default: 'rest')
  --poly_detrend [POLY_DETREND]
                        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, --indiv_trials    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 FEATURE_SELECT, --feature_select FEATURE_SELECT
                        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).
  --skip_bids_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:

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:

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.