blast-ct 5.0.5
Automatic segmentation of Traumatic Brain Injury (TBI) in Head CT
License: MIT
Requires Python: >=3.6
Keywords: CT, traumatic brain injury, segmentation, medical imaging

# BLAST-CT
[![DOI](https://zenodo.org/badge/246262662.svg)](https://zenodo.org/badge/latestdoi/246262662)

**B**rain **L**esion **A**nalysis and **S**egmentation **T**ool for **C**omputed **T**omography - Version 2.0.0

## 🔧 NOTE: Updated, Installable Fork
> **This is an updated and fully installable version of BLAST-CT.**  
> The original repo fails on install due to bundled binaries + outdated packaging.  
> This fork:  
> • Works via `pip install blast-ct`  
> • Downloads models from Hugging Face  
> • Cleans up inference + training CLI for modern environments


This repository provides our deep learning image segmentation tool for traumatic brain injuries in 3D CT scans.

Please consider citing our article when using our software:
> Monteiro M, Newcombe VFJ, Mathieu F, Adatia K, Kamnitsas K, Ferrante E, Das T, Whitehouse D, Rueckert D, Menon DK, Glocker B. **[Multi-class semantic segmentation and quantification of traumatic brain injury lesions on head CT using deep learning – an algorithm development and multi-centre validation study](https://www.thelancet.com/journals/landig/article/PIIS2589-7500(20)30085-6/fulltext)**. _The Lancet Digital Health_ (2020).
Monteiro and Newcombe are equal first authors. Menon and Glocker are equal senior authors.

**NOTE:** This software is not intended for clinical use.

![Examples for automatic lesion segmentation](blast-ct.png)

## Source code

The provided source code enables training and testing of our convolutional neural network designed for multi-class brain lesion segmentation in head CT.
Additionally, it allows for localisation of the segmented image, i.e. calculation of the volume of lesion per brain region (list of regions in blast_ct/data/localisation_files/atlas_labels.csv).
**NOTE:** The localisation is based on linear image registration, hence it does not allow for voxel-wise precision.

## Pre-trained model

In version 2.0.0 of this tool, we also make available a model that has been trained on a set of 680 annotated CT scans obtained from multiple clinical sites. 

The output of our lesion segmentation tool is a segmentation map in NIfTI format with integer values ranging from 1 to 4 representing:
1. Intraparenchymal haemorrhage (IPH);
2. Extra-axial haemorrhage (EAH);
3. Perilesional oedema;
4. Intraventricular haemorrhage (IVH).

A CSV file with the total volume of lesion calculated for each lesion class is also part of the output. If the user chooses to perform localisation of lesions, 
this file will also include the volume of lesion per brain region, the volume of each brain region as well as the total brain volume.

**As of the latest version, the tool resamples images internally and returns the output segmentation in the same space as the input image, so there is no need to preprocess the input.**
## Installation

### Linux and MacOS
On a fresh python3 virtual environment install `blast-ct` via

`pip install blast-ct`

### Windows
If you are using miniconda, create a new conda environment and install PyTorch

```
conda create -n blast-ct python=3
conda activate blast-ct
conda install pytorch torchvision cudatoolkit=10.1 -c pytorch
```

Then install `blast-ct` via

`pip install blast-ct`

Verify the installation by running
`blast-ct --help`

Pretrained Models (Hosted on Hugging Face)
Pretrained ensemble models are downloaded automatically on first use from:

- https://huggingface.co/sakshirathi360/blast-ct

Models are cached locally at:

`~/.blastct/models/`

Manual download (optional):

`huggingface-cli download sakshirathi360/blast-ct --include "*.torch_model"`

# Usage with examples

Please run the following in your bash console to obtain an example data that we use to illustrate the usage of our tool in the following:
```
mkdir blast-ct-example
cd blast-ct-example
svn checkout "pip install git+https://github.com/SakshiRa/blast-ct/trunk/blast_ct/data/"
```

## Inference on one image
To run inference on one image using our pre-trained model:

`blast-ct --input <path-to-input-image> --output <path-to-output-image> --device <device-id>`

1. `--input`: path to the input input image which must be in nifti format (`.nii` or `.nii.gz`);
2. `--output`: path where prediction will be saved (with extension `.nii.gz`);
3. `--device <device-id>` the device used for computation. Can be `'cpu'` (up to 1 hour per image) or an integer 
indexing a cuda capable GPU on your machine. Defaults to CPU;
4. Pass `--ensemble True`: to use an ensemble of 15 models which improves segmentation quality but slows down inference
 (recommended for gpu).
5. Pass `--localisation True` to localise the segmented lesion, i.e. calculate the volume of lesion per brain region.
6. (Only if `--do-localisation True`) `'--num-reg-runs'`: how many times to run registration between native scan and CT template. Running it more than one time prevents initialisation errors, as only the best performing run is kept.

##### Working example:

Run the following in the `blast-ct-example` directory (might take up to an hour on CPU):

`blast-ct --input data/scans/scan_0/scan_0_image.nii.gz --output scan_0_prediction.nii.gz`


## Inference on multiple images
To run inference on multiple images using our ensemble of pre-trained models:

```
blast-ct-inference \
    --job-dir <path-to-job-dir> \
    --test-csv-path <path-to-test-csv> \ 
    --device <device-id>
```

1. `--job-dir`: the path to the directory where the predictions and logs will be saved;
2. `--test-csv-path`: the path to a [csv file](#csv-files-for-inference-and-training) containing the paths of the 
images to be processed;
3. `--device <device-id>` the device used for computation. Can be `'cpu'` (up to 1 hour per image) or an integer 
indexing a cuda capable GPU on your machine. Defaults to CPU;
4. Pass `--overwrite True`: to write over existing `job-dir`. Set as `False` if you want to continue a run previously started.
5. Pass `--do-localisation True` to localise the segmented lesion, i.e. calculate the volume of lesion per brain region.
6. (Only if `--do-localisation True`) `'--num-reg-runs'`: how many times to run registration between native scan and CT template. Running it more than one time prevents initialisation errors, as only the best performing run is kept.

##### Working example:

Run the following in the `blast-ct-example` directory (GPU example):

`blast-ct-inference --job-dir my-inference-job --test-csv-path data/data.csv --device 0`

**NOTE:** If the run breaks before all images are processed, run again with `--overwrite False` to finish from where it was left on the previous run.

## Training models on your own data

To train your own model:

```
blast-ct-train \
    --job-dir <path-to-job-dir> \
    --config-file <path-to-config-file> \
    --train-csv-path <path-to-train-csv> \
    --valid-csv-path <path-to-valid-csv> \
    --num-epochs <num-epochs> \
    --device <gpu_id> \
    --random-seed <list-of-random-seeds>
```

1. `--job-dir`: the path to the directory where the predictions and logs will be saved;
2. `--config-file`: the path to a json config file (see `data/config.json` for example);
3. `--train-csv-path`: the path to a [csv file](#csv-files-for-inference-and-training) containing the paths of the 
images, targets and sampling masks used to train th model;
4. `--valid-csv-path`: the path to a [csv file](#csv-files-for-inference-and-training) containing the paths of the 
images used to keep track of the model's performance during training;
5. `--num-epochs`: the number of epochs for which to train the model (1200 was used with the example config)
6. `--device <device-id>` the device used for computation (`'cpu'` or integer indexing GPU). GPU is strongly recommended.
7. `-random-seeds`: a list of random seeds used for training. 
Pass more than one to train multiple models one after the other.
8. pass `--overwrite True`: to write over existing `job-dir`. Set as `False` if you want to continue a run previously started.


##### Working example:

Run the following in the `blast-ct-example` directory (GPU example, takes time):
```
blast-ct-train \
    --job-dir my-training-job \
    --config-file data/config.json \
    --train-csv-path data/data.csv \
    --valid-csv-path data/data.csv \
    --num-epochs 10 \
    --device 0 \
    --random-seeds "1"
```


## Inference with your model

To run inference with your own models and config use
```
blast-ct-inference \
   --job-dir <path-to-job-dir> \
   --config-file <path-to-config-file> \
   --test-csv-path <path-to-test-csv> \
   --device <gpu_id> \
   --saved-model-paths <list-of-paths-to-saved-models>
```

1. `--job-dir`: the path to the directory where the predictions and logs will be saved;
2. `--config-file`: the path to a json config file (see `data/config.json` for example);
3. `--test-csv-path`: the path to a [csv file](#csv-files-for-inference-and-training) containing the paths of the 
images to be processed;
4. `--device <device-id>` the device used for computation. Can be `'cpu'` (up to 1 hour per image) or an integer 
indexing a cuda capable GPU on your machine. Defaults to CPU;
 `--saved-model-paths` is a list of pre-trained model paths;
5. pass `--overwrite True`: to write over existing `job-dir`. Set as `False` if you want to continue a run previously started.
6. pass `--do-localisation True` to localise the segmented lesion, i.e. calculate the volume of lesion per brain region.
7. (Only if `--do-localisation True`) `'--num-reg-runs'`: how many times to run registration between native scan and CT template. Running it more than one time prevents initialisation errors, as only the best performing run is kept.


##### Working example:

Run the following in the `blast-ct-example` directory (GPU example):
```
blast-ct-inference \
    --job-dir my-custom-inference-job \
    --config-file data/config.json \
    --test-csv-path data/data.csv \
    --device 0 \
    --saved-model-paths "data/saved_models/model_1.pt data/saved_models/model_3.pt data/saved_models/model_6.pt
    --do-localisation True
```

## csv files for inference and training

The tool takes input from csv files containing lists of images with unique ids.
Each row in the csv represents a scan and must contain:
1. A column named `id` which must be unique for each row (otherwise overwriting will happen);
2. A column named `image` which must contain the path to a nifti file;
3. (training only) A column named `target` containing a nifti file with the corresponding labels for training;
4. (training only; optional) A column named `sampling_mask` containing a nifti file with the corresponding sampling mask 
for training;
See `data/data.csv` for a working example with 10 rows/ids (even though in this example they point to the same image).