General maintenance, enhance editing options, and introduce additional processing variants including cortical areas

.github/workflows/build.yml

@@ -15,7 +15,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu, macos, windows]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     name: ${{ matrix.os }} - py${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}-latest
     defaults:

README.md

@@ -11,7 +11,7 @@ hippocampal shape and thickness analysis as described in our recent [publication
 
 Please see the [documentation pages](https://deep-mi.org/hipsta/dev/index.html) for a general overview, usage information and
 examples, and output description. Brief usage information is also available [here](hipsta/doc/DOCUMENTATION.md).
-Some suggestions for running the script can be found in the [tutorial](TUTORIAL.md).
+Some suggestions for running the script can be found in the [tutorial](https://deep-mi.org/hipsta/dev/tutorials/index.html).
 
 
 ## Current status:
@@ -75,7 +75,7 @@ exist as an environment variable and point to a valid FreeSurfer installation.
 or the ASHS software. A custom segmentation is also permissible (some restrictions
 and settings apply; see [Supported Segmentations](https://github.com/Deep-MI/Hipsta#supported-segmentations)).
 
-3. Python 3.8 or higher including the lapy, numpy, scipy, nibabel, pyvista, and
+3. Python 3.10 or higher including the lapy, numpy, scipy, nibabel, pyvista, and
 pyacvd libraries, among others. See `requirements.txt` for a full list, and use
 `pip install -r requirements.txt` to install.
 

TUTORIAL.md

@@ -239,9 +239,9 @@ argument.
 
 Since no explicit labels for the hippocampal head are present in ASHS 
 segmentations, it will be necessary to use the `--automask-head` flag and 
-optionally also the `--automask-tail-margin` argument. If the identification of 
-the boundary between hippocampal body tail does not work well given the existing 
-labels, using the `--automask-tail` flag and optionally the `--automask-head-margin` 
+optionally also the `--automask-head-margin` argument. If the identification of 
+the boundary between hippocampal body and tail does not work well given the existing 
+labels, using the `--automask-tail` flag and optionally the `--automask-tail-margin` 
 argument may be advised as well.
 
 ### Additional arguments for ASHS and FreeSurfer segmentations
@@ -264,10 +264,10 @@ The primary output of the hippocampal shape and thickness analysis are surface
 files and associated thickness values in the `thickness` folder. The estimated 
 hippocampal thickness values will be stored in csv tables:
 
-| Filenane                                           | Contents                                                  |
+| Filename                                           | Contents                                                  |
 |----------------------------------------------------|-----------------------------------------------------------|
 | `lh.grid-segments-x.csv`, `rh.grid-segments-x.csv` | Length estimates in the medial-to-lateral dimension       |
-| `lh.grid-segments-y.csv`, `rh.grid-segments-y.csv` | Length estimates in the medial-to-lateral dimension       |
+| `lh.grid-segments-y.csv`, `rh.grid-segments-y.csv` | Length estimates in the posterior-to-anterior dimension   |
 | `lh.grid-segments-z.csv`, `rh.grid-segments-z.csv` | Thickness estimates in the exterior-to-interior dimension |
 
 Here, x corresponds to the medial-->lateral dimension, y to the 
@@ -303,6 +303,57 @@ provided for interior, mid, and exterior surfaces:
 | `<lh\|rh>.<int\|mid\|ext>-surface.<mean\|gauss>-curv.mgh` | Overlays of mean and gaussian curvature estimtes for corresponding surfaces | 
 
 
+## Extensions to parahippocampal and entorhinal cortex
+
+The Penn ABC-3T ASHS atlas includes several labels beyond the hippocampus, 
+including parahippocampal, entorhinal, BA35, and BA36 regions. The analysis can 
+extended to parts of these regions as well. The corresponding processing 
+variants can be called with the `--lut ashs-penn_abc_3t_t2_ext` and `--lut ashs-penn_abc_3t_t2_ent` 
+arguments. The former will add (parts of) parahippocampal and entorhinal cortex 
+as well as BA35 to the analysis, but still restrict the analysis to the 
+hippocampal body region along the longitudinal axis.
+The latter will perform a separate analysis of the entorhinal cortex. Due to 
+more complex or variable anatomy, these approaches should to some extent be 
+considered experimental and may require additional QC or manual edits.
+
+The expected output when using `--lut ashs-penn_abc_3t_t2_ext` is shown in the 
+following figure; it is simply an extension of the analysis beyond the 
+subiculum and presubiculum into the cortex. 
+
+![](images/scaled/ctx-01.png)
+
+A potential issue that might arise in this analysis could be due to large shifts 
+between segmentations in successive slices, especially for anisotropic voxel 
+sizes, leading to holes in the surface mesh. Another potential issue is too close 
+proximity of the subiculum / CA1 and cortical regions so that the surface mesh 
+will incorrectly create a connection. Manual edits or changing the 
+spatial filter settings may help resolving these issues (see the following 
+section on Troubleshooting for details).
+
+![](images/scaled/ctx-03a.png)
+![](images/scaled/ctx-03b.png)
+![](images/scaled/ctx-03c.png)
+![](images/scaled/ctx-02.png)
+
+The expected output when using `--lut ashs-penn_abc_3t_t2_ent` is shown below. 
+Here, we leave out the hippocampal labels and restrict the analysis the 
+complete entorhinal cortex segmentation.
+
+![](images/scaled/erc-01a.png)
+![](images/scaled/erc-01b.png)
+![](images/scaled/erc-01c.png)
+
+Care should be taken that the entorhinal cortex is cut across its full extent 
+at its anterior and posterior ends. The left figure shows to conservative 
+cutting, the middle and right figure more appropriate cuts. Cutting can be 
+adjusted using the `--cut-range` and `--automask-head-margin` / `--automask-tail-margin` 
+arguments (see the following section on Troubleshooting for details).
+
+![](images/scaled/erc-02a.png)
+![](images/scaled/erc-02b.png)
+![](images/scaled/erc-02c.png)
+
+
 ## Troubleshooting
 
 ### Logfiles

VERSION

@@ -1 +1 @@
-0.9.1.3
+0.10.0

doc/tutorials/index.md

@@ -1,5 +1,3 @@
-=======
-
 ```{include} ../../TUTORIAL.md
 :relative-images:
 ```

hipsta/cfg/atlases.py

@@ -26,7 +26,7 @@ def get_atlases(lut):
 
         LUTINDEX = [226, [233, 235, 237, 239, 245], 234, 236, 238, 240, 240, 242, 244, 246]
 
-        LUTDICT = dict(zip(LUTLABEL, LUTINDEX))
+        LUTDICT = dict(zip(LUTLABEL, LUTINDEX, strict=True))
 
         HSFLIST = [234, 236, 238, 240, 246]
 
@@ -37,7 +37,7 @@ def get_atlases(lut):
 
         LUTINDEX = [226, [233, 235, 237, 239, 245], 234, 236, 238, 240, 240, 242, 244]
 
-        LUTDICT = dict(zip(LUTLABEL, LUTINDEX))
+        LUTDICT = dict(zip(LUTLABEL, LUTINDEX, strict=True))
 
         HSFLIST = [234, 236, 238, 240]
 
@@ -63,10 +63,62 @@ def get_atlases(lut):
 
         LUTINDEX = [1, 2, 4, 3, 3, 5, 8, 8, 9, 10, 11, 12, 20, 5]
 
-        LUTDICT = dict(zip(LUTLABEL, LUTINDEX))
+        LUTDICT = dict(zip(LUTLABEL, LUTINDEX, strict=True))
 
         HSFLIST = [8, 1, 2, 4]
 
+    elif lut == "ashs-penn_abc_3t_t2_ent":
+        LOGGER.info("Found internal, modified look-up table for the Penn ABC-3T ASHS Atlas for T2-weighted MRI.")
+
+        LUTLABEL = [
+            "ca1",
+            "ca2",
+            "ca3",
+            "ca4",
+            "dg",
+            "tail_orig",
+            "subiculum",
+            "presubiculum",
+            "entorhinal",
+            "ba35",
+            "ba36",
+            "parahippocampal",
+            "head",
+            "tail",
+        ]
+
+        LUTINDEX = [1, 2, 4, 3, 3, 5, 8, 8, 9, 10, 11, 12, 20, 5]
+
+        LUTDICT = dict(zip(LUTLABEL, LUTINDEX, strict=True))
+
+        HSFLIST = [9]
+
+    elif lut == "ashs-penn_abc_3t_t2_ext":
+        LOGGER.info("Found internal, modified look-up table for the Penn ABC-3T ASHS Atlas for T2-weighted MRI.")
+
+        LUTLABEL = [
+            "ca1",
+            "ca2",
+            "ca3",
+            "ca4",
+            "dg",
+            "tail_orig",
+            "subiculum",
+            "presubiculum",
+            "entorhinal",
+            "ba35",
+            "ba36",
+            "parahippocampal",
+            "head",
+            "tail",
+        ]
+
+        LUTINDEX = [1, 2, 4, 3, 3, 5, 8, 8, 9, 10, 11, 12, 20, 5]
+
+        LUTDICT = dict(zip(LUTLABEL, LUTINDEX, strict=True))
+
+        HSFLIST = [12, 10, 9, 8, 1, 2, 4]
+
     elif lut == "ashs-umcutrecht_7t":
         LOGGER.info("Found internal, modified look-up table for ASHS UMC Utrecht 7T atlas.")
 
@@ -86,7 +138,7 @@ def get_atlases(lut):
 
         LUTINDEX = [1, 2, 2, 3, 4, 5, 6, 5, 7, 8, 20]
 
-        LUTDICT = dict(zip(LUTLABEL, LUTINDEX))
+        LUTDICT = dict(zip(LUTLABEL, LUTINDEX, strict=True))
 
         HSFLIST = [2, 3, 4, 6]
 
@@ -105,7 +157,7 @@ def get_atlases(lut):
 
         lut = lut[lut[1].str.lower().isin(["presubiculum", "subiculum", "head", "tail", "ca1", "ca2", "ca3", "ca4"])]
 
-        LUTDICT = dict(zip(lut[1], lut[0]))
+        LUTDICT = dict(zip(lut[1], lut[0], strict=True))
 
         HSFLIST = list(lut[1])
 
@@ -121,6 +173,7 @@ def get_atlases(lut):
     LUTDICT["bndtail"] = 2260
     LUTDICT["bndhead"] = 2320
     LUTDICT["bndca4"] = 2420
+    LUTDICT["bndba35"] = 100
 
     # return
 

hipsta/cfg/config.py

@@ -1,5 +1,5 @@
 """
-This module provides configuration defaults for the hippocampal shape and 
+This module provides configuration defaults for the hippocampal shape and
 thickness analysis package.
 
 """
@@ -10,6 +10,8 @@ def get_defaults(x):
         # note: if changing these values, remember to adjust the argparse help
         # messages as well as the run_hipsta docstring also
         # options
+        start_with_edited_labels=False,
+        start_with_edited_masks=False,
         no_cleanup=False,
         no_crop=False,
         upsample=False,