hyperresashs 1.0.0__tar.gz

hyperresashs-1.0.0/PKG-INFO

@@ -0,0 +1,376 @@
+Metadata-Version: 2.4
+Name: hyperresashs
+Version: 1.0.0
+Summary: Isotropic segmentation pipeline for MTL subregions from multi-modality 3T MRI
+Author: Yue Li, PATCHLab, University of Pennsylvania
+Author-email: Paul Yushkevich <pyushkevich@gmail.com>
+Project-URL: repository, https://github.com/liyue3780/HyperResASHS
+Project-URL: homepage, https://github.com/liyue3780/HyperResASHS
+Keywords: deep learning,image segmentation,medical image analysis,medical image segmentation,MTL subregions,hippocampus segmentation,nnU-Net,hyperresashs,ASHS,Automatic Segmentation of Hippocampal Subfields
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: torch==2.5.1
+Requires-Dist: torchvision==0.20.1
+Requires-Dist: torchaudio==2.5.1
+Requires-Dist: acvl-utils>=0.2
+Requires-Dist: dynamic-network-architectures>=0.4
+Requires-Dist: tqdm
+Requires-Dist: dicom2nifti
+Requires-Dist: scipy
+Requires-Dist: batchgenerators>=0.25
+Requires-Dist: numpy
+Requires-Dist: scikit-learn
+Requires-Dist: scikit-image>=0.19.3
+Requires-Dist: SimpleITK>=2.2.1
+Requires-Dist: pandas
+Requires-Dist: graphviz
+Requires-Dist: tifffile
+Requires-Dist: requests
+Requires-Dist: nibabel
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: imagecodecs
+Requires-Dist: yacs
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: huggingface_hub>=0.20.0
+Requires-Dist: picsl_greedy>=0.0.11
+Requires-Dist: picsl_c3d>=1.4.6.0
+Requires-Dist: tensorboard==2.20.0
+Requires-Dist: lpips==0.1.4
+
+# HyperResASHS
+
+[![arXiv](https://img.shields.io/badge/arXiv-2508.17171-b31b1b.svg)](https://doi.org/10.48550/arXiv.2508.17171)
+
+**HyperResASHS** is a deep learning pipeline for isotropic segmentation of medial temporal lobe (MTL) subregions from multi-modality 3T MRI (T1w and T2w). This repository implements the method described in our paper for achieving high-resolution, isotropic segmentation of brain structures.
+
+## Overview
+
+This project addresses the challenge of segmenting MTL subregions from anisotropic MRI data by:
+1. Building an isotropic atlas using Implicit Neural Representations (INR)
+2. Training a multi-modality segmentation model with nnU-Net
+3. Performing inference on test data with automatic preprocessing
+
+The pipeline handles the entire workflow from raw multi-modality MRI images to final segmentation results, including registration, ROI extraction, upsampling, and model inference.
+
+## Setup
+
+Follow these steps to set up the repository in a fresh environment:
+
+### 1. Create a Conda Environment
+
+Create a new conda environment with Python 3.10 or higher:
+
+```bash
+conda create -n hyperresashs python=3.10
+conda activate hyperresashs
+```
+
+### 2. Clone the Repository
+
+Clone the repository with submodules:
+
+```bash
+git clone --recursive https://github.com/liyue3780/HyperResASHS.git
+cd HyperResASHS
+```
+
+If you've already cloned without submodules, initialize them with:
+
+```bash
+git submodule update --init --recursive
+```
+
+### 3. Install Python Dependencies
+
+**Important**: PyTorch version compatibility is critical. This pipeline requires PyTorch 2.5.x (tested with 2.5.1). Newer versions (e.g., 2.9) may cause compatibility issues.
+
+```bash
+# First, install PyTorch with CUDA support (adjust CUDA version as needed)
+# For CUDA 11.8:
+pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118
+
+# For CPU only:
+# pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1
+
+# Then install the package and remaining dependencies
+pip install -e .
+```
+
+**Note**: Additional dependencies may be required by the submodules. See the submodule setup instructions below.
+
+### 4. Set Up Submodules
+
+This repository uses git submodules for dependencies:
+
+- **`submodules/multi_contrast_inr`**: INR repository (tracking `main` branch)
+- **`submodules/nnUNet`**: Modified nnUNet repository (tracking `mmseg` branch) - [https://github.com/liyue3780/nnUNet/tree/mmseg](https://github.com/liyue3780/nnUNet/tree/mmseg)
+
+**Install nnUNet submodule:**
+
+This step is only needed if you will be training new HyperResASHS models. For inference, it is not necessary.
+
+```bash
+cd submodules/nnUNet
+pip install -e .
+cd ../..
+```
+
+**Set nnU-Net Environment Variables:**
+
+After installing nnUNet, you must set the following environment variables:
+
+```bash
+export nnUNet_raw="/path/to/nnUNet_raw"
+export nnUNet_preprocessed="/path/to/nnUNet_preprocessed"
+export nnUNet_results="/path/to/nnUNet_results"
+```
+
+For detailed setup instructions (including Linux, MacOS, and Windows), see the [nnU-Net environment variables documentation](https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/set_environment_variables.md).
+
+**Install INR submodule dependencies:**
+
+This step is only needed if you will be training new HyperResASHS models. For inference, it is not necessary.
+
+```bash
+pip install tensorboard==2.20.0 lpips==0.1.4
+```
+
+Refer to the INR repository's documentation for specific installation requirements. The INR submodule may require additional dependencies such as PyTorch, nibabel, and other packages.
+
+**Note**: The modified nnUNet includes Modality Augmentation methods for multi-modality brain MRI segmentation. Make sure to use the `mmseg` branch when running nnU-Net training.
+
+### 6. Verify Installation
+
+Verify that the main pipeline can be imported:
+
+```bash
+python -c "from hyperresashs.preprocessing import PreprocessorInVivo; from hyperresashs.testing import ModelTester; from hyperresashs.prepare_inr import INRPreprocess; print('Installation successful!')"
+```
+
+## Configuration
+
+For detailed configuration information, including config file format and cross-validation file format, see [Configuration Guide](docs/configuration.md).
+
+## Pipeline Details
+
+The pipeline consists of six main steps that can be run in linear order. Each step assumes the previous steps have been completed:
+
+1. **Prepare** → 2. **Prepare INR** → 3. **Run INR Upsampling** → 4. **Preprocess** → 5. **Train** → 6. **Test**
+
+**Note**: Steps 2-3 are only needed if using INR upsampling. For other upsampling methods (e.g., `GreedyUpsampling` or `None`), you can skip Steps 2-3 and go directly from Step 1 to Step 4.
+
+### Step 1: Prepare Patch Data (`stage = prepare`)
+
+Run this step first to create the experiment folder by copying images and segmentations from the two atlas folders (T1w and T2w ASHS atlases). This step:
+- Copies primary and secondary modality images from ASHS packages
+- Copies segmentation files
+- Performs coordinate system transformations (swapdim RPI)
+- Creates the folder structure in `{PREPARE_RAW_PATH}/{EXP_NUM}{MODEL_NAME}/images/`
+
+**Usage:**
+```bash
+python main.py -s prepare -c {CONFIG_ID}
+```
+
+### Step 2: Prepare INR Data (`stage = prepare_inr`)
+
+This step prepares the data for INR upsampling. It requires the prepared patch data from Step 1. The `prepare_inr` stage will:
+- Prepare the data in the format expected by the INR submodule
+- Generate INR configuration files for each case
+- Create a shell script `shell/run_inr_upsampling_{EXP_NUM}{MODEL_NAME}.sh` with paths automatically filled from your config
+
+**Usage:**
+```bash
+python main.py -s prepare_inr -c {CONFIG_ID}
+```
+
+**Folder structure created:**
+
+The `prepare_inr` stage creates the following folder structure under `{INR_PATH}/{EXP_NUM}{MODEL_NAME}/`:
+- `preprocess/`: Contains case folders with input data and config files for INR
+- `training_preparation/`: Contains case folders with prepared data ready for INR training
+- `training_output/`: Will contain INR training outputs (created after INR training completes)
+
+### Step 3: Run INR Upsampling (`stage = run_inr`)
+
+After preparing INR data, you have two options to run INR upsampling:
+
+#### Option 1: Run via Python (Recommended for single GPU)
+
+Run INR upsampling directly using Python:
+
+```bash
+python main.py -s run_inr -c {CONFIG_ID}
+```
+
+This will process all cases sequentially. The script automatically:
+- Finds all cases in the `training_preparation` folder (created in Step 2)
+- Runs INR training for each case using the generated config files from the `preprocess` folder
+
+#### Option 2: Run via Shell Script (Recommended for multi-GPU)
+
+For multi-GPU setups, you can use the generated shell script and modify it to run different batches on different GPUs. See [INR Upsampling Shell Script Guide](docs/inr_upsampling_shell_script.md) for detailed instructions.
+
+### Step 4: Complete Preprocessing (`stage = preprocess`)
+
+After INR upsampling is finished, run the preprocessing stage to complete all remaining steps. This step assumes the patch data preparation (Step 1) was already completed. It will:
+- Copy INR upsampled results (if using INR upsampling method)
+- Perform resampling/upsampling based on the configured method
+- Register secondary modality (T1w) to primary (T2w)
+- Prepare nnU-Net dataset
+- Remove outer segmentation artifacts
+- Convert labels to continuous format
+- Create cross-validation splits
+- Run nnU-Net experiment planning
+- Generate nnU-Net training script: `shell/train_nnunet_{EXP_NUM}{MODEL_NAME}.sh`
+
+**Usage:**
+```bash
+python main.py -s preprocess -c {CONFIG_ID}
+```
+
+**Outputs from Step 4:**
+- nnU-Net dataset in `{NNUNET_RAW_PATH}/Dataset{EXP_NUM}_{MODEL_NAME}/`
+- Preprocessed data in `{NNUNET_RAW_PATH}/../nnUNet_preprocessed/Dataset{EXP_NUM}_{MODEL_NAME}/`
+- Cross-validation splits file: `splits_final.json`
+- Training script: `shell/train_nnunet_{EXP_NUM}{MODEL_NAME}.sh`
+
+**Note**: If you're using a non-INR upsampling method (e.g., `GreedyUpsampling` or `None`), you can skip Steps 2-3 and go directly from Step 1 to Step 4.
+
+### Step 5: nnU-Net Training (`stage = train`)
+
+Step 4 creates the nnU-Net dataset, runs experiment planning, and creates five-fold cross-validation splits. A training script is automatically generated for convenience.
+
+You have two options to run nnU-Net training:
+
+#### Option 1: Run via Python (Recommended)
+
+Run nnU-Net training directly using Python:
+
+```bash
+python main.py -s train -c {CONFIG_ID}
+```
+
+This will train all 5 folds (fold 0-4) sequentially using the `TRAINER` specified in your configuration file (e.g., `ModAugUNetTrainer`).
+
+**Note**: Ensure you're using the modified nnUNet from `submodules/nnUNet` (mmseg branch) which includes Modality Augmentation methods. The `nnUNetv2_train` command should be available after installing the modified nnUNet.
+
+#### Option 2: Run via Shell Script
+
+Alternatively, you can run the generated training script manually. See [nnU-Net Training Shell Script Guide](docs/nnunet_training_shell_script.md) for detailed instructions.
+
+### Step 6: Testing (`stage = test`)
+
+Testing is independent from Steps 1-5 and uses its own configuration files in the `config_test/` directory. Each test configuration has its own ID that links to a trained model.
+
+**Test Configuration ID Convention:**
+- The test config ID links to the training model ID. For example:
+  - `2921` links to model `292` (the `1` represents the first test set)
+  - `2922`, `2923`, `2924`, etc. can be used for different test sets of the same model
+- The first digits match the `EXP_NUM` of the trained model you want to use
+
+**Usage:**
+```bash
+python main.py -s test -c {TEST_CONFIG_ID}
+# For example: python main.py -s test -c 2921
+```
+
+**Configuration Requirements:**
+- `EXP_NUM`: Must match the training model's `EXP_NUM` (e.g., `292`)
+- `MODEL_NAME`: Must match the training model's `MODEL_NAME` (e.g., `TestPipeline`)
+- `TRAINER`: Must match the training model's `TRAINER`
+- `CONDITION`: Must match the training model's `CONDITION` (e.g., `in_vivo`)
+- `UPSAMPLING_METHOD`: Must match the training model's `UPSAMPLING_METHOD`
+- `TEST_PATH`: Path to test data (see [Configuration Guide](docs/configuration.md) for structure)
+- `TEMPLATE_PATH`: Path to ASHS template for MTL ROI cropping (downloadable from [DOI: 10.5061/dryad.k6djh9wmn](https://doi.org/10.5061/dryad.k6djh9wmn))
+
+**This stage performs:**
+- Whole-brain registration (T1w to T2w)
+- ROI extraction using ASHS template
+- Patch cropping and upsampling
+- Local registration for fine alignment
+- nnU-Net inference for segmentation
+- Output of segmentation results
+
+For detailed test configuration information, see [Configuration Guide](docs/configuration.md).
+
+## Citation
+
+If you use this code in your research, please cite our paper:
+
+```bibtex
+@article{hyperresashs2024,
+  title={HyperResASHS: Isotropic Segmentation of MTL Subregions from Multi-modality 3T MRI},
+  author={[Authors]},
+  journal={arXiv preprint arXiv:2508.17171},
+  year={2024},
+  url={https://doi.org/10.48550/arXiv.2508.17171}
+}
+```
+
+## Changelog
+
+### 01/14/2026
+- Replaced `trim_neck.sh` shell script with Python implementation using `picsl_c3d` package
+- Removed ITK-SNAP installation requirement (no longer needed)
+- Updated `multi_contrast_inr` submodule to latest version
+- Modified `--config_id` argument to accept both integer ID and full file path
+- Added config validation checks: ID consistency, conflict detection, and nnUNet dataset existence
+- Made `FILE_NAME_CONFIG` optional with automatic defaults based on stage (test vs. other stages)
+- Renamed `scripts/` folder to `shell/` for better clarity
+- Added optional `--subject_id` argument for test stage to test specific subjects
+- Updated `.gitignore` to exclude generated config and script files while keeping template files tracked
+- Fixed config validation to skip checks when stage is `test`
+
+### 01/07/2026
+- Added `requirements.txt` and `setup.py` with pinned package versions for reproducible installation
+- Added nnU-Net environment variables setup instructions
+- Added Python stages for INR upsampling (`stage = run_inr`) and nnU-Net training (`stage = train`)
+- Created comprehensive documentation in `docs/` folder:
+  - Configuration guide with training and test config details
+  - INR upsampling shell script guide
+  - nnU-Net training shell script guide
+- Updated README to reference documentation files for better organization
+- Added `trim_neck.sh` script for neck trimming
+- Updated testing documentation with config_test details and test data structure
+- Changed default pipeline stage from `prepare_inr` to `prepare`
+
+### 01/04/2026
+- Refactored pipeline to support linear execution order
+- Added separate `prepare` stage for patch data preparation
+- Simplified `execute()` method in preprocessing to remove conditional checks
+- Updated pipeline documentation to reflect linear execution flow
+- Added `.gitignore` to exclude Python cache files and build artifacts
+
+### 12/24/2025
+- Added INR and modified nnUNet as git submodules
+- Added INR preparation module with config generation
+- Added INR upsampling script template and generation
+- Added nnUNet training script template and generation
+- Updated README with submodule setup and pipeline documentation
+
+### 12/22/2025
+- Updated README.md with comprehensive documentation
+- Added data structure documentation slots for atlas and test data
+
+### 11/20/2025
+- Added main pipeline of preprocessing
+
+### 10/27/2025
+- Initial release of isotropic segmentation pipeline for MTL subregions
+- Support for 3T-T2w and 3T-T1w multi-modality MRI
+
+## Contact
+
+For questions or support, please open an issue or contact [liyue3780@gmail.com](mailto:liyue3780@gmail.com).