README.md

# Level 1

The `level1.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 for CIFTI processed using ciftify or the HCP BIDS app.

## Usage
```
usage: level1.py [-h] [--session SESSION] (--mode_ciftify | --mode_hcp)
                 [--n_cpus N_CPUS] [--fwhm FWHM] [--hpfilter HPFILTER]
                 [--drop_trs DROP_TRS] [--mesh MESH] [--resolution RESOLUTION]
                 [--motion6] [--motion6dt]
                 [--fmriprep_confounds [FMRIPREP_CONFOUNDS [FMRIPREP_CONFOUNDS ...]]]
                 [--ciftify_desc CIFTIFY_DESC]
                 bids_dir output_dir tcontrast_file participant task run

First level models for CIFTI data

positional arguments:
  bids_dir              Full path to the directory with the input dataset
                        formatted according to the BIDS standard.
  output_dir            Full path to the base directory containing
                        preprocessed data.This directory will be modified.For
                        ciftify data, this is directory containing the
                        directories named ciftify and fmriprep.For HCP data,
                        this directory contains the subject level output
                        directories.
  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
  --mode_ciftify, --mode-ciftify
                        Use data processed by ciftify
  --mode_hcp, --mode-hcp
                        Use data processed by the HCP BIDS app
  --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
  --mesh MESH           Mesh resolution
  --resolution RESOLUTION
                        Volume resolution
  --motion6             Include 6 motion regressors as confounds
  --motion6dt           Include the first derivative of the 6 motion
                        regressors as confounds
  --fmriprep_confounds [FMRIPREP_CONFOUNDS [FMRIPREP_CONFOUNDS ...]]
                        Additional fmriprep confound columns to include.
  --ciftify_desc CIFTIFY_DESC
                        ciftify desc value
```

Due to slight differences in HCP and ciftify naming, you must specify `--mode_ciftify` or `--mode_hcp`, depending on which pipeline you used. If your ciftify output folder include a `desc` tag, specify this with the `--ciftify_desc` option.

## 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=3
#SBATCH --mem=4gb
#SBATCH --time=01:00: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/lexdec:/data \
    /scratch/psyc5171/containers/nipype.sif \
    /data/surface_scripts/level1.py \
    --mode-ciftify --n_cpus 3 --fwhm 2 --hpfilter 120 --motion6 \
    /data/bids \
    /data/bids/derivatives/ciftify \
    /data/contrasts.tsv \
    $SUBJECT $TASK $RUN

```

Job submission for sub-ta6520\_task-homophone10\_run-01:

```
sbatch sbatch_level1.sh ta6520 homophone10 01
```

# Level 2

The `level2.sh` script will combine results across runs using a fixed effects analysis.

To run the script, supply the base output directory, subject ID (without `sub-`) and task to process, e.g.


```shell
level2.sh /data/bids/derivatives/ciftify ta6520 homophone10
```