Pre-release

This release is a pre-release and may not be stable for production use.

CRASHS: Cortical Reconstruction for Automatic Segmentation of Hippocampal Subfields (ASHS)

CRASHS is a surface-based modeling and groupwise registration pipeline for the human medial temporal lobe (MTL). It can be used to perform groupwise analysis of pointwise measures in the MTL, such as cortical thickness, longitudinal volume change, functional MRI activation, microstructure, etc. It uses similar principles to whole-brain surface-based analysis pipelines like FreeSurfer and CRUISE, but restricted to the MTL region. CRASHS is used to postprocess the results of ASHS segmentation with certain ASHS atlases.

CRASHS overview figure

Some of the newer ASHS atlases include the white matter label, which is used by CRASHS. For other ASHS atlases, CRASHS can paint in the white matter label using nnU-Net. CRASHS uses the CRUISE technique to fit the white matter segmentation with a surface of spherical topology, and find a series of surfaces spanning between the gray/white boundary and the pial surface. The middle surface is inflated and registered to a population template, allowing surface-based analysis of MTL cortical thickness and other measures such as functional MRI and diffusion MRI.

CRUISE and the other surface-processing algorithms CRASHS uses are implemented in Java as part of the CBS Tools library developed by Pierre-Louis Bazin and colleagues at the Max Planck Institute for Human Cognitive and Brain Sciences. CRASHS calls this code directly via a small native binding (compiled ahead-of-time with GraalVM Native Image, no Java runtime required at install or run time) rather than through the NighRes software, which previously required a separate Java/JCC build step that could not be installed with pip. See THIRD_PARTY_LICENSES.md for attribution and license details for this bundled code.

The CRASHS pipeline is described in the supplemental material to our paper in the special issue of Alzheimer's and Dementia on the 20th anniversary of ADNI.

Installation using `pip`

As of the version in this repository, CRASHS no longer depends on nighres or a separately-installed Java/JVM. The cbstools algorithms CRASHS needs are compiled ahead-of-time (via GraalVM Native Image) into a native library that ships inside the crashs package itself.

Once binary wheels are published to PyPI, installing CRASHS requires no Java, JDK, or compiler of any kind — just:

pip install crashs
python3 -m crashs --help

Installing from source (development / editable install)

Building from source does require a JDK — specifically a GraalVM JDK with the native-image component (GraalVM for JDK 21+ ships this by default) — but only at build time, not at runtime or for end users installing a published wheel.

# Clone with submodules (native/cbstools-public is a git submodule)
git clone --recurse-submodules https://github.com/pyushkevich/crashs
cd crashs

# Build the native library once (requires a GraalVM JDK with native-image on PATH)
bash native/scripts/build_native.sh macos-14   # or: ubuntu-latest, windows-2022

# Regular (non-editable) install picks up the native library correctly:
pip install .

Note: pip install -e . (editable install) currently does not work for this package, because the compiled native library is only copied into the installed package location, not back into the source tree that an editable install imports from. For local development, build once as above, then manually stage the artifact into the source tree before installing editable:

mkdir -p src/crashs/_native_lib src/crashs/_native_data
cp native/build/out/libcbstools_native.* src/crashs/_native_lib/
cp -r native/data/topology_lut src/crashs/_native_data/
pip install -e .

Example installation (Ubuntu)

Our Docker script may provide hints on installing crashs and its dependencies on a modern Ubuntu system.

Installation using Docker

The CRASHS Docker container is available on DockerHub as pyushkevich/crashs:latest. Use the command below to download the container.

docker pull pyushkevich/crashs:latest

If you are using newer Mac with the ARM processor, you may need to use the -platform flag to download the container:

docker pull --platform linux/amd64 pyushkevich/crashs:latest

After pulling the Docker container, use the command below to open a bash shell in the docker container, which will allow you to execute CRASHS commands in the container. The folder /my/crashs/folder/sample_data below stands for a folder on your file system that contains ASHS outputs that you wish to process. The folder /my/crashs/folder/crashs_template_package is a folder to which CRASHS will download its template package. The first time your run CRASHS, this should be an empty folder that you create.

docker run \
    -v your_output_directory:/data \
    -v /my/crashs/folder/crashs_template_package:/package \
    -v /my/crashs/folder/sample_data:/data \
    -it pyushkevich/crashs:latest /bin/bash

Downloading CRASHS Templates and Models

