Skip to content

Latest commit

 

History

History
183 lines (136 loc) · 9.66 KB

README.md

File metadata and controls

183 lines (136 loc) · 9.66 KB

ETAB: A Benchmark Suite for Visual Representation Learning in Echocardiography


What is ETAB?Getting StartedUsing ETABDocumentationContributingCommunityPaper


Python 3.6+ PyTorch 1.1.0

Echocardiography is one of the most commonly used non-invasive imaging techniques for assessing cardiac function, examining heart anatomy and diagnosing cardiovascular diseases. An echo study is an ultrasound of the heart acquired by a cardiac sonographer through a transducer device. Different acquisition angles by which the device is placed relative to the patient's heart provide different views of the heart anatomy. Echocardiograms inform cardiologists, surgeons, oncologists and emergency physicians on clinical decisions pertaining to treatment management and surgical planning. Because of the central role it plays in cardiovascular medicine, there has been a significant interest in applying deep learning-based computer vision models to echocardiograms, with the ultimate goal of automating cardiac evaluation, reducing variance and improving reproducibility in interpreting echocardiograms, and predicting patient-specific clinical outcomes.


🫀 What is ETAB?

The echocardiographic task adaptation benchmark (ETAB) is a software library that provides a unified and easy-to-use API for developing and testing visual representation learning algorithms across a diverse set of echocardiohraphic tasks of interest using various publicly accessible datasets. ETAB offers:

  • A unified API for loading and processing various publicly-accessible echocardiography datasets.
  • A comprehensive suite of (transfer learning and downstream) benchmark tasks tailored to echocardiography.
  • An easy-to-use API for creating modeling pipelines that supports a wide variety of backbone architectures and covers different types of downstream tasks of interest.
  • A unified evaluation protocol for pre-trained echocardiographic representations.

The ETAB library is meant to provide a self-sufficient framework for developing and evaluating visual representations of echocardiograms by creating a metadataset that encapsulates various publicly-accessible data sources. You can use ETAB in your research to develop new models for echocardiography or evaluate pre-trained representations derived from external data sources.


🏃 Getting Started

Step 1: Install the ETAB package

Installation from source (recommended)

$git clone https://github.com/ahmedmalaa/ETAB.git 
$pip install -r <path-to-repo>/ETAB/requirements.txt

Simple installation from PyPI (experimental)

$pip install etab

Step 2: Download the datasets

The current version of ETAB supports three echocardiography datasets. Details of all datasets can be found in Section 1 of the documentation below. Please note that ETAB provides a standardized API for loading and processing data from different sources, but it does not alter, redistribute or directly share the datasets. To download the data, please follow the instructions in Section 1 of the documentation below.


🛠️ Using ETAB

You can run any benchmark task supported by ETAB using the following CLI

$ python run_benchmark.py --task <str: Task Code> --backbone <str: Backbone representation> \
                          --head <str: Task-specific head> \ 
                          --freeze_backbone <bool: Fully finetune?> \
                          --train_frac <int: fraction of data used for training> \
                          --val_frac <int: fraction of data used for validation> \
                          --lr <float: learning rate> --epochs <int: number of epochs> --batch <int: batch size> 

The task encoding convention and the ETAB model zoo are described in detail in Section 2 of the documentation.

You can also write your own customized program using the ETAB API. A simple example for a customized program is one that evaluates the quality of a pre-trained representation with respect to the echocardiographic tasks by computing the ETAB score. In the following program, we compute the ETAB score for the ResNet-50 backbone pre-trained on ImageNet-1K.

from etab.scores import ETABscore
from torchvision.models import resnet50
                   
backbone    = resnet50(weights="IMAGENET1K_V1")

etab_score  = ETABscore(backbone_architecture="ResNet-50", backbone_model=backbone)

The ETAB library provides a succint API for echocardiographic datasets, models, and benchmark tasks that enables writing more sophisticated programs within your research project. Details of the ETAB API along with usage examples and demo notebooks are provided in the documentation below.


📚 Documentation

To start using the ETAB library in your research, visit the documentation sections below to learn more about its different features and use cases through step-by-step instructions and demo notebooks.

Explore Content (click to expand)  
Explore Content (click to expand)  
Explore Content (click to expand)  
Explore Content (click to expand)  

🏆 ETAB Leaderboard

An online leaderboard hosted on this repo keeps track of the best performing backbone architectures with respect to benchmark echocardiographic tasks. Users can contribute new pre-trained backbone models to the ETAB library and submit their models to the leaderboard. Visit this link to learn more!

Latest update August 28, 2022
Current status Running 🔴 Cardiac structure identification benchmarks
Progress 5 out of 19 benchmark tasks completed 26%
10 out of 14 baseline models evaluated 71%

🤝 Community

Connect with other researchers for questions or discussions by joining the ETAB community on Slack!