Volumetric Processing

This repository contains sample scripts for doing multilevel analysis of task fMRI data following minimal preprocessing in fmriprep.

The scripts assume the following (container) paths:

• /bids: The BIDS folder for the dataset
• /fmriprep: The fmriprep output directory, containing subject level results.
• /results: The output folder for the statistics

Level 1

The level1_volume.py script is a minimal Nipype workflow to model the hemodynamic response to the task in a single run.

usage: level1_volume.py [-h] [--session SESSION]
                        [--fmriprep_confounds [FMRIPREP_CONFOUNDS [FMRIPREP_CONFOUNDS ...]]]
                        [--n_cpus N_CPUS] [--fwhm FWHM] [--hpfilter HPFILTER]
                        [--drop_trs DROP_TRS] [--motion6] [--motion6dt]
                        [--space SPACE]
                        bids_dir fmriprep_dir output_dir tcontrast_file
                        participant task run

First level models for volumetric fmriprep data

positional arguments:
  bids_dir              Full path to the directory with the input dataset
                        formatted according to the BIDS standard.
  fmriprep_dir          Full path to the fmriprep output directory, containing
                        subject level folders
  output_dir            Full path to the base directory for outputs
  tcontrast_file        Full path to T contrast specification
  participant           Participant label to process
  task                  Task label to process
  run                   Run label to process

optional arguments:
  -h, --help            show this help message and exit
  --session SESSION     Session label to process
  --fmriprep_confounds [FMRIPREP_CONFOUNDS [FMRIPREP_CONFOUNDS ...]]
                        Additional fmriprep confound columns to include.
  --n_cpus N_CPUS, --n-cpus N_CPUS
                        Number of CPUs/cores available to use.
  --fwhm FWHM           Smoothing FWHM in mm
  --hpfilter HPFILTER   Highpass filter length in seconds
  --drop_trs DROP_TRS   Number of initial TRs to drop
  --motion6             Include 6 motion regressors as confounds
  --motion6dt           Include the first derivative of the 6 motion
                        regressors as confounds
  --space SPACE         fmriprep output space to use

Contrast file

You must provide the path to a file describing the desired contrasts for the tcontrast_file argument.

This file should be tab-delimited with the following structure.

• a header row, with the first column named contrast
• subsequent column names must exactly match possible trial_type values from the BIDS _events.tsv file. Any event types not included will be ignored in the design
• the second and following rows define T contrasts, with the name specified in the contrast column

contrast	condition1	condition2
1-2	1	-1
2	0	1

Example Cluster Use

sbatch_level1.sh:

#!/bin/bash
#SBATCH --mail-type=FAIL 			# Mail events (NONE, BEGIN, END, FAIL, ALL)
#SBATCH --mail-user=First.Last@uconn.edu	# Your email address
#SBATCH --nodes=1					# OpenMP requires a single node
#SBATCH --ntasks=1					# Run a single serial task
#SBATCH --cpus-per-task=1
#SBATCH --mem=2gb
#SBATCH --time=00:15:00				# Time limit hh:mm:ss
#SBATCH -e error_%A_%a.log			# Standard error
#SBATCH -o output_%A_%a.log			# Standard output
#SBATCH --job-name=level1			# Descriptive job name
#SBATCH --partition=serial            # Use a serial partition 24 cores/7days
##### END OF JOB DEFINITION  #####

SUBJECT=$1
TASK=$2
RUN=$3

module load singularity
singularity run --cleanenv \
    --bind /scratch/psyc5171/exercises/rhyme:/data \
    /scratch/psyc5171/containers/nipype.sif \
    /data/volume_scripts/level1_volume.py $SUBJECT $TASK $RUN \
    --n_cpus 1 --fwhm 8 --hpfilter 120 --motion6 \
    /data/bids \
    /data/bids/derivatives/fmriprep \
    /data/results \
    /data/contrasts.tsv \
    $SUBJECT $TASK $RUN

Job submission for sub-85_task-VisRhyme_run-01:

sbatch sbatch_level1.sh 85 VisRhyme 01

Level 2

The level2_volume.sh will combine results across runs using a fixed effects analysis.

To run the script, supply the path to the results directory where the level 1 outputs are, the subject ID (without sub-) and task to process, e.g.

level2_volume.sh /results 01 VisRhyme

Level 3

The level3_volume.sh script will calculate a one sample t-test across level 2 results.

To run the script, supply the result directory and task to process e.g.

level3_volume.sh /results VisRhyme

Level 3 permutation tests

The level3_randomise.sh script will calculate a one sample t-test across level 2 results, using permutation test and TFCE.

To run the script, supply the result directory, task to process, and number of permutations e.g.

level3_volume.sh /results VisRhyme 5000