Before using CRASHS, you will need to download the templates and pretrained models. The models are stored on HuggingFace at https://huggingface.co/datasets/pyushkevich/crashs_template_package, and can be downloaded to a folder on your filesystem (in the example below, /my/crashs/folder/crashs_template_package) using:

python3 -m crashs download /my/crashs/folder/crashs_template_package

If running inside of the Docker container, the command is:

python3 -m crashs download /package

The same command can be used in the future to update the template package to the latest version. It is convenienet to set the environment variable CRASHS_DATA to point to the folder where the package was downloaded:

export CRASHS_DATA=/my/crashs/folder/crashs_template_package

We recommend adding the line above that sets the CRASHS_DATA environment variable to your .bashrc, .bash_profile or .zshrc file, depending on what shell you use. Alternatively, you can invoke CRASHS below with the -C switch to provide the path to the templates and models directory.

Inputs to CRASHS

The main input to the package is the ASHS output folder. Before running CRASHS, you will need to run ASHS on your MRI scans using one of the atlases for which a CRASHS template is available.

CRASHS offers different templates for different ASHS versions. Currently, the following templates are provided:

ashs_pmc_t1: Template for the T1-weighted MRI version of ASHS T1-ASHS using the ASHS-PMC-T1 atlas. We recommend using the 2023 ASHS-PMC-T1 atlas with the white matter label. However, you can also provide segmentations created using the original ASHS-PMC-T1 atlas and the white matter label will be added to the existing segmentation automatically, using nnUNet.
ashs_pmc_t1exst: Template for the T1-weighted MRI version of ASHS T1-ASHS using the ASHS-PMC-T1ext atlas. This atlas extends the MTL cortical structures (ERC, BA35, BA36) more anteriorly and also includes the amygdala and white matter labels.
ashs_pmc_alveus: Template for the high-resolution oblique coronal T2-weighted MRI version of ASHS. This template should be used with the ASHS PMC atlas. The white matter label will be added to the existing segmentation and extended synthetically over the alveus/fimbria, as described in our ADNI 20th anniversary paper.

Running CRASHS on a sample dataset

A sample dataset is included in the sample_data folder in the repository. Download it to some folder on your system (we will use /my/crashs/folder/sample_data for this tutorial).

Instructions for Docker

Run this command inside of the container to run CRASHS on the example T1-ASHS segmentation.

python3 -m crashs fit \
    -C /package -s right -c corr_usegray \
    sample_data/ashs_pmc_t1/subj01/ashs \
    ashs_pmc_t1 \
    sample_data/ashs_pmc_t1/subj01/crashs

You should find the output from running CRASHS in folder /my/crashs/folder/sample_data/ashs_pmc_t1/subj01 on your system.

Instructions for `pip` install

If using CRASHS installed with pip and the CRASHS_DATA environment variable has been set as explained above, use the command below to run CRASHS on the on the example T1-ASHS segmentation:

python3 -m crashs fit \
    -s right -c corr_usegray \
    /my/crashs/folder/sample_data/ashs_pmc_t1/subj01/ashs \
    ashs_pmc_t1 \
    /my/crashs/folder/sample_data/ashs_pmc_t1/subj01/crashs

You should find the output from running CRASHS in folder /my/crashs/folder/sample_data/ashs_pmc_t1/subj01/crashs.

T2 Example

Another example in the sample_data folder can be used to test CRASHS for T2-weighted MRI processed with the ASHS-PMC atlas. It is better to run this example on a machine with an NVidia GPU because a nnU-Net is used by CRASHS to generate the white matter label; otherwise expect it to take 30-60 minutes to complete. If using Docker, include the flag --gpus all when calling the docker run command to make the GPU available to the container.

You can run the example in the Docker container like this:

python3 -m crashs fit -C /package -s left -c heur \
    /data/ashs_pmc_alveus/subj02/ashs \
    ashs_pmc_alveus \
    /data/ashs_pmc_alveus/subj02/crashs

Or using CRASHS pip install like this:

python3 -m crashs fit -s left -c heur \
    /my/crashs/folder/sample_data/ashs_pmc_alveus/subj02/ashs \
    ashs_pmc_alveus \
    /my/crashs/folder/sample_data/ashs_pmc_alveus/subj02/crashs

Outputs from CRASHS

The program generates many outputs, but the most useful ones are:

