Fall 2020 Pygers Workshop

Organized by: Lizzie McDevitt, Sam Nastase, Paula Brooks

Contact info: emcdevitt8287@gmail.com, sam.nastase@gmail.com, paulapbrooks@gmail.com

Building a reproducible neuroimaging pipeline: From acquisition to analysis

This is a weekly hands-on workshop series designed to introduce you to the tools and best practices foundational to building a reproducible neuroimaging pipeline. This workshop is open to researchers of all levels, no prior experience necessary! You do not need your own data as the demos will use our sample dataset, but we certainly hope you will apply the framework covered here to your own data. During the workshop, we will be demo-ing on our (Mac OS) computers, and we strongly recommend you try to follow along on your own computer. Each week’s lesson will build off of the last.

The tentative workshop schedule is included below, but please be aware that dates may change if we end up needing more than one week to cover a given set of topics. The workshop will take place via Zoom on Thursdays from 10-11am EST.

Please subscribe to the pygers listserv to get email announcements and Zoom links!

  1. Send an email to listserv@princeton.edu from the email you want to be subscribed.

  2. In the body of the email, type SUB pygers

  3. Make sure there is no subject or any other text in the body and then send the email. You should receive a response.

  4. If the above method does not work, please email sam.nastase@gmail.com to be added manually.

Workshop Overview

Week 1: Intro to high performance computing at PNI and Terminal basics

Week 1 Notes

Week 1 Recording

Date: Thursday, October 8 10-11am EST

Topics Covered:

  • server/cluster jargon

  • how to use PNI’s file server and cluster

  • bash commands

  • using vim

  • setting up aliases in .bash_profile and .bashrc

  • setting up a conda environment and installing packages (we didn’t get to this in week 1; we will start with this at the beginning of week 2)

Preparation (try to complete these agenda items prior to the Thursday workshop):

  1. If you are at PNI, make sure you have access to the PNI server (i.e., request a PNI NetID). After requesting your PNI NetID, follow the provided instructions to login and setup your password.

  2. If you do not have PNI server access, figure out where you want your working directory for the workshop to live. This can be on your local machine, or if you have access to a server at your home institution that you normally use for data processing/analysis, you may want to work there. Either way, name your working directory pygers_workshop. Follow the instructions to download the sample data and save it in your pygers_workshop working directory. Note, if you have PNI server access you do not need to download the sample data ahead of time.

  3. If you do not have PNI server access, download the new_study_template folder available on Google Drive. Save it in the same pygers_workshop working directory as the downloaded sample data. Rename the folder new_study_template to sample_study.

  4. If you are using a Windows machine, you should consider installing a Windows subsystem for Linux. When choosing your Linux distribution, choose the newest version of Ubuntu LTS.

  5. If you are using a Mac: If you do not already have it, download and install XQuartz on your local machine. After installing, you will need to log out of your computer’s user account and then log back in (or just restart your computer). Then open a Terminal and type:

defaults write org.macosforge.xquartz.X11 enable_iglx -bool true

  1. Everyone: Download and install a text editor on your local machine (recommended: Sublime Text).

Week 2: Using Git and GitHub

Week 2 Notes

Week 2 Recording

Date: Thursday, October 15 10-11am EST

Topics Covered:

  • setting up a conda environment and installing packages

  • initializing Git

  • setting up a GitHub repository

  • using .gitignore

  • general Git workflow, including important Git commands

Preparation:

  1. Sign up for an account on GitHub if you don’t have one already

  2. Background reading: Overview of Git and version control

Week 3: Understanding MRI data formats and standardizing your dataset structure

Week 3 Notes

Week 3 Recording

Date: Thursday, October 22 10-11am EST

Topics Covered:

  • What is BIDS?

  • Using the ReproIn heuristic to setup your program card prior to data acquisition

  • dicom and nifti formats

  • Using HeuDiConv to convert raw data to a BIDS-compliant data structure

  • Using tmux to create persistent server sessions

  • Defacing images using pydeface

Preparation:

  1. The benefits of BIDS. This is Sam’s OHBM TrainTrack presentation (~70 minutes).

  2. Handbook reading: Using tmux to create persistent server sessions

  3. If you do not have PNI server access, install a local version of FSL.

  4. Optional: If you are working on your home institution’s server: If Singularity is available on your server, you can use it to build your own heudiconv Singularity image that can live on your institution’s server.

singularity pull docker://nipy/heudiconv

Week 4: Preparing your data to run BIDS apps (MRIQC and fMRIPrep)

Week 4 Notes

Week 4 Recording

Date: Thursday, October 29 10-11am EST

Topics Covered:

  • Exploring the outputs of HeuDiConv

  • Data visualization using FSLeyes and AFNI

  • Using the BIDS Validator

Preparation:

  1. Everybody, even if you have been working on the PNI server: We recommend that you have a local version of FSLeyes available. This is because remotely accessing the module on the PNI server to view images is quite slow and clunky. It is much faster to use a local version of FSLeyes. You can either a) install a local version of FSL, which includes FSLeyes (if you already have a local FSL installed after last week you are good to go!) OR b) install conda on your local machine (you can follow the instructions for Local installation in our Week 2 Notes) and create a new local conda environment. After creating your new conda environment, you can install the FSLeyes package (you don’t need to install the git, numpy, pandas, jupyter packages from Week 2 unless you want to).

conda install -c conda-forge fsleyes

Week 5: Running MRIQC and fMRIPrep

Week 5 Notes

Week 5 Recording

Date: Thursday, November 5 10-11am EST

Topics Covered:

  • Using SLURM to schedule jobs on the PNI server

  • Running MRIQC for data quality control

  • Running fMRIPrep for data preprocessing

Preparation:

  1. Everybody: Make sure you are caught up thru week 4!

  2. Everybody: Download a FreeSurfer license key and save it in your pygers_workshop/sample_study/code/preprocessing directory. If you have previously downloaded a FreeSurfer license, you can simply save a copy of the same license file in this location.

  3. Everybody, Optional: If you want to get a head start on week 5 content, follow the instructions in the section titled, “Preparing to run MRIQC and fMRIPrep” in the Week 5 notes to (i) setup your work directory on scratch and (ii) edit the following scripts: globals.sh, deface_template.sh, run_mriqc.sh, run_mriqc_group.sh, run_fmriprep.sh.

  4. Optional: If you are working on a non-PNI server: If Singularity is available on your server, you can use it to build your own MRIQC and fMRIPrep Singularity images that can live on your institution’s server.

singularity build mriqc-0.15.1.simg docker://poldracklab/mriqc:0.15.1

singularity build fmriprep-v20.2.0.simg docker://poldracklab/fmriprep:20.2.0

  1. Optional: If you want to run MRIQC and fMRIPrep locally, it is recommended you use Docker. MRIQC Docker instruction are found here. fMRIPrep Docker instructions are found here.

Week 6: Exploring MRIQC and fMRIPrep outputs

Week 6 Recording

Date: Thursday, November 12 10-11am EST

Topics Covered:

  • What are the different quality control metrics?

  • Understanding different output spaces

Preparation:

  1. Make sure you are caught up thru week 5!

  2. Check out the documentation about MRIQC outputs!

  3. Check out the documentation about fMRIPrep outputs!

Week 7: Version controlling your data

Week 7 Recording

Date: Thursday, November 19 10-11am EST

Topics Covered:

Preparation:

  1. Check out the DataLad Handbook!