From 4df2f80153f045a607f8fcbbe11d42025314157f Mon Sep 17 00:00:00 2001 From: Jordan DeKraker Date: Thu, 30 May 2024 09:42:20 -0400 Subject: [PATCH] initial docs for templateseg (#292) * initial docs for templateseg * added references section --------- Co-authored-by: Jordan DeKraker --- docs/contributing/references.md | 11 +++++++++++ docs/index.md | 2 ++ docs/usage/templates.md | 17 +++++++++++++++++ 3 files changed, 30 insertions(+) create mode 100644 docs/contributing/references.md create mode 100644 docs/usage/templates.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 68455213..f61f7ba9 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 ``` @@ -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 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).