thickness/[ID]_template_thickness.vtk: a mesh with same number of vertices and faces as the CRASHS template that has been fitted to the mid-surface of the cortex and that contains point array VoronoiRadius that estimates half-thickness of the cortex at each vertex. This is the main output to use for downstream statistical analysis. Additionally, array plab contains the posterior probability of each anatomical label defined in the template. Value 0 corresponds to the white matter, and thickness values there should be ignored (most of them will be NaN anyway). These meshes can be used for groupwise analysis of cortical thickness.
thickness/[ID]_thickness_roi_summary.csv: Mean and median of the VoronoiRadius array in thickness/[ID]_template_thickness.vtk integrated over ROIs defined in the template.
fitting/[ID]_fitted_omt_match_to_p00.vtk ... fitting/[ID]_fitted_omt_match_to_p09.vtk: these meshes are similar to thickness/[ID]_template_thickness.vtk in that they represent the template's geometry fitted to the subject's cortex, but they are fitted to different layers: 00 corresponds to the gray-white surface and 09 to the pial surface. These meshes can be used to sample data from the cortex in subject space (fMRI, NODDI, etc) into template space for group analysis

The following files can be used to check how well the fitting between the inflated template mid-surface and the inflated subject mid-surface worked.

fitting/[ID]_fit_target_reduced.vtk: this is the inflated and sub-sampled mid-surface mesh of the subject, affine transformed into the space of the inflated template. Each triangle is associated with an anatomical label.
fitting/[ID]_fitted_lddmm_template.vtk: this is the inflated template warped to optimally match the mesh above. The fit is not perfect but should be close.
fitting/[ID]_fitted_dist_stat.json: distance statistics of the fitting, including average, max, and 95th percentile of the distance. Useful to check for poor fitting results.

CRASHS command-line parameters

Run python3 -m crashs fit --help to print the command-line parameters.

One set of parameters is used to specify which ASHS output should be used for fitting the geometrical representation:

-s {left,right} is used to specify the side of the brain that should be fitted
-f {multiatlas,bootstrap} is used to specify whether to use the ASHS output from the initial multi-atlas stage or the second bootstrap stage. Typically the bootstrap stage segmentation is better (accuracy is higher, on average, in ASHS validation experiments), so the default setting of bootstrap should be used.
-c {heur,corr_usegray,corr_nogray} is used to specify which correction mode in ASHS should be used. The heur mode does not use any pixel-level machine learning correction and typically corresponds to smoothest shape segmentations. If the data on which you run ASHS is not well matched to the data on which ASHS was trained, it is best to use the heur option. The corr_usegray mode uses pixel-level machine learning correction, and in our validation experiments, has highest accuracy, but only if the data being segmented is similar to the training data (similar MRI protocol, age, etc.). Finally corr_nogray is an intermediate option that is rarely used.

