HIPpocampal Shape and Thickness Analysis - HIPSTA

Purpose:

This repository contains a collection of scripts for hippocampal shape and thickness analysis as described in our recent publication.

Description:

The main analysis script performs the following major processing steps:

0. preprocess image (cropping, upsampling, automask)
1. create labels
   1. extract HSF labels from label image
   2. merge individual labels
2. attach molecular layer to neighboring regions (if present)
3. create mask
   1. fill holes using dilation and erosion
   2. create final mask
4. create surface
   1. create initial surface using marching cube algorithm
   2. topology fixing (optional)
   3. smooth (fixed) surface
   4. remesh surface (optional)
5. create tetrahedral mesh from triangular surface
6. create label files for tetra mesh
7. remove boundary mask (preprocessing for mesh cutting)
8. cut open tetrahedral mesh at anterior and posterior ends
9. create cube parametrization
10. compute thickness and curvature
11. map subfield values (and other volume-based data)
12. create supplementary files for visualization

Current status and future development:

The hippocampal shape and thickness analysis package is currently in its beta stage, which means that it's open for testing, but may still contain unresolved issues. Future changes with regard to the algorithms, interfaces, and package structure are to be expected.

In the near future, we anticipate the following changes and additions:

• improved documentation including walk-through examples
• improved interfaces and installation options; availability as a python package
• provision of Docker and/or Singularity files to avoid issues with differences in dependencies and enviroments

Usage:

python3 shapetools.py --filename <filename> --hemi <hemi> --lut <lookup-table> [--outputdir <OUTDIR>] [further options]

Example:

python3 shapetools.py --filename /my/segmentation/file --hemi lh --lut fs711 --outputdir /my/output/directory

Outputs:

1. The primary output are thickness values that will be computed and stored as CSV or PSOL or MGH overlay files within the 'thickness' folder. The PSOL or MGH files can be overlaid onto the mid-surface vtk file that is also found within the 'thickness' folder.

2. Intermediate volume and surface files, each prefixed with the particular operation performed. The basic pattern for the filenames is:

   <hemisphere>.<prefixes>.<hsf-labels>.<suffixes>

3. Several folders with intermediate results

Supported segmentations:

• If using the ashs segmentation, additional labels for the hippocampal head (label value: 20) and tail (label value: 5) labels are recommended.
• Topological fixing (--topological-fixing <filename1> <filename2>) should not be used unless working with FreeSurfer-processed data. <filename1> is the brain.mgz file and <filename2> is the wm.mgz file, both found within the mri subdirectory of an individual FreeSurfer output directory.
• If using a custom look-up table (--lut <filename>), the expected format for the file is: <numeric ID> <name> <R> <G> <B> <A>. <R>, <G>, <B>, <A> are numerical values for RGB colors and transparency (alpha) and will be ignored. For example, 236 Subiculum 255 0 0 0. Each line may only contain a single anatomical structure. Do not use a header line. The following labels need to be present in the look-up table: presubiculum, subiculum, ca1, ca2, ca3, ca4, head, and tail. Additional labels may be present, but will be ignored. Lines starting with # will be ignored (and can be used for comments).
• Multiple substructures can have the same numeric ID, e.g. presubiculum and subiculum can have the same numeric ID if these substructures are not distinguished in the segmentation. The head and tail subregions can have multiple labels if these are distinguished in the segmentation, but should be combined for the processing within the hippocampal shapetools.

Installation:

Use the following code to download this package from its GitHub repository:

git clone https://github.com/Deep-MI/Hipsta.git

You can use the following code to install the required Python depencies:

pip install -r requirements.txt

It is recommended to run this pipeline within its own virtual environment.

Requirements:

1. A FreeSurfer version (6.x or 7.x) must be sourced, i.e. FREESURFER_HOME must exist as an environment variable and point to a valid FreeSurfer installation.

2. A hippocampal subfield segmentation created by FreeSurfer 7.11 or later or the ASHS software. A custom segmentation is also permissible (some restrictions and settings apply; see Supported Segmentations).

3. Python 3.5 or higher including the lapy, numpy, scipy, nibabel, pyvista, and pyacvd libraries, among others. See requirements.txt for a full list.

4. The gmsh package (verson 2.x; http://gmsh.info) must be installed. Can be downloaded e.g. as binaries for linux or MacOSX . The 'gmsh' binary must be on the $PATH:

   export PATH=${PATH}:/path/to/gmsh-directory/bin

5. The PYTHONPATH environment variable should include the toolbox directory:

   export PYTHONPATH=${PYTHONPATH}:/path/to/hipsta-package

References:

Please cite the following publications if you use these scripts in your work:

• Diers, K., Baumeister, H., Jessen, F., Düzel, E., Berron, D., & Reuter, M. (2023). An automated, geometry-based method for hippocampal shape and thickness analysis. Neuroimage, 276:120182. doi: 10.1016/j.neuroimage.2023.120182.

Please also consider citing the these publications:

• Geuzaine, C., & Remacle, J.-F. (2009). Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities. International Journal for Numerical Methods in Engineering, 79, 1309-1331.

• Andreux, M., Rodola, E., Aubry, M., & Cremers, D. (2014). Anisotropic Laplace-Beltrami operators for shape analysis. In European Conference on Computer Vision (pp. 299-312). Springer, Cham.

• Iglesias, J. E., Augustinack, J. C., Nguyen, K., Player, C. M., Player, A., Wright, M., ... & Fischl, B. (2015). A computational atlas of the hippocampal formation using ex vivo, ultra-high resolution MRI: application to adaptive segmentation of in vivo MRI. Neuroimage, 115, 117-137.

• Yushkevich, P. A., Pluta, J., Wang, H., Ding, S.L., Xie, L., Gertje, E., Mancuso, L., Kliot, D., Das, S. R., & Wolk, D.A. (2015). Automated Volumetry and Regional Thickness Analysis of Hippocampal Subfields and Medial Temporal Cortical Structures in Mild Cognitive Impairment. Human Brain Mapping, 36, 258-287.