From eec62a57484c23398cf9948e0d1d3b529debdfef Mon Sep 17 00:00:00 2001
From: Jordan DeKraker <jordan.dekraker@mail.mcgill.ca>
Date: Wed, 29 May 2024 12:27:03 -0400
Subject: [PATCH 1/2] initial docs for templateseg

---
 docs/index.md           |  1 +
 docs/usage/templates.md | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)
 create mode 100644 docs/usage/templates.md

diff --git a/docs/index.md b/docs/index.md
index 68455213..fc0f14e5 100644
--- 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
 ```
 
diff --git a/docs/usage/templates.md b/docs/usage/templates.md
new file mode 100644
index 00000000..ed577332
--- /dev/null
+++ 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). 

From 15d2681721648131ba1465af81b0c6d179b2d570 Mon Sep 17 00:00:00 2001
From: Jordan DeKraker <jordan.dekraker@mail.mcgill.ca>
Date: Wed, 29 May 2024 12:46:39 -0400
Subject: [PATCH 2/2] added references section

---
 docs/contributing/references.md | 11 +++++++++++
 docs/index.md                   |  1 +
 2 files changed, 12 insertions(+)
 create mode 100644 docs/contributing/references.md

diff --git a/docs/contributing/references.md b/docs/contributing/references.md
new file mode 100644
index 00000000..2427d099
--- /dev/null
+++ 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
index fc0f14e5..f61f7ba9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -63,6 +63,7 @@ outputs/QC
 :hidden:
 :maxdepth: 2
 
+contributing/references
 contributing/contributing
 ```