fMRIPrep Bootcamp | Day 1 :: BIDS Hands-on

name: title
layout: true
class: center
---
layout: false
count: false

.center[
<a href="https://www.nipreps.org/assets/fmriprep-bootcamp-geneva2024/day1-03-bids-hands-on/">
 <img src="images/qr-talk-url.svg" alt="workflow" style="width: 20%" />
 
 https://www.nipreps.org/assets/fmriprep-bootcamp-geneva2024/day1-03-bids-hands-on/
</a>

## BIDS | Hands-on

Chris Markiewicz <<code>markiewicz@stanford.edu</code>>

Oscar Esteban <<code>phd@oscaresteban.es</code>>
]

---
name: newsection
layout: true

.perma-sidebar[

<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0; height: 20px; padding-top: 6px;" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a>
 Day 1 :: BIDS Hands-on

]

---

# Outlook

.right-column3.center[
<a href="https://www.nipreps.org/assets/fmriprep-bootcamp-geneva2024/day1-03-bids-hands-on/">
 <img src="images/qr-talk-url.svg" alt="workflow" style="width: 100%" />
 
 https://www.nipreps.org/assets/fmriprep-bootcamp-geneva2024/day1-03-bids-hands-on/
</a>
]

.left-column3[

.large[

* Explore the bootcamp's dataset

* Compute environments

* Accessing the cluster and creating an environment

* Datalad & PyBIDS

]]

???

---

# Exploring the bootcamp's dataset

.boxed-content[
.center[[https://openneuro.org/datasets/ds005454/versions/1.0.0](https://openneuro.org/datasets/ds005454/versions/1.0.0)]

---

# Understanding ds005454

.left-column2.small[
.pad-left[
 my_dataset/ 
.pad-left[ CHANGES] 
.pad-left[ README] 
.pad-left[ dataset_description.json] 
.pad-left[ participants.json] 
.pad-left[ participants.tsv] 
.pad-left[ scans.json] 
.pad-left[ sub-11] 
.pad-left[.pad-left[ anat/]] 
.pad-left[.pad-left[.pad-left[ sub-11_T2w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_T2w.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-denoised_T1w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-denoised_T1w.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-mp2rage_T1w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-mp2rage_T1w.nii.gz]]] 
.pad-left[.pad-left[ fmap/]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude1.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude1.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude2.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude2.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_phasediff.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_phasediff.nii.gz]]] 
.pad-left[.pad-left[ func/]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_bold.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_bold.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_events.tsv]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-rest_bold.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-rest_bold.nii.gz]]] 
.pad-left[.pad-left[ sub-11_scans.tsv]] 
.pad-left[ sub-14] 
.pad-left[ sub-15] 
]
]

.right-column2.larger[

### Anatomical images

* T1-weighted (T1w) images:

* MP2RAGE scheme
  * Two versions: uniform and denoised

* T2-weighted (T2w) images
]

---

# Understanding ds005454

.left-column2.small[
.pad-left[
 my_dataset/ 
.pad-left[ CHANGES] 
.pad-left[ README] 
.pad-left[ dataset_description.json] 
.pad-left[ participants.json] 
.pad-left[ participants.tsv] 
.pad-left[ scans.json] 
.pad-left[ sub-11] 
.pad-left[.pad-left[ anat/]] 
.pad-left[.pad-left[.pad-left[ sub-11_T2w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_T2w.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-denoised_T1w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-denoised_T1w.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-mp2rage_T1w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-mp2rage_T1w.nii.gz]]] 
.pad-left[.pad-left[ fmap/]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude1.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude1.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude2.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude2.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_phasediff.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_phasediff.nii.gz]]] 
.pad-left[.pad-left[ func/]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_bold.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_bold.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_events.tsv]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-rest_bold.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-rest_bold.nii.gz]]] 
.pad-left[.pad-left[ sub-11_scans.tsv]] 
.pad-left[ sub-14] 
.pad-left[ sub-15] 
]
]

.right-column2.larger[

### Functional images

* Two tasks:
  * Resting state fMRI (`task-rest`)
  * Task fMRI (`task-mixed`)

* Repetition time: 1.5s

* Length ~7 minutes

]

---

# Understanding ds005454

.left-column2.small[
.pad-left[
 my_dataset/ 
.pad-left[ CHANGES] 
.pad-left[ README] 
.pad-left[ dataset_description.json] 
.pad-left[ participants.json] 
.pad-left[ participants.tsv] 
.pad-left[ scans.json] 
.pad-left[ sub-11] 
.pad-left[.pad-left[ anat/]] 
.pad-left[.pad-left[.pad-left[ sub-11_T2w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_T2w.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-denoised_T1w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-denoised_T1w.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-mp2rage_T1w.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_acq-mp2rage_T1w.nii.gz]]] 
.pad-left[.pad-left[ fmap/]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude1.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude1.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude2.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_magnitude2.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_phasediff.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_phasediff.nii.gz]]] 
.pad-left[.pad-left[ func/]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_bold.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_bold.nii.gz]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-mixed_events.tsv]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-rest_bold.json]]] 
.pad-left[.pad-left[.pad-left[ sub-11_task-rest_bold.nii.gz]]] 
.pad-left[.pad-left[ sub-11_scans.tsv]] 
.pad-left[ sub-14] 
.pad-left[ sub-15] 
]
]

