Getting Started

Installing UltraBench

UltraBench can be installed from PyPI by running:

pip install usaugment

After this, the CLI for preparing the datasets is accessible via the command ultrabench, e.g.

ultrabench --help

This lists the commands for preparing each dataset.

Using a Dataset

To demonstrate how to use UltraBench, we will walk through the steps required to prepare the CAMUS dataset.

1. Download and Extract the Raw Data

Download the raw CAMUS dataset (CAMUS_public.zip) from here and then extract it:

unzip CAMUS_public.zip

2. Prepare the Dataset

Once the dataset has been downloaded and extracted, we can use UltraBench to create a preprocessed version using the camus command and providing the path to the raw data and the location to save the preprocessed version. For example, if CAMUS_public/ is in the current directory and we want to save the processed version in the same place, we would run:

ultrabench camus CAMUS_public/ .

This creates a directory camus_v1.0.0 with a version number matching the version of UltraBench that contains the following:

.
└── camus_v1.0.0/
    ├── images/
    │   ├── patient0001_view2CH_frame10.png
    │   └── ...
    ├── masks/
    │   ├── scan/
    │   │   ├── patient0001_view2CH_frame10.png
    │   │   └── ...
    │   └── structures/
    │       ├── patient0001_view2CH_frame10.png
    │       └── ...
    ├── test.json
    ├── train.json
    ├── validation.json
    └── version.txt

The images and masks directories contain the processed images and mask files. The three JSON files (train.json, validation.json, or test.json) contain the examples in the train, validation and test sets, respectively. Finally, the version.txt file contains information about the version of UltraBench used to generate the processed version of dataset and the date it was created.

An example entry the split files contain all of the information linked to each example. For example, the class label (where applicable), the path to the associated image, the path to the associated mask(s) and any other metadata provided with the original data. For example, the first entry in the CAMUS trainining set is:

{
    "patient": 121,
    "view": "4CH",
    "frame": 1,
    "sex": "F",
    "age": 50,
    "image_quality": "Medium",
    "EF": 17,
    "frame_rate": 56.5,
    "image": "images/patient0121_view4CH_frame1.png",
    "mask": "masks/structures/patient0121_view4CH_frame1.png",
    "scan_mask": "masks/scan/patient0121_view4CH_frame1.png",
    "label": 1,
    "ED": true,
    "ES": false
}

3. Using the Dataset

Now that we've prepared the dataset, we can use it to train a model. All of the datasets are standardized in the format presented above, which makes it easy to use the same training pipeline for multiple datasets. Examples of how to load and use the datasets with different frameworks are provided here.