Lesson plan discussion

[josephmje]

Below is a proposed lesson plan summarized from previous meeting minutes. Some of this content currently exist in slide format and some have been converted to the carpentries' lesson formatting (seen in the episodes/ and code/) folders. We welcome discussion to help round out the material and ensure it will work well for our intended audience.

Some excellent content has also already been developed for ReproNim, Neurohackademy, BrainHack School, etc. It might also be worth reaching out to those instructors to integrate content.

Part 1: Introduction to an MR Imaging Dataset

The instructor will browse a project in the openneuro.org website (including the integrated papaya viewer) and may download the data locally (in prep for further sections) using the web interface.
Downloading from openneuro using datalad or awscli
Summarizing available data with pybids
Loading data into python using nibabel/nilearn and viewing its dimensions
viewing (raw) files using nilearn plotting tools

General concepts to Explore in Part One

• What are “subjects” and “sessions”
• What’s an ”_anat” file?
• What a ”_func” file? What additional info do other’s need to be able to work with it?
• What a ”_dwi” file? What additional info do other’s need to be able to work with it?

Part 2 "Converting" to BIDS

This is mostly a pointer to the BIDS starter kit. Show BIDS conversion using multiple methods

• BIDS validator discussion (important checkpoint)
• from DICOM format, use dcm2niix to convert - and then rename as needed
  -i.e. BIDS starter kit tutorial 1.
• from converted NIFTI's
• redirect students to other programmatic methods. (i.e. heudiconv)

Part 3: Pre-preprocessing

• BIDS apps
  • define a BIDS app
  • why BIDS apps
  • the BIDS app arguments ( )
  • the popular ones (and where they are stored?)
    • fmriprep
    • mriqc
    • ciftify
    • freesurfer
    • HCPPipeline
    • CPAC
• BIDS apps are containers
  • what's a container
  • Docker vs singularity
    • we write Docker spec
    • we run singularity containers

Part 4: Using Docker/Singularity Containers and running pipelines on a HPC

• docker
• singularity run
  • binding in general
  • binding the data
  • binding home
  • binding the $BBUFFER as your workdir
• singularity shell
• singularity exec
• building a container from Dockerhub
• building your own container with NeuroDocker

[jerdra]

good overview Michael!

Should we structure the lesson plan in the style of data carpentry? I.e for each lesson block:

1. The proposed episode title
2. The questions that are to be answered within the episode
3. The key take-aways from the episode
4. An additional block for sub-sections we plan to include (i.e affine, headers, viewing etc...)

I think formalizing it this way might be easier to get into the gritty details for discussion.

Some additional thoughts for potentially optional content:

1. Since IntroMRI is the base point for all MR branches (fMRI, dMRI, and eventually sMRI), should we get into discussion about spaces and registrations? A lot of neuroimaging people talk about these concepts and its jargon to newcomers. In addition this can highlight components that we typically take for granted. Perhaps this can be included w/the exploration of NIFTI headers?

2. Data quality assessment? I.e how do you know if a scan is good or usable? In addition, a bit of information about the metadata files (JSON sidecars) and typical pitfalls might be useful. The BIDS-validator could help with this.

   • For example when downloading large open neuro datasets (ABCD) you cannot assume that the data is perfect. In many cases you'll need to do some dirty data cleaning (i.e making sure files are what they say they are etc..)

3. Introduction to common sequences that you might come across and what they mean? This can pertain to the above item, where sometimes images are mis-named (i.e a T2 is called T1 in a dataset, how do you visually verify this, etc.). BIDS validator might catch this, in which case might be good to show a bad dataset example?

4. Some sequences have caveats that are important for pre-processing decisions. I.e fast multi-band doesn't rely heavily on slice-timing correction, whereas slow single-band does. (This one might be too deep into the woods for an intro course)

[josephmje]

Thanks for your comments @jerdra. Good point! Structuring the lesson plan into the carpentries format might also help us determine which aspects are out of scope. Let me think more about this and I'll update my original post.

1. Since IntroMRI is the base point for all MR branches (fMRI, dMRI, and eventually sMRI),
   should we get into discussion about spaces and registrations? A lot of neuroimaging people
   talk about these concepts and its jargon to newcomers. In addition this can highlight components
   that we typically take for granted. Perhaps this can be included w/the exploration of NIFTI headers?

Yes! I like this idea. I would leave more detailed discussion of spaces to the upstream modality lessons but it would be good to introduce the concept.

2. Data quality assessment? I.e how do you know if a scan is good or usable? In addition, a bit
   of information about the metadata files (JSON sidecars) and typical pitfalls might be useful.
   The BIDS-validator could help with this.

I would leave QC to the upstream lessons (same to doing data cleaning on open datasets), mostly because the types things that you might need to look out for are going to be slightly different. But talking about the metadata files and how the BIDS-validator can catch certain discrepancies is great! All datasets uploaded to OpenNeuro also go through automated BIDS validation.

3. Introduction to common sequences that you might come across and what they mean?
   This can pertain to the above item, where sometimes images are mis-named (i.e a T2 is called T1
   in a dataset, how do you visually verify this, etc.). BIDS validator might catch this, in which case
   might be good to show a bad dataset example?

Yes, I think this usually comes up naturally when we introduce the different modalities. But we haven't really talked about the MR physics and how that leads to the resulting image. Maybe it would be good to include that and how certain important parameters are described in the json? I'm inclined to not introduce too many caveats in the intro lesson.

4. Some sequences have caveats that are important for pre-processing decisions. I.e fast
   multi-band doesn't rely heavily on slice-timing correction, whereas slow single-band does.
   (This one might be too deep into the woods for an intro course)

I agree, this sounds too out of scope for the intro.

[jerdra]

Sounds like qc practices in general should be an optional/self-guided episode in the respective upstream repos! Maybe after all the base content is established