Skip to content

Commit

Permalink
Update README to include Hydra overriding documentations (#139)
Browse files Browse the repository at this point in the history
  • Loading branch information
@HangJung97
HangJung97 authored Nov 6, 2023
1 parent f1c18f0 commit d2fe777
Showing 1 changed file with 92 additions and 37 deletions.
129 changes: 92 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<div align="center">

# ASCENT <!-- no toc -->
# ASCENT <!-- omit in toc -->

Welcome to the code repository for *cardiAc ultrasound Segmentation & Color-dopplEr dealiasiNg Toolbox* (ASCENT).

Expand All @@ -15,9 +15,9 @@ Welcome to the code repository for *cardiAc ultrasound Segmentation & Color-dopp
[![pre-commit](https://img.shields.io/badge/Pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![code-quality](https://github.com/creatis-myriad/ASCENT/actions/workflows/code-quality-main.yaml/badge.svg)](https://github.com/creatis-myriad/ASCENT/actions/workflows/code-quality-main.yaml)

[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/creatis-myriad/ASCENT#LICENSE)
[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

# Publications <!-- no toc -->
# Publications <!-- omit in toc -->

[![Journal](https://img.shields.io/badge/IEEE%20TUFFC-2023-4b44ce.svg)](https://doi.org/10.1109/TUFFC.2023.3289621)
[![Paper](http://img.shields.io/badge/paper-arxiv.2306.13695-B31B1B.svg)](https://arxiv.org/abs/2306.13695)
Expand All @@ -29,20 +29,29 @@ Welcome to the code repository for *cardiAc ultrasound Segmentation & Color-dopp

# Description

ASCENT is a toolbox to segment cardiac structures (left ventricle, right ventricle, etc.) on ultrasound images and perform dealiasing on color Doppler echocardiography. It combines one of the best segmentation framework, [nnUNet](https://github.com/MIC-DKFZ/nnUNet/tree/nnunetv1) with [Lightning](https://lightning.ai/), [Hydra](https://hydra.cc/), and [monai](https://monai.io/). The main reasons of doing so are to take advantage of each library:
ASCENT is a toolbox to segment cardiac structures (left ventricle, right ventricle, etc.) on
ultrasound images and perform dealiasing on color Doppler echocardiography. It combines one of the
best segmentation framework, [nnUNet](https://github.com/MIC-DKFZ/nnUNet/tree/nnunetv1) with
[Lightning](https://lightning.ai/), [Hydra](https://hydra.cc/), and [monai](https://monai.io/).
The main reasons of doing so are to take advantage of each library:

- nnUNet's heuristic rules for hyperparameters determination and training scheme give excellent segmentation results.
- nnUNet's heuristic rules for hyperparameters determination and training scheme give excellent
segmentation results.
- Lightning reduces boilerplate and provides better PyTorch code organization.
- Hydra offers pluggable architectures, dynamic configurations, and easy configuration overriding through command lines.
- Hydra offers pluggable architectures, dynamic configurations, and easy configuration overriding
through command lines.
- Monai simplifies the data loading and pre-processing.

For now, ASCENT provides only nnUNet 2D and 3D_fullres architectures (similar to monai's [DynUNet](https://docs.monai.io/en/stable/_modules/monai/networks/nets/dynunet.html)). You can easily plug your own models in ASCENT pipeline.
For now, ASCENT provides only nnUNet 2D and 3D_fullres architectures (similar to monai's
[DynUNet](https://docs.monai.io/en/stable/_modules/monai/networks/nets/dynunet.html)). You can
easily plug your own models in ASCENT pipeline.

> **Note**
> **ⓘ**
> nnUNet implemented in ASCENT is the V1.
# Table of Contents <!-- no toc -->
# Table of Contents <!-- omit in toc -->

- [Description](#description)
- [How to run](#how-to-run)
- [Install](#install)
- [Data](#data)
Expand All @@ -53,15 +62,18 @@ For now, ASCENT provides only nnUNet 2D and 3D_fullres architectures (similar to
- [Run inference](#run-inference)
- [Experiment tracking](#experiment-tracking)
- [Define custom data and logs path](#define-custom-data-and-logs-path)
- [Advanced Hydra overriding](#advanced-hydra-overriding)
- [Resources](#resources)
- [References](#references)

# How to run

ASCENT has been tested on Linux (Ubuntu 20, Red Hat 7.6), macOS and Windows 10/11.

> **Note**
> Automatic Mixed Precision (AMP) is buggy on Windows devices, e.g. Nan in loss computation. For Windows users, it is recommended to disable it during the run by adding trainer.precision=32 to the train/evaluate/predict command to avoid errors.
> **ⓘ**
> Automatic Mixed Precision (AMP) is buggy on Windows devices, e.g. Nan in loss computation.
> For Windows users, it is recommended to disable it during the run by adding `trainer.precision=32`
> to the train/evaluate/predict command to avoid errors.
## Install

Expand All @@ -77,7 +89,8 @@ ASCENT has been tested on Linux (Ubuntu 20, Red Hat 7.6), macOS and Windows 10/1
conda create -n ascent python=3.10
conda activate ascent
```
3. Install [PyTorch](https://pytorch.org/get-started/locally/) according to instructions. Grab the one with GPU for faster training:
3. Install [PyTorch](https://pytorch.org/get-started/locally/) according to instructions.
Grab the one with GPU for faster training:
```bash
# example for linux or Windows
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia
Expand All @@ -87,15 +100,19 @@ ASCENT has been tested on Linux (Ubuntu 20, Red Hat 7.6), macOS and Windows 10/1
pip install -e .
```

Several new commands will be added to the virtual environment once the installation is completed. These commands all start with `ascent_`.
Several new commands will be added to the virtual environment once the installation is completed.
These commands all start with `ascent_`.

## Data

Before doing any preprocessing and training, you must first reformat the dataset to the appropriate format and place the converted dataset in the `data/` folder.
Here is an example of the converted [CAMUS](https://www.creatis.insa-lyon.fr/Challenge/camus/) dataset using this [conversion script](ascent/dataset_conversion/camus.py).
Before doing any preprocessing and training, you must first reformat the dataset to the appropriate
format and place the converted dataset in the `data/` folder. Here is an example of the converted
[CAMUS](https://www.creatis.insa-lyon.fr/Challenge/camus/) dataset using this
[conversion script](ascent/dataset_conversion/camus.py).

> **Note**
> Refer to [here](#define-custom-data-and-logs-path) if you want to have a different `data/` folder location.
> **ⓘ**
> Refer to [here](#define-custom-data-and-logs-path) if you want to have a different `data/` folder
> location.
The reformatted dataset should look like this:

Expand Down Expand Up @@ -124,11 +141,14 @@ More details can be found in [nnUNet's dataset conversion instructions](https://

## Important note

ASCENT uses Hydra to handle the configurations and runs. To know more about Hydra's CLI, refer to its [documentation](https://hydra.cc/docs/intro/).
ASCENT uses Hydra to handle the configurations and runs. To know more about Hydra's CLI, refer to
its [documentation](https://hydra.cc/docs/intro/).

## Preprocess

ASCENT preprocesses and determines the optimized hyperparameters according to nnUNet's heuristic rules. After placing the dataset in the correct `data/` folder, you can run the preprocessing and planning with the following command:
ASCENT preprocesses and determines the optimized hyperparameters according to nnUNet's heuristic
rules. After placing the dataset in the correct `data/` folder, you can run the preprocessing and
planning with the following command:

```bash
ascent_preprocess_and_plan dataset=XXX
Expand All @@ -142,23 +162,35 @@ It is possible to preprocess multiple dataset at once using the `--multirun` fla
ascent_preprocess_and_plan --multirun dataset=XXX,YYY,ZZZ
```

By default, ASCENT creates a 2D and a 3D experiment configuration files that includes the batch size, U-Net architecture, patch size, etc. You can choose to plan only 2D or 3D experiment by overriding `pl2d` or `pl3d` like follows:
By default, ASCENT creates a 2D and a 3D experiment configuration files that includes the batch
size, U-Net architecture, patch size, etc. You can choose to plan only 2D or 3D experiment by
overriding `pl2d` or `pl3d` like follows:

```bash
ascent_preprocess_and_plan dataset=XXX pl2d=False
```

Once `ascent_preprocess_and_plan` is completed, the cropped and preprocessed data will be located respectively at `data/XXX/cropped` and `data/XXX/preprocessed`. New config files are also generated in [ascent/configs/experiment/](ascent/configs/experiment/), [ascent/configs/datamodule/](ascent/configs/datamodule/), and [ascent/configs/model/](ascent/configs/model/). These configs files are named as `XXX_2d.yaml` or `XXX_3d.yaml`, depending on the requested planner(s).
Once `ascent_preprocess_and_plan` is completed, the cropped and preprocessed data will be located
respectively at `data/XXX/cropped` and `data/XXX/preprocessed`. New config files are also generated
in [ascent/configs/experiment/](ascent/configs/experiment),
[ascent/configs/datamodule/](ascent/configs/datamodule),
and [ascent/configs/model/](ascent/configs/model). These configs files are named as `XXX_2d.yaml`
or `XXX_3d.yaml`, depending on the requested planner(s).

You may override other configurations as long as they are listed in [ascent/configs/preprocess_and_plan.yaml](ascent/configs/preprocess_and_plan.yaml). You can also run the following command to display all available configurations:
You may override other configurations as long as they are listed in
[ascent/configs/preprocess_and_plan.yaml](ascent/configs/preprocess_and_plan.yaml). You can also
run the following command to display all available configurations:

```bash
ascent_preprocess_and_plan -h
```

## Model training

With the preprocessing being done, you can now train the model. For all experiments, ASCENT automatically detects the presence of GPU and utilize the GPU if it is available. ASCENTS creates 5-Fold cross validations with train/validation/test splits with 0.8/0.1/0.1/ ratio. You can disable the test splits by overriding `datamodule.test_splits=False`.
With the preprocessing being done, you can now train the model. For all experiments, ASCENT
automatically detects the presence of GPU and utilize the GPU if it is available. ASCENTS creates
5-Fold cross validations with train/validation/test splits with 0.8/0.1/0.1/ ratio. You can disable
the test splits by overriding `datamodule.test_splits=False`.

Below is an example to train a 2D model on CAMUS dataset with the pre-determined hyperparameters:

Expand All @@ -175,13 +207,18 @@ You can override any parameter from command line like this:
ascent_train experiment=camus_challenge_2d trainer.max_epochs=20 datamodule.batch_size=8 logger=tensorboard
```

If you want to check if all the configurations are correct without running the experiment, simply run:
> **ⓘ**
> More advanced Hydra overriding is explained [here](#advanced-hydra-overriding).
If you want to check if all the configurations are correct without running the experiment, simply
run:

```bash
ascent_train experiment=camus_challenge_2d --cfg --resolve
ascent_train experiment=camus_challenge_2d --cfg job --resolve
```

Hydra creates new output directory for every executed run. Default ASCENT's nnUNet logging structure is as follows:
Hydra creates new output directory for every executed run. Default ASCENT's nnUNet logging
structure is as follows:

```
├── logs
Expand All @@ -205,18 +242,22 @@ Hydra creates new output directory for every executed run. Default ASCENT's nnUN
│ │ │ │ │ └── ...
```

At the end of the training, the prediction on validation or test data will be executed and saved in the output folder, named as `validation_raw` or `testing_raw`. To disable this, override `test=False`:
At the end of the training, the prediction on validation or test data will be executed and saved in
the output folder, named as `validation_raw` or `testing_raw`. To disable this, override
`test=False`:

```bash
ascent_train experiment=camus_challenge_2d test=False logger=tensorboard
```

> **Note**
> Refer to [here](#define-custom-data-and-logs-path) if you want to have a different `logs/` folder location.
> **ⓘ**
> Refer to [here](#define-custom-data-and-logs-path) if you want to have a different `logs/` folder
> location.
## Model evaluation

If you skipped the evaluation on validation or test data during, you may evaluate your model afterwards by specifying the `fold` and the `ckpt_path` using `ascent_evaluate`:
If you skipped the evaluation on validation or test data during, you may evaluate your model
afterward by specifying the `fold` and the `ckpt_path` using `ascent_evaluate`:

```bash
ascent_evaluate experiment=camus_challenge_2d fold=0 ckpt_path="/path/to/ckpt" logger=tensorboard
Expand All @@ -232,20 +273,27 @@ To run inference on unseen data, you may use the `ascent_predict`:
ascent_predict dataset=CAMUS_challenge model=camus_challenge_2d ckpt_path=/path/to/checkpoint input_folder=/path/to/input/folder/ output_folder=/path/to/output/folder
```

By default, ASCENT applies test time augmentation during inference. To disable this, override `tta=False`. If you wish to save the predicted softmax probabilities as well, activate the `save_npz=True` flag.
By default, ASCENT applies test time augmentation during inference. To disable this, override
`tta=False`. If you wish to save the predicted softmax probabilities as well, activate the
`save_npz=True` flag.

## Experiment tracking

ASCENTS supports all the logging frameworks proposed by PyTorch Lightning: [Weights&Biases](https://www.wandb.com/), [Neptune](https://neptune.ai/), [Comet](https://www.comet.ml/), [MLFlow](https://mlflow.org), [Tensorboard](https://www.tensorflow.org/tensorboard/).
ASCENTS supports all the logging frameworks proposed by PyTorch Lightning:
[Weights&Biases](https://www.wandb.com/), [Neptune](https://neptune.ai/), [Comet](https://www.comet.ml/),
[MLFlow](https://mlflow.org), [Tensorboard](https://www.tensorflow.org/tensorboard/).

For nnUNet experiments, Weights&Biases logger is used by default. This requires you to create an account. After signing up, rename the [.env.example](.env.example) file to `.env` and specify your WANDB API Key as follows:
For nnUNet experiments, Weights&Biases logger is used by default. This requires you to create an
account. After signing up, rename the [.env.example](.env.example) file to `.env` and specify your
WANDB API Key as follows:

```bash
### API keys ###
WANDB_API_KEY=<your-wandb-api-key>
```

The environment variables in the `.env` file is automatically loaded by `pyrootutils` before each run.
The environment variables in the `.env` file is automatically loaded by `pyrootutils` before each
run.

You can simply override `logger` to use your logger of preference:

Expand All @@ -256,7 +304,9 @@ ascent_train experiment=camus_challenge_2d logger=tensorboard

## Define custom data and logs path

In some cases, you may want to specify your own data and logs paths instead of using the default `data/` and `logs/`. You can do this by setting them in environments variables after renaming the [.env.example](.env.example) file to `.env`. In the `.env`, simply override:
In some cases, you may want to specify your own data and logs paths instead of using the default
`data/` and `logs/`. You can do this by setting them in environments variables after renaming the
[.env.example](.env.example) file to `.env`. In the `.env`, simply override:

```bash
# custom data path
Expand All @@ -273,6 +323,11 @@ After that, you must override `paths=custom` in all your commands, e.g.:
ascent_train experiment=camus_challenge_2d paths=custom
```

## Advanced Hydra overriding

If you wish to perform some advanced Hydra overriding, kindly refer to the these
[documentations](documentations/hydra_config).

# Resources

This project was inspired by:
Expand All @@ -284,8 +339,8 @@ This project was inspired by:

# References

If you find this repository useful, please consider citing the paper implemented in this repository relevant to you from the
list below:
If you find this repository useful, please consider citing the paper implemented in this repository
relevant to you from the list below:

```bibtex
@article{ling_dealiasing_2023,
Expand Down

0 comments on commit d2fe777

Please sign in to comment.