initial docs for templateseg (#292)

* initial docs for templateseg * added references section --------- Co-authored-by: Jordan DeKraker <[email protected]>
khanlab · May 30, 2024 · 4df2f80 · 4df2f80
1 parent 65662b2
commit 4df2f80
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 0 deletions.
diff --git a/docs/contributing/references.md b/docs/contributing/references.md
@@ -0,0 +1,11 @@
+# References
+
+If you use HippUnfold, please cite
+- DeKraker, Jordan, Roy AM Haast, Mohamed D. Yousif, Bradley Karat, Jonathan C. Lau, Stefan Köhler, and Ali R. Khan. "Automated hippocampal unfolding for morphometry and subfield segmentation with HippUnfold." elife 11 (2022): e77945.
+
+If you use a custom UNet model, template, or atlas, please cite to corresponding works:
+- Eichert, Nicole, Jordan DeKraker, Amy FD Howard, Istvan N. Huszar, Silei Zhu, Jerome Sallet, Karla L. Miller, Rogier B. Mars, Saad Jbabdi, and Boris C. Bernhardt. "Hippocampal connectivity patterns echo macroscale cortical evolution in the primate brain." bioRxiv (2023): 2023-09.
+- DeKraker, Jordan, Jonathan C. Lau, Kayla M. Ferko, Ali R. Khan, and Stefan Köhler. "Hippocampal subfields revealed through unfolding and unsupervised clustering of laminar and morphological features in 3D BigBrain." NeuroImage 206 (2020): 116328.
+
+After running HippUnfold, consider using the [HippoMaps](https://github.com/MICA-MNI/hippomaps) tools and example analyses:
+DeKraker, Jordan, Donna Gift Cabalo, Jessica Royer, Ali R. Khan, Bradley Karat, Oualid Benkarim, Raul Rodriguez-Cruces et al. "HippoMaps: Multiscale cartography of human hippocampal organization." bioRxiv (2024): 2024-02.
diff --git a/docs/index.md b/docs/index.md
@@ -27,6 +27,7 @@ getting_started/vagrant
 usage/cli
 usage/useful_options
 usage/specializedScans
+usage/templates.md
 usage/faq.md
 ```
 
@@ -62,6 +63,7 @@ outputs/QC
 :hidden:
 :maxdepth: 2
 
+contributing/references
 contributing/contributing
 ```
 

diff --git a/docs/usage/templates.md b/docs/usage/templates.md
@@ -0,0 +1,17 @@
+# Template-base segmentation
+
+Template-based segmentation can be used with the `--use-template-seg` flag instead of a deep neural network for tissue class segmentation prior to unfolding. This is the recommended workflow for non-human data.
+
+**Advantages:**
+- Relatively robust to image quality
+- Can be used without UNet training (which requires many manually segmented samples)
+- Precision can be adjusted with the `--inject_template_smoothing_factor` and `--rigid-reg-template` flags
+
+**Disadvantages:**
+- Doesn't account well for interindividual differences in folding patterns (not an issue in most non-human species where the hippocampus is relatively smooth)
+- Can still fail due to registration errors
+
+This is meant as an alternative to UNet-based tissue segmentation when only one or a few manually segmented training samples are available, which are not sufficient to train a UNet model. However, failures can still occur during this registration due to differences in image contrast and/or quality compared to the template. Adjusting the optional parameters is sufficient to solve this in most cases, but if not then you can manually register or segment your hippocampal images and then run with the `--modality segT1w`, `--modality segT2w`, or `--modality cropseg` (the latter doesn't perform any additional cropping its its recommended you crop your segmentations to improve HippUnfold processing time). 
+
+
+If you have a unique template hippocmapal segmentation (e.g. from another species or special population) then please consider making it available to other HippUnfold users! We will be happy to include it, and any associated references, if you raise a [git issue](https://github.com/khanlab/hippunfold/issues).