Metadata-Version: 2.3
Name: crashs
Version: 0.2.2
Summary: CRASHS: Cortical Reconstruction for Automated Segmentation of Hippocampal Subfields (ASHS)
Project-URL: Homepage, https://github.com/pyushkevich/crashs
Author-email: Paul Yushkevich <pyushkevich@gmail.com>
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Requires-Dist: geomloss
Requires-Dist: monai
Requires-Dist: nnunetv2
Requires-Dist: numpy
Requires-Dist: picsl-c3d>=1.4.2.1
Requires-Dist: picsl-cmrep>=1.0.2.0
Requires-Dist: picsl-greedy>=0.0.5
Requires-Dist: pykeops
Requires-Dist: pymeshlab
Requires-Dist: simpleitk
Requires-Dist: statsmodels
Requires-Dist: torch
Requires-Dist: vtk
Description-Content-Type: text/markdown

# 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 is used to postprocess the results of [ASHS](https://github.com/pyushkevich/ashs) segmentation with ASHS atlases that contain a white matter label. CRASHS uses the [CRUISE](https://doi.org/10.1016/j.neuroimage.2004.06.043) technique implemented in the [NighRes software](https://nighres.readthedocs.io/en/latest/) 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. 

## Inputs
The main input to the package is the ASHS-T1 output folder. ASHS should be run using the new [ASHS-T1 atlas with the white matter label](https://www.nitrc.org/frs/downloadlink.php/13554).

## Outputs
The program generates many outputs, but the most useful ones are:
* `fitting/[ID]_fitted_omt_hw_target.vtk`: the grey/white and grey/csf boundaries estimated by the `cruise_cortex_extraction` module of NighRes. These meshes are in physical (RAS) coordinate space, not in voxel (IJK) space output by Nighres. *If you extract meshes from the T1-ASHS segmentation in ITK-SNAP, those should line up with these meshes.*

* `fitting/[ID]_fitted_omt_hw_target.vtk`: the mid-surface of the gray matter estimated by the `volumetric_layering` module of NighRes. Also in RAS space.

* `fitting/[ID]_fitted_omt_match_to_hw.vtk`: the template mesh projected onto the mid-surface surface, also in RAS space. This should have the same geometry as the mid-surface, but the same number of vertices/faces as the template. This mesh will also have scalar arrays for the anatomical label and other features from the template, such as template curvature (useful for visualization). **This mesh can be used to map data from subject space (thickness, 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`: 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`: 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.

* `thickness/[ID]_template_thickness.vtk`: a mesh with same geometry as the template that has a point array `VoronoiRadius` containing half-thickness of the gray matter at each vertex.

## Installation: pip

CRASHS requires the `nighres` package, which cannot be installed with `pip`. To install `nighres`, please follow the [installation instructions](https://nighres.readthedocs.io/en/latest/). To our knowledge, ARM64 architecture is currently not supported.

Once `nighres` is installed, you can install CRASHS:

```sh
pip install crashs
```

Or, if you want to run the latest development code:

```sh
git clone https://github.com/pyushkevich/crashs
cd crashs
pip install .
```

## Docker
This repository includes the CRASHS scripts and a `Dockerfile`. The official container on DockerHub is labeled `pyushkevich/crashs:latest`

```sh
docker run -v your_data_directory:/data -it pyushkevich/crashs:latest /bin/bash
python3 -m crashs --help
```

A sample dataset is also provided and can be processed as follows (also see `run_sample.sh`)

```sh
docker run -v your_data_directory:/data -it pyushkevich/crashs:latest /bin/bash
python3 -m crashs -s right -r 0.1 sample_data/035_S_4082_2011-06-28 templates/crashs_template_01 /data/test
```

## Citation
* PA Yushkevich, L Xie, LEM Wisse, M Dong, S Ravikumar, R Ittyerah,  R de Flores, SR Das, DA Wolk for the Alzheimer’s Disease Neuroimaging Initiative (ADNI), Mapping Medial Temporal Lobe Longitudinal Change in Preclinical Alzheimer’s Disease, 2023 Alzheimer's Association International Conference (AAIC 2023).


    
