README.md

# 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](https://nipype.readthedocs.io/en/latest/) 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`: 

```bash
#!/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.


```shell
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.

```shell
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.

```shell
level3_volume.sh /results VisRhyme 5000
```