README.md

---
title: AscitesModel
license: cc-by-nc-sa-4.0
---

# Ascites Segmentation with nnUNet

This model was trained as part of the research 'Deep Learning Segmentation of Ascites on Abdominal CT Scans for Automatic Volume Quantification' ([Paper](https://doi.org/10.1148/ryai.230601), [arXiv](https://arxiv.org/abs/2406.15979)). 

## Method 1: Run Inference using `nnunet_predict.py`

1. Install [nnUNet_v1](https://github.com/MIC-DKFZ/nnUNet/tree/nnunetv1#installation) and [PyTorch](https://pytorch.org/get-started/locally/).

```shell
user@machine:~/ascites_segmentation$ pip install torch torchvision torchaudio nnunet matplotlib
```

2. Run inference with command:

```shell
user@machine:~/ascites_segmentation$ python nnunet_predict.py -i file_list.txt -t TMP_DIR -o OUTPUT_FOLDER -m /path/to/nnunet/model_weights
```

```shell
usage: tmp.py [-h] [-i INPUT_LIST] -t TMP_FOLDER -o OUTPUT_FOLDER -m MODEL [-v]

Inference using nnU-Net predict_from_folder Python API

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT_LIST, --input_list INPUT_LIST
                        Input image file_list.txt
  -t TMP_FOLDER, --tmp_folder TMP_FOLDER
                        Temporary folder
  -o OUTPUT_FOLDER, --output_folder OUTPUT_FOLDER
                        Output Segmentation folder
  -m MODEL, --model MODEL
                        Trained Model
  -v, --verbose         Verbose Output
```



N.B. 
- `model_weights` folder should contain `fold0`, `fold1`, etc...
- WARNING: the program will try to create file links first, but will fallback to filecopy if fails


## Method 2: Run Inference using `nnUNet_predict` from shell

1. Install [nnUNet_v1](https://github.com/MIC-DKFZ/nnUNet/tree/nnunetv1#installation) and [PyTorch](https://pytorch.org/get-started/locally/).

```shell
user@machine:~/ascites_segmentation$ pip install torch torchvision torchaudio nnunet matplotlib
```

2. Setup environment variables so that nnU-Net knows where to find trained models: 

```shell
user@machine:~/ascites_segmentation$ export nnUNet_raw_data_base="/absolute/path/to/nnUNet_raw_data_base"
user@machine:~/ascites_segmentation$ export nnUNet_preprocessed="/absolute/path/to/nnUNet_preprocessed"
user@machine:~/ascites_segmentation$ export RESULTS_FOLDER="/absolute/path/to/nnUNet_trained_models"
```

3. Run inference with command:

```shell
user@machine:~/ascites_segmentation$ nnUNet_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -t 505 -m 3d_fullres -f N --save_npz 
```

where:
- `-i`: input folder of `.nii.gz` scans to predict. NB, filename needs to end with `_0000.nii.gz` to tell nnU-Net only one kind of modality
- `-o`: output folder to store predicted segmentations, automatically created if not exist
- `-t 505`: (do not change) Ascites pretrained model name
- `-m 3d_fullres` (do not change) Ascites pretrained model name
- `N`: Ascites pretrained model fold, can be `[0, 1, 2, 3, 4]`
- `--save_npz`: save softmax scores, required for ensembling multiple folds 

### Optional [Additional] Inference Steps

a. use `nnUNet_find_best_configuration` to automatically get the inference commands needed to run the trained model on data.

b. ensemble predictions using `nnUNet_ensemble` by running:

```shell
user@machine:~/ascites_segmentation$ nnUNet_ensemble -f FOLDER1 FOLDER2 ... -o OUTPUT_FOLDER -pp POSTPROCESSING_FILE
```

where `FOLDER1` and `FOLDER2` are predicted outputs by nnUNet (requires `--save_npz` when running `nnUNet_predict`).

## Method 3: Docker Inference

Requires `nvidia-docker` to be installed on the system ([Installation Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)). This `nnunet_docker` predicts ascites with all 5 trained folds and ensembles output to a single prediction.

1. Build the `nnunet_docker` image from `Dockerfile`:

```shell
user@machine:~/ascites_segmentation$ sudo docker build -t nnunet_docker .
```

2. Run docker image on test volumes:

```shell
user@machine:~/ascites_segmentation$ sudo docker run \
--gpus 0 \
--volume /absolute/path/to/INPUT_FOLDER:/tmp/INPUT_FOLDER \
--volume /absolute/path/to/OUTPUT_FOLDER:/tmp/OUTPUT_FOLDER \
nnunet_docker /bin/sh inference.sh
```

- `--gpus` parameter:
  - `0, 1, 2, ..., n` for integer number of GPUs 
  - `all` for all available GPUs on the system
  - `'"device=2,3"'` for specific GPU with ID

- `--volume` parameter
  - `/absolute/path/to/INPUT_FOLDER` and `/absolute/path/to/OUTPUT_FOLDER` folders on the host system needs to be specified
  - `INPUT_FOLDER` contains all `.nii.gz` volumes to be predicted
  - predicted results will be written to `OUTPUT_FOLDER`

## Citation

If you find this repository helpful in your research, please consider citing our paper:

```text
@article{hou2024deep,
  title={Deep Learning Segmentation of Ascites on Abdominal CT Scans for Automatic Volume Quantification},
  author={Hou, Benjamin and Lee, Sung-Won and Lee, Jung-Min and Koh, Christopher and Xiao, Jing and Pickhardt, Perry J. and Summers, Ronald M.}
  journal={Radiology: Artificial Intelligence},
  pages={e230601},
  year={2024},
  publisher={Radiological Society of North America}
}
```