![tracking performed on the A0 component overlaid onto the tissue component ODFs](components.png)
# dHCP neonatal-multi-component-HARDI-atlas

This hosts the multi-component atlas of diffusion MRI data over the neonatal period created for the publication **A framework for multi-component analysis of diffusion MRI data over the neonatal period.**
doi: [10.1016/j.neuroimage.2018.10.060](https://www.sciencedirect.com/science/article/pii/S1053811918320329)
using data collected as part of the [developing Human Connectome Project](http://www.developingconnectome.org/) (dHCP).


---

## Cite
Please cite the following publication:

Pietsch, Maximilian, et al. "A framework for multi-component analysis of diffusion MRI data over the neonatal period." NeuroImage 186 (2019): 321-337.

```bibtex
@article{pietsch2019framework,
  title={A framework for multi-component analysis of diffusion MRI data over the neonatal period},
  author={Pietsch, Maximilian and Christiaens, Daan and Hutter, Jana and Cordero-Grande, Lucilio and Price, Anthony N and Hughes, Emer and Edwards, A David and Hajnal, Joseph V and Counsell, Serena J and Tournier, J-Donald},
  journal={NeuroImage},
  volume={186},
  pages={321--337},
  year={2019},
  publisher={Elsevier}
}
```

---

## Download 

### Manually

The weekly templates can be downloaded individually from [here](https://gin.g-node.org/maxpietsch/dHCP_neonatal_HARDI_atlas/src/master/v1/rigid/mean).

### via the GIN command line interface


This describes how to download the data using the [GIN-CLI client](http://https://github.com/G-Node/gin-cli).

On macOS, it can be installed via [homebrew](https://brew.sh/):
```bash
brew tap g-node/pkg
brew install g-node/pkg/gin-cli
```

On ubuntu:
```bash
wget https://web.gin.g-node.org/G-Node/gin-cli-releases/raw/master/gin-cli-latest.deb
sudo dpkg -i gin-cli-latest.deb
sudo apt install -f
```

For standlone binaries and instructions for other operating systems, see [here](https://github.com/G-Node/gin-cli/wiki/downloads).


Then, to download this repository simply execute
```bash
gin get maxpietsch/dHCP_neonatal_HARDI_atlas
cd dHCP_neonatal_HARDI_atlas
```

Initially, place-holder files are downloaded instead of larger files (.git/annex). If you want to download all files use `gin download --content`, for individual files or directories use `gin get-content <location>`, for downloading all rigidly aligned templates use `gin get-content v1/rigid/mean`, check the download status with `gin ls`. See [GIN CLI Usage Tutorial](https://gin.g-node.org/G-Node/Info/wiki/GIN+CLI+Usage+Tutorial) for details.

### via Datalad

If needed, install [datalad](https://www.datalad.org/get_datalad.html), then clone this repo with

```bash
datalad clone https://gin.g-node.org/maxpietsch/dHCP_neonatal_HARDI_atlas
cd dHCP_neonatal_HARDI_atlas
```

Finally, download any files needed. For instance, the group-average templates can be downloaded via `datalad get v1/rigid/mean`.



## Data

Response functions and `.mif.gz` images can be processed, converted and inspected with MRtrix3 (https://www.mrtrix.org/).

Note that mean and median aggregation was perfomed using (Not-a-Number-) masked data using the
brain masks as inclusion criteria for the aggregation operation. This prevents
bias due to cropped data and allows retrospectively thresholding the template 
voxels by the number of subjects using the count.mif.gz images. 
For instance, the following MRtrix3 command replaces voxel values to which fewer than 5 subjects contribute by NaNs:
`mrcalc count.mif.gz 5 -ge odf_o_normed_cyo.mif.gz nan -if odf_o_normed_cyo_thresholded.mif.gz`


### Organisation


This repo is organised hierarchically: 


```
├── LICENSE
├── README.md
└── v1                          <-- atlas version (`v1` is as used for the paper)
    ├── joint                   <-- jointly aligned data (single space across time)
    │   ├── mean                <-- mode of aggregation
    │   ├── median              <-- mode of aggregation
    │   ├── rois                <-- regions of interest used for the paper
    ├── rigid                   <-- weekly templates, rigidly aligned
    │   ├── mean
    │   └── median
    └── metadata                <-- subject information and response functions
        ├── rf_csf_all
        ├── rf_native
        ├── rf_tissue_32.9
        ├── rf_tissue_44.1
        ├── sub_ses_ga_32.9
        ├── sub_ses_ga_34.0
        ├── sub_ses_ga_35.2
        ├── sub_ses_ga_35.7
        ├── sub_ses_ga_37.1
        ├── sub_ses_ga_38.1
        ├── sub_ses_ga_39.1
        ├── sub_ses_ga_40.1
        ├── sub_ses_ga_40.9
        ├── sub_ses_ga_42.0
        ├── sub_ses_ga_42.8
        └── sub_ses_ga_44.1
```

The files (see [fig. 3](https://www.sciencedirect.com/science/article/pii/S1053811918320329#fig3)):

```

├── LICENSE
├── README.md
└── v1
    ├── joint
    │   ├── mean
    │   │   ├── 32.9
    │   │   │   ├── adc.mif.gz                         <-- DTI-fit, ADC map
    │   │   │   ├── count.mif.gz                       <-- sum across masks, useful to modify template mask
    │   │   │   ├── fa.mif.gz                          <-- DTI-fit, FA map
    │   │   │   ├── mask.mif.gz
    │   │   │   ├── odf_csf_normed_cyo.mif.gz          <-- fluid component ODF, intensity, normalised
    │   │   │   ├── odf_csf_normed_native.mif.gz       <-- subject-native fluid image
    │   │   │   ├── odf_o_normed_cyo.mif.gz            <-- Ao: older-appearing tissue component
    │   │   │   ├── odf_wm_gm_normed_native.mif.gz     <-- subject-native tissue image
    │   │   │   └── odf_y_normed_cyo.mif.gz            <-- Ay: younger-appearing tissue component, normalised
    │   │   ├── 34.0
...
    ├── metadata
    │   ├── rf_native                                   <-- subject-specific response functions
    │   │   ├── sub-CC00063AN06_ses-15102_36_csf.txt    <-- CSF response function for this subject (PMA: 36w)
    │   │   ├── sub-CC00063AN06_ses-15102_36_wm_gmi.txt
    │   │   ├── sub-CC00065XX08_ses-18600_41_csf.txt
    │   │   ├── sub-CC00065XX08_ses-18600_41_wm_gmi.txt
    │   │   ├── sub-CC00067XX10_ses-20200_40_csf.txt

...
    │   ├── rf_csf_all                                  <-- group-average response functions
    │   ├── rf_tissue_32.9
    │   ├── rf_tissue_44.1
    │   ├── sub_ses_ga_32.9                             <-- subject identitifers per age group
    │   ├── sub_ses_ga_34.0
    │   ├── sub_ses_ga_35.2
    │   ├── sub_ses_ga_35.7
    │   ├── sub_ses_ga_37.1
    │   ├── sub_ses_ga_38.1
    │   ├── sub_ses_ga_39.1
    │   ├── sub_ses_ga_40.1
    │   ├── sub_ses_ga_40.9
    │   ├── sub_ses_ga_42.0
    │   ├── sub_ses_ga_42.8
    │   └── sub_ses_ga_44.1
    └── rigid
        ├── mean
        │   ├── 32.9
        │   │   ├── adc.mif.gz
        │   │   ├── count.mif.gz
        │   │   ├── fa.mif.gz
        │   │   ├── mask.mif.gz
        │   │   ├── odf_csf_normed_cyo.mif.gz
        │   │   ├── odf_csf_normed_native.mif.gz
        │   │   ├── odf_o_normed_cyo.mif.gz
        │   │   ├── odf_wm_gm_normed_native.mif.gz
        │   │   └── odf_y_normed_cyo.mif.gz
        │   ├── 34.0
...
```