.right-column2.larger[

### B0 inhomogeneity maps

.gray-text[... or 'fieldmaps' for short]

* GRE (gradient recalled echo) scheme
* Measures the phase drift between two close echos
  * Two magnitude files
  * One phase-difference map (one echo minus the other)

]

---

# General metadata | `dataset_description.json`

.boxed-content.pad-top[

```JSON
{
  "Acknowledgements": "Provided by Emilie C. Sleight for the fMRIPrep bootcamp",
  "Authors": [
    "Emilie C. Sleight",
    "Oscar Esteban",
    "Frédéric Grouiller"
  ],
  "BIDSVersion": "1.8.0",
  "DatasetDOI": "10.18112/openneuro.ds005454.v1.0.0",
  "HowToAcknowledge": "Cite OpenNeuro's DOI",
  "License": "CC-BY",
  "Name": "fMRIPrep boot camp -- 7T training dataset",
  "ReferencesAndLinks": [
    "https://doi.org/10.18112/openneuro.ds005454.v1.0.0",
    "https://doi.org/10.1038/s41592-018-0235-4"
  ]
}
```
]
---

# General metadata | `participants.tsv`

.boxed-content.pad-top[

```TSV
participant_id  age sex group
sub-17  28  F control
sub-16  33  F control
sub-15  40  F control
sub-14  38  F control
sub-11  27  M control
```
]

---

# General metadata | `task-mixed_events.tsv`

.boxed-content.pad-top[

```TSV
onset duration  trial_type
21.2  20.0  motor
44.5  20.0  music
66.9  20.0  visual
89.7  20.0  motor
113.0 20.0  music
135.4 20.0  visual
158.2 20.0  music
180.6 20.0  visual
203.4 20.0  motor
226.7 20.0  visual
249.5 20.0  motor
272.8 20.0  music
295.2 20.0  visual
318.0 20.0  motor
341.3 20.0  music
363.6 20.0  visual
386.4 20.0  music
408.8 20.0  motor
```
]

---

.boxed-content[
.large.center[
# Let's play with these data
]
.large.center.gray-text[Who knows about Conda?]
]

---

# Execution environment

.boxed-content[
.no-bullet[
* .large[ One way or another, we will need to *install stuff*.]
 * .larger[Easy on a computer you administer], but
 * .larger[hard in multi-tenant systems such as HPC.]

### What are the options?

* .larger[ Good old days: modules (`module load FreeSurfer`)]
 * Requires intervention from the cluster admin for default modules
 * Users can create modules, but installation is not trivial nor portable

* .larger[ Conda environments: handle beyond *Python*]
 * Easy to deploy, very *Python*-friendly
 * Replicating environments is possible, but requires 'some' effort

* .larger[ Containers (Docker, Apptainer)]
 * Conceived to resolve the problem
 * Sometimes images are hefty
]
]

---

.boxed-content[
.large.center[
# Hack!
]
.larger.center.gray-text[Pause to install Conda & Docker and check access to the cluster]
]

---

# Logging in into a cluster and setting up conda

.boxed-content.pad-top[
<div class="asciicast" id="636539" data-src="images/setting-conda.cast"></div>
]

---

.boxed-content[
.center[
https://www.datalad.org
<iframe src="https://www.datalad.org" width="100%" height="600px" style="border: 0" />
]
]

---

# First interaction with datalad

.boxed-content.pad-top[
<div class="asciicast" id="636540" data-src="images/setting-datalad.cast"></div>
]

---

.boxed-content[
.center[
https://handbook.datalad.org/en/latest/
<iframe src="https://handbook.datalad.org/en/latest/" width="100%" height="600px" style="border: 0" />
]
]

---

.boxed-content[
.large.center[
# Git?
]
.larger.center.gray-text[Pause to ask about git, GitHub, and git-annex]
 
 
]
--

.boxed-content.center[
.gray-text[Let's investigate our dataset...]

.large[https://github.com/nipreps-data/bootcamp-geneva-2024-dataset]
]

---

# Exercises with *PyBIDS*

.large.boxed-content[
* Get a list of all the resting-state BOLD files in the dataset

* Get a list of all T1w images in the dataset

* Get the `PhaseEncodingDirection` (or directions) of only BOLD files
]

---

# Those having issues on bamboo

Add to the end of your `$HOME/.bashrc`:

``` Bash
# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup="$('/opt/ebsofts/Miniconda3/4.9.2/bin/conda' 'shell.bash' 'hook' 2> /dev/null)"
if [ $? -eq 0 ]; then
 eval "$__conda_setup"
else
 if [ -f "/opt/ebsofts/Miniconda3/4.9.2/etc/profile.d/conda.sh" ]; then
 . "/opt/ebsofts/Miniconda3/4.9.2/etc/profile.d/conda.sh"
 else
 export PATH="/opt/ebsofts/Miniconda3/4.9.2/bin:$PATH"
 fi
fi
unset __conda_setup
# <<< conda initialize <<<
```