Merge pull request #1 from carpentries-incubator/gh-pages

fork catchup

AUTHORS

@@ -1 +1,2 @@
-FIXME: list authors' names and email addresses.
+Nikhil Bhagwat [email protected]
+Erin Dickie [email protected]

README.md

@@ -1,44 +1,41 @@
-# FIXME Lesson title
+# Introduction to sMRI Analysis in Python
 
 [![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/)
+[![Slack Status](https://img.shields.io/badge/Slack_Channel-neuroimaging-E01563.svg)](https://swcarpentry.slack.com/messages/CCJBHKCHZ)
 
-**Thanks for contributing to The Carpentries Incubator!**
-This repository provides a blank starting point for lessons to be developed here.
+## Background
 
-A member of the [Carpentries Curriculum Team](https://carpentries.org/team/)
-will work with you to get your lesson listed on the
-[Community Developed Lessons page][community-lessons]
-and make sure you have everything you need to begin developing your new lesson.
+This is one sub-module within the [Neuroimaging cirriculum][neuro_cirriculum]. Visit the link to view all the modules associated with the Neuroimaging Carpentries program.
 
-## What to do next
+**sMRI Analysis in Python** is a programme developed to facilitate reproducibility in structural neuroimaging analyses. Python is emerging as a standard language of data analysis, visualization, and workflow building. More recently, it has rapidly been adopted by the neuroimaging community as a means of developing powerful open-source tools in favour of historically used opaque software such as AFNI, FSL and SPM. In addition, the barrier to entry to Python is low - meaning that you as the user can easily develop your own packages and contribute to the open-source codebase of neuroimaging!
 
-Before you begin developing your new lesson,
-here are a few things we recommend you do:
 
-* [ ] Decide on a title for your new lesson!
-  Once you've chosen a new title, you can set the value for `lesson_title`
-  in [`_config.yml`](_config.yml)
-* [ ] Add the URL to your built lesson pages to the repository description\*
-* [ ] Fill in the fields marked `FIXME` in:
-  * this README
-  * [`_config.yml`](_config.yml)
-* [ ] If you're going to be developing lesson material for the first time
-  according to our design principles,
-  consider reading the [Carpentries Curriculum Development Handbook][cdh]
-* [ ] Consult the [Lesson Example][lesson-example] website to find out more about
-  working with the lesson template
-* [ ] If you are planning to write your lesson in RMarkdown,
-  [create a `main` branch and set this as the default branch in your repository settings][change-default-branch]
-* [ ] Update this README with relevant information about your lesson
-  and delete this section
+***
 
+The **sMRI Analysis in Python** is a workshop series started up via a collaboration between researchers and staff at the Centre for Addiction and Mental Health (Toronto, ON), the University of Western Ontario (London, Ontario), and McGill University (Montreal, Quebec).
 
-\* To set the URL on GitHub, click the gear wheel button next to **About**
-on the right of the repository landing page.
-The lesson URL structure is **https://carpentries-incubator.github.io/<repository-slug\>**:
-a repository at https://github.com/carpentries-incubator/new-lesson/ will have pages at
-the lesson URL https://carpentries-incubator.github.io/new-lesson/.
+***
 
+## About the lesson
+
+This lesson covers a typrical sMRI imaging pipeline by introducing 1) image modalities, 2) image preprocessing, 3) phoenotype quantification, and 4) statistical analyses.  
+
+### Episodes
+
+| Time | Episode | Question(s) Answered |
+| ---  | ---     | ---                  |
+||Setup|Download files required for the lesson|
+| 00:00 | 0. Course Overview and Prereqs | What is a structural MR imaging pipeline? |
+| 00:30 | 1. sMRI modalities | How is MR image acquired? What anatomical features do different modalities capture?  |
+| 01:00 | 2. sMRI preprocessing (Part 1: image clean-up) | How do we clean-up MR images and extract brains? |
+| 01:30 | 3. sMRI preprocessing (Part 2: image registration) | What are "templates", "spaces", "atlases"? What is spatial normalization? |
+| 02:00 | 4. sMRI quantification | How do we delineate brain anatomy and quantify phenotypes? |
+| 02:30 | 5. sMRI quality-control | How do we identify image preprocessing failures? |
+| 03:00 | 6. Statistical analysis (Part 1: ROIs) | How to look at group differences in regional anatomical features? |
+| 03:30 | 7. Statistical analysis (Part 2: voxels) | How to look at group differences at voxel-level features? |
+| 04:00 | 8. Reproducibility considerations | How sensitive are the findings to your MR pipeline parameters? |
+| 04:30 | Finish | |
+
 
 ## Contributing
 
@@ -49,21 +46,19 @@ We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTR
 the [more detailed guidelines][lesson-example] on proper formatting, ways to render the lesson locally, and even
 how to write new episodes.
 