The other parameters you may need to set are -i (specify the ID of the subject, used as a prefix in CRASHS output files), -d (specifies the device to use for PyTorch, e.g., cuda0 if you have an NVidia GPU, cpu otherwise, and -C (to point to the templates and models folder if you didn't set the CRASHS_DATA environment variable).

The options starting with --skip are used to skip certain steps when re-running CRASHS in the same folder. They are mostly used for debugging.

Citations

Yushkevich PA, Ittyerah R, Li Y, et al. Morphometry of medial temporal lobe subregions using high-resolution T2-weighted MRI in ADNI3: Why, how, and what's next? Alzheimer's Dement. 2024; 20: 8113–8128. https://doi.org/10.1002/alz.14161
PA Yushkevich, L Xie, LEM Wisse, et al., Mapping Medial Temporal Lobe Longitudinal Change in Preclinical Alzheimer’s Disease, 2023 Alzheimer's Association International Conference (AAIC 2023).

Troubleshooting

If you get intermittent crashes, particularly in parallel environments, try setting the following environment variables before running CRASHS:

# Use a dedicated cache folder for PyKeops. This prevents parallel
# jobs from writing to the same cache folder concurrently. This will
# result in a small performance hit, and is really meant for clusters.
# (replace /scratch with your preferred temp directory)
export KEOPS_CACHE_FOLDER=$(mktemp -d /scratch/keops_cache_XXXXXX)

# This fixed a hard to track down double-free bug somewhere in the optimal
# mass transport code that would occur only some of the time and only when
# using the CPU. The bug is still lurking there somewhere...
export PYTHONMALLOC=malloc

If you get an error ImportError: cannot import name 'crashs_main' from 'crashs', it's likely due to a missing/misconfigured package that CRASHS depends on. Use the command below to get more detailed information.

python -c 'from crashs.crashs import *'

Development Status
- 4 - Beta
Intended Audience
- Science/Research
License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3
Topic
- Scientific/Engineering :: Medical Science Apps.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

crashs-0.3.0a1-cp313-cp313-win_amd64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.13Windows x86-64

crashs-0.3.0a1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

crashs-0.3.0a1-cp313-cp313-macosx_11_0_arm64.whl (8.2 MB view details)

Uploaded Sep 8, 2026 CPython 3.13macOS 11.0+ ARM64

crashs-0.3.0a1-cp313-cp313-macosx_10_9_x86_64.whl (8.3 MB view details)

Uploaded Sep 8, 2026 CPython 3.13macOS 10.9+ x86-64

crashs-0.3.0a1-cp312-cp312-win_amd64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.12Windows x86-64

crashs-0.3.0a1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

crashs-0.3.0a1-cp312-cp312-macosx_11_0_arm64.whl (8.2 MB view details)

Uploaded Sep 8, 2026 CPython 3.12macOS 11.0+ ARM64

crashs-0.3.0a1-cp312-cp312-macosx_10_9_x86_64.whl (8.3 MB view details)

Uploaded Sep 8, 2026 CPython 3.12macOS 10.9+ x86-64

crashs-0.3.0a1-cp311-cp311-win_amd64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.11Windows x86-64

crashs-0.3.0a1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

crashs-0.3.0a1-cp311-cp311-macosx_11_0_arm64.whl (8.2 MB view details)

Uploaded Sep 8, 2026 CPython 3.11macOS 11.0+ ARM64

crashs-0.3.0a1-cp311-cp311-macosx_10_9_x86_64.whl (8.3 MB view details)

Uploaded Sep 8, 2026 CPython 3.11macOS 10.9+ x86-64

crashs-0.3.0a1-cp310-cp310-win_amd64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.10Windows x86-64

crashs-0.3.0a1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.4 MB view details)

Uploaded Sep 8, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

crashs-0.3.0a1-cp310-cp310-macosx_11_0_arm64.whl (8.2 MB view details)

Uploaded Sep 8, 2026 CPython 3.10macOS 11.0+ ARM64

crashs-0.3.0a1-cp310-cp310-macosx_10_9_x86_64.whl (8.3 MB view details)

Uploaded Sep 8, 2026 CPython 3.10macOS 10.9+ x86-64

File details

Details for the file crashs-0.3.0a1-cp313-cp313-win_amd64.whl.

File metadata

Download URL: crashs-0.3.0a1-cp313-cp313-win_amd64.whl
Upload date: Sep 8, 2026
Size: 8.4 MB
Tags: CPython 3.13, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for crashs-0.3.0a1-cp313-cp313-win_amd64.whl
Algorithm	Hash digest
SHA256	`2089f00f09cb16fbf886c870cd5402870070762971b4b3f5b44dacf67f458e3b`
MD5	`dec21a8f98e78ce87977fa52b05f689e`
BLAKE2b-256	`f2e1f817f39c081099790ad32ae588aa05b5a27df9582a4fff9b4df5dec758a7`

Algorithm	Hash digest
SHA256	`2c45ffc9e28e864f11fb4d7c96349fc0f7704acd16df1e118b61c561950b7213`
MD5	`37ef9a4f88bbef0ce960dbcfcd833433`
BLAKE2b-256	`e6c6c5f13d0d4c906638d56dcbc81f7a5ff703cd0906bfe208c24bc3904185ca`

Algorithm	Hash digest
SHA256	`8d67820bd1c270fb597f885a6a302be47a0bdd3123d3963463443974609d7834`
MD5	`69f2f732d68d94db97b2da017ba8016a`
BLAKE2b-256	`e6857cb66b7b1750ad9b6ac6e5a0ad5ab843c3edc295ff09348598ce9042aed0`

Algorithm	Hash digest
SHA256	`a9ff8ec8ffe10198b39c132d9134946e456b9aed702288f6ffa9b25bf30b788b`
MD5	`1711d73edca8358f366b025a4742889c`
BLAKE2b-256	`1803bfce696be61b99dcc23c41b70781b36f1e493440b4bbe57e4bf5980aa242`

Algorithm	Hash digest
SHA256	`4c778544ca0265f729d392d4d32f8c1a22d71effb08e9eb069e58cbd36385f3d`
MD5	`5115f857c46860ad581c68b9935e2ab9`
BLAKE2b-256	`8faebe3fd72f3f5f62c8413e5c9262a017092dba9901e8d9299f91d61cff7241`

Algorithm	Hash digest
SHA256	`853f789ae9c9db645b90245822a79a021cda6a7062a18324a43e494909799776`
MD5	`d408716fe079090b7d24532b9c1fad03`
BLAKE2b-256	`97f986c2930b5319dbe25f1d805c62b4bf6379e2d782db468f11c793f8ad0dab`

Algorithm	Hash digest
SHA256	`850cfeddb198f383496e0a28a3e7b75768dc37a114264655e8432c672fa617e6`
MD5	`246f18fae682222f384ba79b3534c6d6`
BLAKE2b-256	`2a663025175bd401c0e8949b9a4e283209194ab59e47a378efdcfdfa9f978198`

Algorithm	Hash digest
SHA256	`f6d14dec8afc24c47f5682e3b7dca5b039959a07b6546a18c03f94bc9d4a1ee7`
MD5	`b998b524432a90efec539d7bdd145502`
BLAKE2b-256	`f201de51c8070887965ef499d9d3b18b667e972061caa77324a0fb508474e38a`

Algorithm	Hash digest
SHA256	`2b145b1094205f6903b1366c131fdaeb9fb28888d9c9616d401375d68d90c122`
MD5	`3d33f89636b0ac96cf8443377b8d224c`
BLAKE2b-256	`84dcdcc20569f0efe6c47b5550f7bc9a976397a742f5949431521866cf7b4202`

Algorithm	Hash digest
SHA256	`df9fe96f15823b4eaf940d33efa23a2c968a568de9191297d310636e581bc241`
MD5	`e1a379c00912b9fcd0643b8c0324de2d`
BLAKE2b-256	`7138a98f2447e3853979c5b90caf4138687a5ad23149b635cf41e1ca2d1d5042`

Algorithm	Hash digest
SHA256	`f991d3314b1170227b9988d32d0ca5e4a4aefd7442f9ccd131baa6fc34782990`
MD5	`6b18f49dfb712815141a6321971be347`
BLAKE2b-256	`a68842b0a0d82a67a521b1253d268df83a0f315f35fc80924e3fb16f64e2d9e5`

Algorithm	Hash digest
SHA256	`f9f18c36cdf43baaecec4394194459e36800850c91ff395dbf836f47a3799664`
MD5	`c78795471826dcf176febc7d7f58a01f`
BLAKE2b-256	`7d0da42ba0d54a1ffb9920c3d29ff44cbcff01fea656669f9785dd2ac1f374ea`

Algorithm	Hash digest
SHA256	`6342b442014357f51e635bdba0b4262423b665504d1d1e3d8169217f818dd46d`
MD5	`fef923f8ecf91ac836f61201715ad926`
BLAKE2b-256	`1e98107f9fc07909ba0bf3f588be1829a05a0d6d64550d57a2da25e59bc48cc0`

Algorithm	Hash digest
SHA256	`70204b0957e434bc7adb22a3e90f33a51da9bd28712b4913305b4d5a5429fb08`
MD5	`bbde43db85fe48a66acd8d2e39e88efc`
BLAKE2b-256	`a0214cbc07b16a475d765fcac91792b4fa15f8dc82a73ca4151cc4c0c2e873c2`

Algorithm	Hash digest
SHA256	`1167f35d58af7a65da05dd926b197e5279a620728be2210b881860481b6ae944`
MD5	`0306d74ae5574d0c3e59de772db9562a`
BLAKE2b-256	`9b3479ad25a8abfcd75d3f4527a69ad9ae949e036f51dee198f5fc5b084954ac`

Algorithm	Hash digest
SHA256	`0f9d8a855cec8fa75a618af772220dd55c29552fafae6ade0345f7f580bc8369`
MD5	`3df0e7ae3782b434b11ab2cb1f195049`
BLAKE2b-256	`dc0dcc7fe34f898735457839cd3437fe76b62179ac425f8acb89617d68e8cf47`

crashs 0.3.0a1

CRASHS: Cortical Reconstruction for Automatic Segmentation of Hippocampal Subfields (ASHS)

Installation using pip

Installing from source (development / editable install)

Example installation (Ubuntu)

Installation using Docker

Downloading CRASHS Templates and Models

Inputs to CRASHS

Running CRASHS on a sample dataset

Instructions for Docker

Instructions for pip install

T2 Example

Outputs from CRASHS

CRASHS command-line parameters

Citations

Troubleshooting

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

Installation using `pip`

Instructions for `pip` install