diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..eb1ee89
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,86 @@
+# How to contribute
+
+As a PhD student, all my time cannot be dedicated to improving and maintaining this project, so any contribution is very welcome,
+from suggestions to bug reports, feature requests, and even code contributions.
+
+`HSF` is designed to be your last tool needed for hippocampal segmentation, we want it fully customizable, and we want you to be able
+to use it as a tool for your own research, even on your own segmentation models. Feel free to make `HSF` it a way it is useful for you.
+
+## Improving `HSF`
+
+### Coding conventions
+
+Internally, we use [Google's Python Style Guide](https://google.github.io/styleguide/pyguide.html).
+
+Please try to stick to it. To make it easier for you, try YAPF :)
+
+### Documentation
+
+Every new function should be documented. In the code docstrings are mandatory as in the example below:
+
+```python
+def load_from_config(path: str, pattern: str) -> list:
+ """
+ Loads all mris from a given path with a given pattern.
+
+ Args:
+ path (str): Path to the mris.
+ pattern (str): Pattern to search for.
+
+ Returns:
+ list: List of mris.
+ """
+ p = Path(path).expanduser()
+ return list(p.glob(pattern))
+```
+
+Every top-level functionality directly accessible to the end-user has to be documented in the [`HSF` doc](https://hsf.rtfd.io/)
+
+### Configurability
+
+It is very important to us that all settings are configurable through Hydra. This is why we have a `config.yaml` file defining all parameters
+used in `HSF`.
+
+### Testing
+
+`HSF` is automatically tested with `pytest`. Please be sure that your code is tested properly.
+
+## Improving Segmentation Models
+
+If you found a way to improve our segmentation quality (e.g. by tweaking TTA's default parameters), please open an issue or make a PR.
+
+Additionally data is the new gold. If you have incorrect segmentations, feel free to correct them, and then send them to us.
+The data will be kept private, stored in secured infrastructures, and will be used in the next training iteration of HSF.
+
+We would be very grateful.
+
+We always seek for new datasets, so if you have a dataset with manual segmentations of hippocampi, or heard about a new released dataset, please let us know.
+
+As soon as we have obtained a relatively good amount of new segmentations (maybe 10 to 20 new hippocampi), we will retrain our models, and we will release a new version of HSF.
+You will then be able to benefit from the improved segmentation by running `pip install -U hsf` as soon as the new version is released.
+
+Additionaly, if you trained your own models and you want to share them with the community, please consider making a pull request with
+a configuration file like the ones in `hsf/conf/segmentation/*.yaml`.
+
+For example, you can submit `hsf/conf/segmentation/johndoe2021.yaml`:
+
+```yaml
+# Configuration file implementing the segmentation models of
+# John Doe, et al., 2021.
+
+ca_mode: "1/2/3"
+models_path: "~/.hsf/models/bagging/"
+models:
+ johndoe_etal_2021_0.onnx:
+ url: "https://url-to-your-trained-model/model0.onnx"
+ xxh3_64: "f0f0f0f0f0f0f0f0"
+ johndoe_etal_2021_1.onnx:
+ url: "https://url-to-your-trained-model/model1.onnx"
+ xxh3_64: "f1f1f1f1f1f1f1f1"
+
+segmentation:
+ test_time_augmentation: True
+ test_time_num_aug: 42
+```
+
+By doing so, future users will be able to use your models by running `hsf segmentation=johndoe2021`.
diff --git a/README.rst b/README.rst
index 5ce3634..3309cad 100644
--- a/README.rst
+++ b/README.rst
@@ -2,6 +2,8 @@
Hippocampal Segmentation Factory (HSF)
======================================
+Exhaustive documentation available at: `hsf.rtfd.io `_
+
**Current Models version:** 1.0.0
.. list-table::
@@ -204,117 +206,11 @@ Models
* Initial release.
-Frequently asked questions
+Documentation
==========================
-How to specify where to store ONNX models?
-------------------------------------------
-
-Just override the ``segmentation.models_path`` parameter in the configuration like this:
-
-``hsf segmentation.models_path="~/my_models"``
-
-This parameter defaults to ``~/.hsf/models``.
-
-
-How to improve segmentation quality?
-------------------------------------
-
-If the segmentation is not good enough, you can try to improve it with the following steps:
-
-* Try to augment the number of TTAs,
-* Try to use a different ONNX model (by adding its ONNX to ``~/.hsf/models``),
-
-If the segmentation is clearly absent or outside the hippocampus, it is because ROILoc failed.
-This is caused by ANTs having troubles to perform registration, leading to a wrong bounding box.
-
-Generally, performing a brain extraction step, our using another ``transform_type`` (e.g. ``SyN``)
-solves this problem.
-
-Also check that the margins are high engough, otherwise you might be missing some subfields
-(crop effect). If your margins are already larges, but part of the hippocampus stays outside,
-you might want to try to increase the ``rightoffset`` and ``leftoffset`` parameters.
-
-The offset parameters are lists of 3 integers, one for each axis. They specify the offset
-1/ from left to right, 2/ from posterior to anterior, and 3/ from inferior to superior.
-
-
-How to help us improve segmentation quality?
---------------------------------------------
-
-If you found a way to improve our segmentation quality (e.g. by tweaking TTA), please open
-an issue or make a PR on GitHub.
-
-Additionally data is the new gold. If you have incorrect segmentations, feel free to
-correct them, and then send them to us. The data will be kept private,
-stored in secured infrastructures, and will be used in the next training iteration of HSF.
-We would be very grateful.
-
-Please open an issue on GitHub so we can agree on how to transfer the segmentations.
-
-We always seek for new datasets, so if you have a dataset with manual segmentations of
-hippocampi, or heared about a new released dataset, please let us know.
-
-As soon as we obtained a relatively good amount of new segmentations (maybe 10 to 20 new
-hippocampi), we will retrain our models, and we will release a new version of HSF. You
-will then be able to benefit from the improved segmentation by running
-``pip install -U hsf`` as soon as the new version is released.
-
-
-Which MRI modalities are usable in HSF?
----------------------------------------
-
-We trained HSF using T1 (MPRAGE & MP2RAGE) and T2 (mostly TSE) modalities.
-
-HSF should work with isotropic and non-isotropic images, but we do not encourage the segmentation
-on 1mm iso images as the resolution is too low to distinguish between subfields.
-
-We trained on CoroT2 with resolutions as low as 0.125*0.125*1.2mm.
-
-You can of course try with other settings, feel free to report your results :)
-
-
-Custom models
--------------
-
-You can use your own ONNX models by placing them in ``~/.hsf/models``, and
-providing the correct configuration (path & xxh3_64).
-
-You can also just place your models there, and use our ``bagging*`` presets,
-they will be included in the plurality votes.
-
-
-Hardware management and Execution Providers
--------------------------------------------
-
-Since v0.1.2, HSF allows the customization of execution providers though
-``hardware.execution_providers``, taking a list of execution providers
-in order of decreasing precedance.
-
-Please check ONNXRuntime's documentation on
-`Execution Providers `_
-for more information.
-
-Here is the default execution:
-
-``hsf hardware.execution_providers=["CUDAExecutionProvider","CPUExecutionProvider"]``
-
-By default, if a provider isn't available, the next one will be used. As an example,
-to force the use of your CPU, you can do:
-
-``hsf hardware.execution_providers=["CPUExecutionProvider"]``
-
-You can also specify provider options by providing a ``List[str, dict]`` instead of
-a single ``str`` as in the following example:
-
-``hsf hardware.execution_providers=[["CUDAExecutionProvider",{"device_id":0,"gpu_mem_limit":2147483648}],"CPUExecutionProvider"]``
-
-
-Performance tunning
--------------------
-
-Please refer to ONNXRuntime's documentation for setting-up the correct environment,
-to benefit from the performance and scalability of hardware accelerations.
+For more details about HSF's configuration and internal parameters, please refer to
+our `documentation `_.
Authorship, Affiliations and Citations
diff --git a/docs/contributing.md b/docs/contributing.md
index 0a82838..eb1ee89 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,19 +1,86 @@
-# Contributing
+# How to contribute
-If you found a way to improve our segmentation quality (e.g. by tweaking TTA), please open
-an issue or make a PR on GitHub.
+As a PhD student, all my time cannot be dedicated to improving and maintaining this project, so any contribution is very welcome,
+from suggestions to bug reports, feature requests, and even code contributions.
+
+`HSF` is designed to be your last tool needed for hippocampal segmentation, we want it fully customizable, and we want you to be able
+to use it as a tool for your own research, even on your own segmentation models. Feel free to make `HSF` it a way it is useful for you.
+
+## Improving `HSF`
+
+### Coding conventions
+
+Internally, we use [Google's Python Style Guide](https://google.github.io/styleguide/pyguide.html).
+
+Please try to stick to it. To make it easier for you, try YAPF :)
+
+### Documentation
+
+Every new function should be documented. In the code docstrings are mandatory as in the example below:
+
+```python
+def load_from_config(path: str, pattern: str) -> list:
+ """
+ Loads all mris from a given path with a given pattern.
+
+ Args:
+ path (str): Path to the mris.
+ pattern (str): Pattern to search for.
+
+ Returns:
+ list: List of mris.
+ """
+ p = Path(path).expanduser()
+ return list(p.glob(pattern))
+```
+
+Every top-level functionality directly accessible to the end-user has to be documented in the [`HSF` doc](https://hsf.rtfd.io/)
+
+### Configurability
+
+It is very important to us that all settings are configurable through Hydra. This is why we have a `config.yaml` file defining all parameters
+used in `HSF`.
+
+### Testing
+
+`HSF` is automatically tested with `pytest`. Please be sure that your code is tested properly.
+
+## Improving Segmentation Models
+
+If you found a way to improve our segmentation quality (e.g. by tweaking TTA's default parameters), please open an issue or make a PR.
+
+Additionally data is the new gold. If you have incorrect segmentations, feel free to correct them, and then send them to us.
+The data will be kept private, stored in secured infrastructures, and will be used in the next training iteration of HSF.
-Additionally data is the new gold. If you have incorrect segmentations, feel free to
-correct them, and then send them to us. The data will be kept private,
-stored in secured infrastructures, and will be used in the next training iteration of HSF.
We would be very grateful.
-Please open an issue on GitHub so we can agree on how to transfer the segmentations.
+We always seek for new datasets, so if you have a dataset with manual segmentations of hippocampi, or heard about a new released dataset, please let us know.
+
+As soon as we have obtained a relatively good amount of new segmentations (maybe 10 to 20 new hippocampi), we will retrain our models, and we will release a new version of HSF.
+You will then be able to benefit from the improved segmentation by running `pip install -U hsf` as soon as the new version is released.
+
+Additionaly, if you trained your own models and you want to share them with the community, please consider making a pull request with
+a configuration file like the ones in `hsf/conf/segmentation/*.yaml`.
+
+For example, you can submit `hsf/conf/segmentation/johndoe2021.yaml`:
+
+```yaml
+# Configuration file implementing the segmentation models of
+# John Doe, et al., 2021.
+
+ca_mode: "1/2/3"
+models_path: "~/.hsf/models/bagging/"
+models:
+ johndoe_etal_2021_0.onnx:
+ url: "https://url-to-your-trained-model/model0.onnx"
+ xxh3_64: "f0f0f0f0f0f0f0f0"
+ johndoe_etal_2021_1.onnx:
+ url: "https://url-to-your-trained-model/model1.onnx"
+ xxh3_64: "f1f1f1f1f1f1f1f1"
-We always seek for new datasets, so if you have a dataset with manual segmentations of
-hippocampi, or heared about a new released dataset, please let us know.
+segmentation:
+ test_time_augmentation: True
+ test_time_num_aug: 42
+```
-As soon as we obtained a relatively good amount of new segmentations (maybe 10 to 20 new
-hippocampi), we will retrain our models, and we will release a new version of HSF. You
-will then be able to benefit from the improved segmentation by running
-`pip install -U hsf` as soon as the new version is released.
+By doing so, future users will be able to use your models by running `hsf segmentation=johndoe2021`.
diff --git a/docs/papers/joss/figures/hsf.png b/docs/papers/joss/figures/hsf.png
index 3ed7145..70205ae 100644
Binary files a/docs/papers/joss/figures/hsf.png and b/docs/papers/joss/figures/hsf.png differ
diff --git a/docs/papers/joss/paper.bib b/docs/papers/joss/paper.bib
index e69de29..51bd0eb 100644
--- a/docs/papers/joss/paper.bib
+++ b/docs/papers/joss/paper.bib
@@ -0,0 +1,153 @@
+@article{todaRoleAdultHippocampal2019,
+ title = {The Role of Adult Hippocampal Neurogenesis in Brain Health and Disease},
+ author = {Toda, Tomohisa and Parylak, Sarah L. and Linker, Sara B. and Gage, Fred H.},
+ date = {2019-01},
+ journaltitle = {Molecular Psychiatry},
+ shortjournal = {Mol Psychiatry},
+ volume = {24},
+ number = {1},
+ pages = {67--87},
+ issn = {1359-4184, 1476-5578},
+ doi = {10.1038/s41380-018-0036-2},
+ url = {http://www.nature.com/articles/s41380-018-0036-2},
+ abstract = {Adult neurogenesis in the dentate gyrus of the hippocampus is highly regulated by a number of environmental and cell-intrinsic factors to adapt to environmental changes. Accumulating evidence suggests that adult-born neurons may play distinct physiological roles in hippocampus-dependent functions such as memory encoding and mood regulation. In addition, several brain diseases, such as neurological diseases and mood disorders, have deleterious effects on adult hippocampal neurogenesis, and some symptoms of those diseases can be partially explained by the dysregulation of adult hippocampal neurogenesis. Here we review a possible link between the physiological functions of adult-born neurons and their roles in pathological conditions.},
+ langid = {english}
+}
+
+@article{yushkevichAutomatedVolumetryRegional2015,
+ title = {Automated Volumetry and Regional Thickness Analysis of Hippocampal Subfields and Medial Temporal Cortical Structures in Mild Cognitive Impairment: Automatic {{Morphometry}} of {{MTL Subfields}} in {{MCI}}},
+ shorttitle = {Automated Volumetry and Regional Thickness Analysis of Hippocampal Subfields and Medial Temporal Cortical Structures in Mild Cognitive Impairment},
+ author = {Yushkevich, Paul A. and Pluta, John B. and Wang, Hongzhi and Xie, Long and Ding, Song-Lin and Gertje, Eske C. and Mancuso, Lauren and Kliot, Daria and Das, Sandhitsu R. and Wolk, David A.},
+ date = {2015-01},
+ journaltitle = {Human Brain Mapping},
+ shortjournal = {Hum. Brain Mapp.},
+ volume = {36},
+ number = {1},
+ pages = {258--287},
+ issn = {10659471},
+ doi = {10.1002/hbm.22627},
+ langid = {english}
+}
+
+@article{iglesiasComputationalAtlasHippocampal2015,
+ title = {A Computational Atlas of the Hippocampal Formation Using Ex Vivo , Ultra-High Resolution {{MRI}}: Application to Adaptive Segmentation of in Vivo {{MRI}}},
+ shorttitle = {A Computational Atlas of the Hippocampal Formation Using Ex Vivo , Ultra-High Resolution {{MRI}}},
+ author = {Iglesias, Juan Eugenio and Augustinack, Jean C. and Nguyen, Khoa and Player, Christopher M. and Player, Allison and Wright, Michelle and Roy, Nicole and Frosch, Matthew P. and McKee, Ann C. and Wald, Lawrence L. and Fischl, Bruce and Van Leemput, Koen},
+ date = {2015-07},
+ journaltitle = {NeuroImage},
+ shortjournal = {NeuroImage},
+ volume = {115},
+ pages = {117--137},
+ issn = {10538119},
+ doi = {10.1016/j.neuroimage.2015.04.042},
+ langid = {english}
+}
+
+@article{romeroHIPSNewHippocampus2017,
+ title = {{{HIPS}}: A New Hippocampus Subfield Segmentation Method},
+ shorttitle = {{{HIPS}}},
+ author = {Romero, Jos\'e E. and Coup\'e, Pierrick and Manj\'on, Jos\'e V.},
+ date = {2017-12},
+ journaltitle = {NeuroImage},
+ shortjournal = {NeuroImage},
+ volume = {163},
+ pages = {286--295},
+ issn = {10538119},
+ doi = {10.1016/j.neuroimage.2017.09.049},
+ url = {https://linkinghub.elsevier.com/retrieve/pii/S1053811917307978},
+ urldate = {2021-01-15},
+ abstract = {The importance of the hippocampus in the study of several neurodegenerative diseases such as Alzheimer's disease makes it a structure of great interest in neuroimaging. However, few segmentation methods have been proposed to measure its subfields due to its complex structure and the lack of high resolution magnetic resonance (MR) data. In this work, we present a new pipeline for automatic hippocampus subfield segmentation using two available hippocampus subfield delineation protocols that can work with both high and standard resolution data. The proposed method is based on multi-atlas label fusion technology that benefits from a novel multicontrast patch match search process (using high resolution T1-weighted and T2-weighted images). The proposed method also includes as post-processing a new neural network-based error correction step to minimize systematic segmentation errors. The method has been evaluated on both high and standard resolution images and compared to other state-of-the-art methods showing better results in terms of accuracy and execution time.},
+ langid = {english}
+}
+
+@article{qiuFeasibilityAutomaticSegmentation2019,
+ title = {Feasibility of {{Automatic Segmentation}} of {{Hippocampus Based}} on {{Deep Learning}} in {{Hippocampus}}-{{Sparing Radiotherapy}}},
+ author = {Qiu, Q. and Gong, G. and Wang, L. and Duan, J. and Yin, Y.},
+ date = {2019-09},
+ journaltitle = {International Journal of Radiation Oncology*Biology*Physics},
+ shortjournal = {International Journal of Radiation Oncology*Biology*Physics},
+ volume = {105},
+ number = {1},
+ pages = {E137-E138},
+ issn = {03603016},
+ doi = {10.1016/j.ijrobp.2019.06.2177},
+ url = {https://linkinghub.elsevier.com/retrieve/pii/S0360301619330123},
+ urldate = {2019-10-01},
+ abstract = {Purpose/Objective(s): Incidence of liver cancer is continuously increasing. American Cancer Society predicts about 42,030 new cases of liver cancer (29,480 in men and 12,550 in women) and 31,780 (21,600 men and 10,180 women) deaths due to liver cancer in 2019. There is a consensus that smoking is one of the known risk factors for liver cancer. Studies showed that current smokers have higher risk than former smokers. The purpose of this study to check a reduction in liver cancer risk by varying smoking status (from current to former) through a multi-parameterized neural network (NN). Materials/Methods: A multi-parameterized neural network (NN) was trained and tested with the National Health Interview Survey (NHIS) data collected from 1997 to 2017 and the Prostate, Lung, Colorectal, Ovarian cancer screening trail data collected from 1993 to 2001. Among a total of 795,163 persons interviewed, 478 were diagnosed with liver cancer. The features used as inputs for NN include age, race, BMI, race, Hispanic ethnicity, exercise habits, smoking, and drinking habits, diabetes, emphysema, stroke, hypertension, heart disease, arthritis, another cancer, family history of cancer. The NN was trained on 70\% of the data and tested on 30\% and the tested population was stratified as low, medium, and high risk for the liver cancer. Both training and testing datasets were stratified for low, medium, and high risk groups. Amongst high-risk group, 17 persons were selected those were obese (BMI {$>$} 0.30), current smokers, relatively heavy drinkers (drinks {$>$} 100 days/year) and not diagnosed for liver cancer at the survey time. The smoking status was changed from current smoker to former smoker in the input features of NN and the variation in their risks was studied. Results: The areas under the curve of the conventional receiver operating characteristic plots for our neural network are 0.83 and 0.85 for the training and testing datasets, respectively. A considerable reduction (maximum reduction is 77.7\%) in the risk values of the selected 17 people were observed by changing their status from current smoker to former smokers. Amongst these people, 35\% (6 people) were shifted from high risk group to medium risk group. Conclusion: Normally, NN is used either for prediction or diagnosis. However, this study is using NN to simulate the variation of cancer risk with changes in habits/life style. The results indicate that the use of a NN based on personal health information cannot only be used for the stratification of large population for liver cancer risk but can also be used for simulating the cancer risk with varying lifestyle.},
+ langid = {english}
+}
+
+@article{zhuDilatedDenseUNet2019,
+ title = {Dilated {{Dense U}}-{{Net}} for {{Infant Hippocampus Subfield Segmentation}}},
+ author = {Zhu, Hancan and Shi, Feng and Wang, Li and Hung, Sheng-Che and Chen, Meng-Hsiang and Wang, Shuai and Lin, Weili and Shen, Dinggang},
+ date = {2019-04-24},
+ journaltitle = {Frontiers in Neuroinformatics},
+ shortjournal = {Front. Neuroinform.},
+ volume = {13},
+ pages = {30},
+ issn = {1662-5196},
+ doi = {10.3389/fninf.2019.00030},
+ url = {https://www.frontiersin.org/article/10.3389/fninf.2019.00030/full},
+ urldate = {2020-09-18},
+ abstract = {Accurate and automatic segmentation of infant hippocampal subfields from magnetic resonance (MR) images is an important step for studying memory related infant neurological diseases. However, existing hippocampal subfield segmentation methods were generally designed based on adult subjects, and would compromise performance when applied to infant subjects due to insufficient tissue contrast and fast changing structural patterns of early hippocampal development. In this paper, we propose a new fully convolutional network (FCN) for infant hippocampal subfield segmentation by embedding the dilated dense network in the U-net, namely DUnet. The embedded dilated dense network can generate multi-scale features while keeping high spatial resolution, which is useful in fusing the low-level features in the contracting path with the high-level features in the expanding path. To further improve the performance, we group every pair of convolutional layers with one residual connection in the DUnet, and obtain the Residual DUnet (ResDUnet). Experimental results show that our proposed DUnet and ResDUnet improve the average Dice coefficient by 2.1 and 2.5\% for infant hippocampal subfield segmentation, respectively, when compared with the classic 3D U-net. The results also demonstrate that our methods outperform other state-of-the-art methods.},
+ langid = {english}
+}
+
+@article{fonovUnbiasedNonlinearAverage2009,
+ title = {Unbiased Nonlinear Average Age-Appropriate Brain Templates from Birth to Adulthood},
+ author = {Fonov, Vs and Evans, Ac and McKinstry, Rc and Almli, Cr and Collins, Dl},
+ date = {2009-07},
+ journaltitle = {NeuroImage},
+ shortjournal = {NeuroImage},
+ volume = {47},
+ pages = {S102},
+ issn = {10538119},
+ doi = {10.1016/S1053-8119(09)70884-5},
+ langid = {english}
+}
+
+@article{maneraCerebrARegistrationManual2020,
+ title = {{{CerebrA}}, Registration and Manual Label Correction of {{Mindboggle}}-101 Atlas for {{MNI}}-{{ICBM152}} Template},
+ author = {Manera, Ana L. and Dadar, Mahsa and Fonov, Vladimir and Collins, D. Louis},
+ date = {2020-12},
+ journaltitle = {Scientific Data},
+ shortjournal = {Sci Data},
+ volume = {7},
+ number = {1},
+ pages = {237},
+ issn = {2052-4463},
+ doi = {10.1038/s41597-020-0557-9},
+ abstract = {Abstract Accurate anatomical atlases are recognized as important tools in brain-imaging research. They are widely used to estimate disease-specific changes and therefore, are of great relevance in extracting regional information on volumetric variations in clinical cohorts in comparison to healthy populations. The use of high spatial resolution magnetic resonance imaging and the improvement in data preprocessing methods have enabled the study of structural volume changes on a wide range of disorders, particularly in neurodegenerative diseases where different brain morphometry analyses are being broadly used in an effort to improve diagnostic biomarkers. In the present dataset, we introduce the Cerebrum Atlas (CerebrA) along with the MNI-ICBM2009c average template. MNI-ICBM2009c is the most recent version of the MNI-ICBM152 brain average, providing a higher level of anatomical details. Cerebra is based on an accurate non-linear registration of cortical and subcortical labelling from Mindboggle 101 to the symmetric MNI-ICBM2009c atlas, followed by manual editing.},
+ langid = {english}
+}
+
+@article{lagardeDistinctAmyloidTau2021,
+ title = {Distinct Amyloid and Tau {{PET}} Signatures Are Associated with Diverging Clinical and Imaging Trajectories in Patients with Amnestic Syndrome of the Hippocampal Type},
+ author = {Lagarde, Julien and Olivieri, Pauline and Tonietto, Matteo and Gervais, Philippe and Comtat, Claude and Caill\'e, Fabien and Bottlaender, Michel and Sarazin, Marie},
+ date = {2021-12},
+ journaltitle = {Translational Psychiatry},
+ shortjournal = {Transl Psychiatry},
+ volume = {11},
+ number = {1},
+ pages = {498},
+ issn = {2158-3188},
+ doi = {10.1038/s41398-021-01628-9},
+ abstract = {Abstract We aimed to investigate the amyloid and tau PET imaging signatures of patients with amnestic syndrome of the hippocampal type (ASHT) and study their clinical and imaging progression according to their initial PET imaging status. Thirty-six patients with a progressive ASHT and 30 controls underwent a complete neuropsychological assessment, 3\,T brain MRI, [ 11 C]-PiB and [ 18 F]-Flortaucipir PET imaging. Subjects were clinically followed-up annually over 2 years, with a second 3\,T MRI ( n \,=\,27 ASHT patients, n \,=\,28 controls) and tau-PET ( n \,=\,20 ASHT patients) at the last visit. At baseline, in accordance with the recent biological definition of Alzheimer's disease (AD), the AD PET signature was defined as the combination of (i) positive cortical amyloid load, and (ii) increased tau tracer binding in the entorhinal cortices and at least one of the following regions: amygdala, parahippocampal gyri, fusiform gyri. Patients who did not meet these criteria were considered to have a non-AD pathology (SNAP). Twenty-one patients were classified as AD and 15 as SNAP. We found a circumscribed tau tracer retention in the entorhinal cortices and/or amygdala in 5 amyloid-negative SNAP patients. At baseline, the SNAP patients were older and had lower ApoE {$\epsilon$}4 allele frequency than the AD patients, but both groups did not differ regarding the neuropsychological testing and medial temporal lobe atrophy. During the 2-year follow-up, the episodic memory and language decline, as well as the temporo-parietal atrophy progression, were more pronounced in the AD sub-group, while the SNAP patients had a more pronounced progression of atrophy in the frontal lobes. Longitudinal tau tracer binding increased in AD patients but remained stable in SNAP patients. At baseline, distinct amyloid and tau PET signatures differentiated early AD and SNAP patients despite identical cognitive profiles characterized by an isolated ASHT and a similar degree of medial temporal atrophy. During the longitudinal follow-up, AD and SNAP patients diverged regarding clinical and imaging progression. Among SNAP patients, tau PET imaging could detect a tauopathy restricted to the medial temporal lobes, which was possibly explained by primary age-related tauopathy.},
+ langid = {english}
+}
+
+@article{haegerImagingAgingBrain2020,
+ title = {Imaging the Aging Brain: Study Design and Baseline Findings of the {{SENIOR}} Cohort},
+ shorttitle = {Imaging the Aging Brain},
+ author = {Haeger, Alexa and Mangin, Jean-Fran\c{c}ois and Vignaud, Alexandre and Poupon, Cyril and Grigis, Antoine and Boumezbeur, Fawzi and Frouin, Vincent and Deverre, Jean-Robert and Sarazin, Marie and Hertz-Pannier, Lucie and Bottlaender, Michel and {the SENIOR team} and Baron, Christine and Berland, Val\'erie and Blancho, Nathalie and Desmidt, S\'everine and Doubl\'e, Christine and Ginisty, Chantal and Joly-Testault, V\'eronique and Laurier, Laurence and Lecomte, Yann and Leroy, Claire and Manciot, Christine and Marchand, Stephanie and Mediouni, Gaelle and Millot, Xavier and Monassier, Ludivine and Roger, S\'everine and Vuillemard, Catherine},
+ date = {2020-12},
+ journaltitle = {Alzheimer's Research \& Therapy},
+ shortjournal = {Alz Res Therapy},
+ volume = {12},
+ number = {1},
+ pages = {77},
+ issn = {1758-9193},
+ doi = {10.1186/s13195-020-00642-1},
+ abstract = {Abstract Background Current demographic trends point towards an aging society entailing increasing occurrence and burden of neurodegenerative diseases. In this context, understanding physiological aging and its turning point into neurodegeneration is essential for the development of possible biomarkers and future therapeutics of brain disease. Methods The SENIOR study represents a longitudinal, observational study including cognitively healthy elderlies aged between 50 and 70\,years old at the time of inclusion, being followed annually over 10\,years. Our multimodal protocol includes structural, diffusion, functional, and sodium magnetic resonance imaging (MRI) at 3\,T and 7\,T, positron emission tomography (PET), blood samples, genetics, audiometry, and neuropsychological and neurological examinations as well as assessment of neuronal risk factors. Results One hundred forty-two participants (50\% females) were enrolled in the SENIOR cohort with a mean age of 60 (SD 6.3) years at baseline. Baseline results with multiple regression analyses reveal that cerebral white matter lesions can be predicted by cardiovascular and cognitive risk factors and age. Cardiovascular risk factors were strongly associated with juxtacortical and periventricular lesions. Intra-subject across-test variability as a measure of neuropsychological test performance and possible cognitive marker predicts white matter volume and is significantly associated with risk profile. Division of the cohort into subjects with a higher and lower risk profile shows significant differences in intra-subject across-test variability and volumes as well as cortical thickness of brain regions of the temporal lobe. There is no difference between the lower- and higher-risk groups in amyloid load using PET data from a subset of 81 subjects. Conclusions We here describe the study protocol and baseline findings of the SENIOR observational study which aim is the establishment of integrated, multiparametric maps of normal aging and the identification of early biomarkers for neurodegeneration. We show that intra-subject across-test variability as a marker of neuropsychological test performance as well as age, gender, and combined risk factors influence neuronal decline as represented by decrease in brain volume, cortical thickness, and increase in white matter lesions. Baseline findings will be used as underlying basis for the further implications of aging and neuronal degeneration as well as examination of brain aging under different aspects of brain pathology versus physiological aging.},
+ langid = {english}
+}
diff --git a/docs/papers/joss/paper.md b/docs/papers/joss/paper.md
index 5852f02..3cac8f3 100644
--- a/docs/papers/joss/paper.md
+++ b/docs/papers/joss/paper.md
@@ -1,5 +1,5 @@
---
-title: 'HSF for a Fast, Robust, and Automated Segmentation of Hippocampal Subfields in MRI'
+title: 'HSF as a Future-Proof Solution to Hippocampal Subfields Segmentation in MRI'
tags:
- python
- mri
@@ -41,44 +41,52 @@ bibliography: paper.bib
# Summary
-Researchers can use their own models
+The hippocampus is a key player of mnesic functions and has been shown to be implied in diverse pathologies such as mild cognitive impairment or Alzheimer's disease. Studying the anatomo-functional properties of the hippocampus and its subfields is a mandatory path to understand such conditions and requires reliable and robust segmentations of MRI data. Moreover, the growing size of publicly available datasets calls for faster and more efficient segmentation algorithms. As the current methodologies are shown to be either imprecise, slow or inconvenient, we propose a novel tool called the Hippocampal Segmentation Factory (`HSF`) to segment the hippocampal subfields in T1w or T2w MRIs.
+
+`HSF` is designed to be a fully customizable end-to-end pipeline, handling tasks from the preprocessing of raw anatomical images, to the segmentation of the subfields through specialized and highly efficient Deep Learning models on any hardware acceleration platform such as CUDA, TensorRT or OpenVINO. `HSF` also supports the state-of-the-art DeepSparse compute engine, providing GPU-class performances on CPU.
+
+Even if we use ever-improving models regularly trained with SotA methods with an increasing amount of manually labeled MRIs, we propose `HSF` as a future-proof tool where researchers can codelessly test and use their own ONNX models through a simple CLI argument.
# Statement of Need
-The hippocampus plays a major role in specific functions of the brain. Divided in multiple hippocampal subfields - namely the Cornu Ammonis, the Dentate Gyrus and the Subiculum - it is actively involved in episodic memory, learning, and decision making. Thus, those substructures are determining an important part of one's behavior during his whole lifespan from the emergence of episofic memory in children to age-dependant cognitive decline. Hippocampal subfields has been shown to be implied in pathological conditions such as Alzheimer's disease, or Temporal lobe epilepsy.
+The hippocampus plays a major role in specific functions of the brain like the episodic memory, the memory containing specific spatio-temporal details. Divided in hippocampal subfields - namely the Cornu Ammonis, the Dentate Gyrus and the Subiculum - it is actively involved in episodic memory, learning, and decision making. Thus, those substructures are determining an important part of one's behavior during his whole lifespan from the emergence of episofic memory in children to age-dependant cognitive decline. Hippocampal subfields have been shown to be implied in pathological conditions such as Alzheimer's disease, or Temporal lobe epilepsy [@todaRoleAdultHippocampal2019].
Therefore, their exist a need for a precise and accurate delineation of those subfields in order to study both healthy and pathological conditions. This delineation process appears to be challenging as the hippocampus is a small and complex structure. Even manual segmentation, still considered as a gold-standard method, is an error-prone process due to inconsistant guidelines and the need for high-definition MRIs.
-To date, there exists (semi-)automated methods for the segmentation of the hippocampal subfields (e.g. ref), but they are either slow (ref) or innacurate (ref), making them unsuited for research or clinical applications. While those methodologies are actually considered as "legacy methods" with respect to the actual literature of semantic segmentation, Deep Learning models have been validated on this complex task (ref), but they are still reserved to specific populations of researchers / engineers because either models are not public and need to be reimplemented from scratch (e.g. Zhu), or need to be re-trained because pretrained models are not made available, or because they are trained on a specific and uniform dataset, thus causing generalization issues on images acquired with different acquisition parameters (e.g. resolution, contrast, scanner).
+To date, there exists (semi-)automated methods for the segmentation of the hippocampal subfields (e.g. @yushkevichAutomatedVolumetryRegional2015, @iglesiasComputationalAtlasHippocampal2015, @romeroHIPSNewHippocampus2017), but they are either slow (e.g.: up to a day to segment a new MRI with `FreeSurfer`) or innacurate, making them unsuited for research or clinical applications. While those methodologies are actually considered as "legacy methods" with respect to the actual literature of semantic segmentation, Deep Learning models have been validated on this complex task [@qiuFeasibilityAutomaticSegmentation2019; @zhuDilatedDenseUNet2019], but they are still reserved to specific populations of researchers / engineers because either models are not public and need to be reimplemented from scratch (e.g. @zhuDilatedDenseUNet2019), or need to be re-trained because pretrained models are not made available, or because they are trained on a specific and uniform dataset, thus causing generalization issues on images acquired with different acquisition parameters (e.g. resolution, contrast, scanner).
-This lack of uniformity and ease of use of hippocampal segmentation models leaves a gap in the range of technical options available to researchers and cliniciants. By developing and published our Hippocampal Segmentation Factory (HSF), we hope to fill this gap and help the scientific community to better study the hippocampal subfields.
+This lack of uniformity and ease of use of hippocampal segmentation models leaves a gap in the range of technical options available to researchers and cliniciants. By developing and published our Hippocampal Segmentation Factory (`HSF`), we hope to fill this gap and help the scientific community to better study the hippocampal subfields.
# Segmentation Pipeline
-The HSF pipeline is constituted of 3 main steps: 1/ a preprocessing step handled by ROILoc to extract the hippocampi from a given MRI, 2/ an augmentation pipeline, and 3/ a segmentation by multiple expert models in order to produce both a segmentation and an uncertainty map (figure \ref{HSF}).
+The `HSF` pipeline is constituted of 3 main steps: 1/ a preprocessing step handled by ROILoc to extract the hippocampi from a given MRI, 2/ an augmentation pipeline, and 3/ a segmentation by multiple expert models in order to produce both a segmentation and an uncertainty map (figure \ref{HSF}).
## Hippocampal Localization and Preprocessing
-
+In order to limit the computational impact of `HSF`, we use a preprocessing step to extract the hippocampi from the MRI. This step is performed by a pipeline we called `ROILoc` (for ROI localization).
+
+To do so, ROILoc registers the `MNI152 09c Sym` template [@fonovUnbiasedNonlinearAverage2009] to the T1w or T2w input MRI. As we know the coordinates of the hippocampus in the MNI space thanks to the CerebrA atlas [@maneraCerebrARegistrationManual2020], this registration process allows us to infer rough coordinates of the hippocampus in native space. `ROILoc` then crops the MRI into two volumes corresponding to the right and left hippocampi (figure \ref{ROILoc}).
-ROILoc, ZNorm, Shape
+
+
+To finish the preprocessing, the resulting crops are Z-Normalized, and padded to obtain shapes which are multiple of 8.
## Hippocampal Subfields Segmentation
ARUNet, unstructured pruning, SWA, big databases (mix public, private), T1, T2, multi acquisition center, multi res
TTA Bagging
+SENIOR [@haegerImagingAgingBrain2020]
+SHATAU [@lagardeDistinctAmyloidTau2021]
## Postprocessing and Uncertainty Estimation
TTA vote, aleatoric uncertainty
-
# Acknowledgements
-IDRIS Genci
-
+We would like to thanks the IDRIS and the Genci who allowed us to access the HPE Jean Zay supercomputer.
# References