-Please see the current list of [issues][FIXME] for ideas for contributing to this
+Please see the current list of [issues](https://github.com/carpentries-incubator/SDC-BIDS-sMRI/issues) for ideas for contributing to this
 repository. For making your contribution, we use the GitHub flow, which is
 nicely explained in the chapter [Contributing to a Project](http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro Git
 by Scott Chacon.
-Look for the tag ![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the maintainers will welcome a pull request fixing this issue.
+Look for the tag ![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the mantainers will welcome a pull request fixing this issue.
 
 
 ## Maintainer(s)
 
-Current maintainers of this lesson are
-
-* FIXME
-* FIXME
-* FIXME
-
+* [Nikhil Bhagwat][nikhil_bhagwat]
+* [Erin Dickie][erin_dickie]
+* [Michael Dayan][Michael_Dayan]
+* [Swapna Premasiri][Swapna_Premasiri]
 
 ## Authors
 
@@ -73,7 +68,9 @@ A list of contributors to the lesson can be found in [AUTHORS](AUTHORS)
 
 To cite this lesson, please consult with [CITATION](CITATION)
 
-[cdh]: https://cdh.carpentries.org
-[change-default-branch]: https://docs.github.com/en/github/administering-a-repository/changing-the-default-branch
-[community-lessons]: https://carpentries.org/community-lessons
 [lesson-example]: https://carpentries.github.io/lesson-example
+[nikhil_bhagwat]: https://github.com/nikhil153
+[erin_dickie]: https://github.com/edickie
+[Michael_Dayan]: https://github.com/neurorepro
+[Swapna_Premasiri]: https://github.com/devdinie
+[neuro_cirriculum]: https://carpentries.org/community-lessons/#neuroimaging

episodes/00-Course_Overview.md

@@ -0,0 +1,42 @@
+---
+title: "Course Overview"
+teaching: 30
+exercises: 0
+questions:
+- "How are structural MR imaging analyses performed?"
+objectives:
+- "Overview of various (pre)processing tasks involved in a sMRI pipeline and subsequent statistical analyses"
+keypoints:
+- "sMRI preprocessing is a starting point to gain insight into brain anatomy and its variations"
+---
+
+## You Are Here!
+![course_flow](../fig/episode_0/Course_flow_0.png)
+
+Welcome to the **Structural Neuroimaging Analysis in Python** workshop! The primary goals of this workshop are:
+
+1. Understand basics of strcutural MR image acquisition
+2. Familiarize with structural MR image (pre)processing pipeline
+3. Perform and visualize group-level neuroanatomical analyses
+
+## The Central Objective
+
+This workshop is designed to teach you the basics of handling structural MR images in Python and familiarize you with common image processing tasks in an sMRI processing pipeline part of typical neuroanatomical analyses within case-control studies. 
+
+All of this may sound complicated, but we'll explain things step-by-step in depth with practical examples as the course goes along.
+
+## Topics Covered
+
+1. sMRI Modalities 
+2. sMRI Preprocessing (Part 1: image clean-up)
+3. sMRI Preprocessing (Part 2: spatial normalization)
+4. sMRI Quantification
+5. sMRI Quality-Control
+6. Statistical Analyses (Part 1: ROIs)
+7. Statistical Analyses (Part 2: voxels)
+8. Reproducibility Considerations 
+
+In the next section we'll begin with looking at commonly used sMRI modalities in neuroanatomical studies!
+
+{% include links.md %}
+

episodes/01-Image_Modalities.md

@@ -0,0 +1,67 @@
+---
+title: "Introduction to structural MR image modalities"
+teaching: 20
+exercises: 10
+questions:
+- "How is structural MR image acquired?"
+- "What anatomical features do different modalities capture?"
+objectives:
+- "Visualize and understand differnces in T1,T2,PD/FLAIR weighted images."
+keypoints:
+- "Different acquisition techniques will offer better quantification of specific brain tissues"
+---
+## You Are Here!
+![course_flow](../fig/episode_1/Course_flow_1.png)
+
+
+## Image acquisition
+1. The acquition starts with application of strong magnetic field B<sub>0</sub> (e.g. 1.5 or 3.0 Tesla > 10000x earth's magnetic field) which forces the hydrogen nuclei of the abundant water molecules in soft tissues in the body to align with the field. You can think of hydrogen nuclei as tiny magnets of their own. 
+2. Then the scanner applies a RF pulse which tilts these nuclei from their alighment along B<sub>0</sub> and then _precess_ back to the alignment. The _precessing_ nuclei emit a signal, which is registered by the receiver coils in the scanner. 
+3. This signal has two components: 1) _Longitudinal_ (z-axis along the scanner's magnetic field) 2) _Transverse_ (xy-plane orthogonal to the scanner's magnetic field). 
+4. Initially the longitudinal signal is weak as most nuclei are tilted away from the z-axis. However this signal grows as nuclei realign. The _time constant_ that dictates the speed of re-alignment is denoted by _T1_. 
+5. Initially the transverse signal is strong as most nuclei are in phase _coherence_. The signal decays as the nuclei dephase as they realign. This decay is denoted by the _T2 time constant_. 
+7. The tissue specific differences in T1 and T2 relaxation times is what enables us to _see_ anatomy from image contrast. The final image contrast depends on when you _listen_ to the signal (design parameter: echo time (TE)) and how fast you repeat the _tilt-relax_ process i.e. RF pulse freuqency (design parameter: repetition time (TR)). 
+
+
+### T1 and T2 relaxation
+Here we see signal from two different tissues as the nuclei are tilted and realigned. 
+![MR_relax](https://user-images.githubusercontent.com/7978607/112332334-08750c80-8c90-11eb-90fc-33956c037a1c.gif)
+
+### T1w, T2w, and PD acquisition
+
+|                | TE short      | TE ~ T2 of tissue of interest|
+| :-------------: | :----------: | :-----------: |
+| **TR ~ T1 of tissue of interest**  |   T1w | - |
+| **TR long**  | Proton Density (PD) | T2w |
+
+_Note_: More recently, the FLAIR (Fluid Attenuated Inversion Recovery) sequence has replaced the PD image. FLAIR images are T2-weighted with the CSF signal suppressed.
+
+### T1 and T2 relaxation times for various tissues
+
+|                | T1 (ms)      | T2 (ms)     |
+| :-------------: | :----------: | :-----------: |
+|  Bones | 500   | 50    |
+|  CSF | 4000   | 500    |
+|  Grey Matter | 1300   | 110    |
+|  White Matter   | 800 | 80 |
+
+### T1w, T2w image contrasts
+
+|        T1w        | T2w |
+| :-------------: | :-----------: |
+| ![T1](../fig/episode_1/T1.gif) | ![T2](../fig/episode_1/T2.gif) |
+
+
+### Applications per modality
+
+|        Modality    | Contrast Characteristics  | Use Cases     |
+| :-------------: | :-----------: | :-----------: |
+|  T1w | Cerebrospinal fluid is dark  | Quantifying anatomy _e.g. measure structrual volumes_  |
+|  T2w | CSF is light, but white matter is darker than with T1  | Identify pathologies related to lesions and tumors |
+|  PD  | CSF is bright. Gray matter is brighter than white matter | Identify demyelination|
+|  FLAIR  | Similar to T2 with the CSF signal suppressed| Identify demyelination |
+
+**Note: In this lesson, we have only talked about image contrast which is most relevent to sMRI image pipelines. The details of spatial encoding and k-space transforms are out of the scope.**
+
+{% include links.md %}
+

episodes/02-Image_Preproc_Part1.md

@@ -0,0 +1,53 @@
+---
+title: "Image preprocessing with smriprep (Part 1: image clean-up)"
+teaching: 20
+exercises: 10
+questions:
+- "What are the sources of noise and artifacts in MR images?"
+- "How do we extract/mask the brain?"
+objectives:
+- "Visualize bias fields and motion artifacts"
+- "Generate brain masks"
+keypoints:
+- "Presence of artifacts can lead to flawed analsis and incorrect findings"
+---
+## You Are Here!
+![course_flow](../fig/episode_2/Course_flow_2.png)
+
+## Image Clean-ups
+### Intensity normalization (a.k.a bias field correction; a.k.a. intensity inhomogeneity correction)
+
+- The bias field is a low-frequency spatially varying MRI artifact resulting from spatial inhomogeneity of the magnetic field,
+variations in the sensitivity of the reception coil, and the interaction between the magnetic field and the human body. 
+- It causes a smooth signal intensity variation within tissue of the same physical properties. 
+- The bias field is dependent on the strength of the magnetic field. If it is not corrected for 1.5T or higher MR scanners, it can considerably affect downstram analyses. 
+- Commonly used tools
+    - [ANTs N4 bias correction](https://pubmed.ncbi.nlm.nih.gov/20378467/) (See figure below)
+    - [FSL FAST](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FAST) (_Note:FSL FAST is a multi-purpose segmentation tool that includes the bias field correction._)
+
+- ANTs N4 correction
+- ![N4_bias](../fig/episode_2/N4_bias.jpeg)
+
+- Impact of correction (_source: [Despotović et al.](https://www.hindawi.com/journals/cmmm/2015/450341/)_)
+- ![bias_correction](../fig/episode_2/Despotovic_bias_correction.png)
+
+
+### Brain extraction (a.k.a skull-stripping)
+- Image contrasts from nonbrain tissues such as fat, skull, or neck can cause issues with downstream analyses starting with brain tissue segmentation.
+- The brain extraction generates a mask that identifies brain voxels comprising grey-matter (GM), white-matter(WM), and Cerebrospinal fluid (CSF) of
+the cerebral cortex and subcortical structures, including the brain stem and cerebellum. 
+- The scalp, dura matter, fat, skin, muscles, eyes, and bones are classified as nonbrain voxels.
+
+- Commonly used tools
+    - [antsBrainExtraction](https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.ants.html#brainextraction)
+    - [FSL brain extraction tool (BET)](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BET)
+
+- ANTs Brain Extraction
+- ![ANTs_brain_extract](../fig/episode_2/brainextraction_t1.jpg)
+
+- FSL BET 
+- ![FSL_brain_extract](../fig/episode_2/bet2_eg_small.png)
+
+
+{% include links.md %}
+