MAPLES-DR Quick API

Downloading, formating and saving MAPLES-DR data in memory or on the disk can be done quite simply using maples_dr quick API.

All the following function are imported either from maples_dr.quick_api or directly from the maples_dr module:

from maples_dr import configure, load_train_set, load_test_set, export_train_set, export_test_set
configure(maples_dr_path='UNSET', messidor_path='UNSET', *, cache='UNSET', resize=None, image_format=None, preprocessing=None, exclude_missing_macula=None, exclude_missing_cup=None, disable_check=False)

Configure the default behavior of the MAPLES-DR dataset.

Any parameters left to None (or “UNSET” for the first two paths) will leave the current configuration unaffected.

Paramètres:

  • maples_dr_path (Optional[str], optional) –

    Path to the MAPLES-DR additional data. Must point to the directory or to the zip file.

    If None (by default), then the dataset is downloaded from figshare.

  • messidor_path (Optional[str], optional) –

    Path to the MESSIDOR dataset.

    Must point to a directory containing the « Base11 », « Base12 », … subdirectories or zip files.

  • cache (Optional[str], optional) –

    Path to the cache directory. The cache is used to store the downloaded dataset and the generated images.

    • If cache is a str or a Path, then the cache is stored in the given directory.

    • If False (by default), then the cache is disabled.

    • If True, then the cache is stored in the default cache directory.

  • resize (Optional[int], optional) –

    Set the size of the images (fundus and biomarkers) generated by maples_dr.

    • If resize is an int, crop the image to a square ROI and resize it to the shape (resize, resize);

    • If True, keep the original MAPLES-DR resolution of 1500x1500 px;

    • If False, use the original MESSIDOR resolution if MESSIDOR path is configured, otherwise fallback to MAPLES-DR original resolution.

  • image_format (Optional[ImageFormat], optional) –

    Python format of the generated images. Must be either « PIL », « rgb » or « bgr ».

    If « rgb » or « bgr » is selected, images will be formatted as numpy array of shape: (height, width, channel).

    By default, « PIL » is used.

  • preprocessing (Optional[Preprocessing], optional) –

    Preprocessing algorithm applied on the fundus images.

    By default, no preprocessing is applied.

  • disable_check (bool, optional) – If True, disable the integrity check of the dataset.

  • exclude_missing_macula (bool, optional) –

    If True, exclude images with missing macula segmentation (one image of the train set).

    By default: False.

  • exclude_missing_cup (bool, optional) –

    If True, exclude images with missing optic cup segmentation (4 images of the train set, 2 of the test set).

    By default: False.

load_train_set()

Load the training set.

MAPLES-DR training set contains labels of pathological and anatomical structures for 138 fundus images. The dataset is return as a Dataset object, which is equivalent to a list of samples. Each sample being stored as a dictionary with the following fields:

  • "fundus": The fundus image. (MESSIDOR path must have been configured!)

  • "optic_cup": The optic cup mask.

  • "optic_disc": The optic disc mask.

  • "macula": The macula mask.

  • "vessels": The red lesions mask.

  • "cotton_wool_spots": The cotton wool spots mask.

  • "exudates": The exudates mask.

  • "drusens": The drusens mask.

  • "bright_uncertain": The mask of bright lesions with uncertain type (CWS, exudates or drusens).

  • "microaneurysms": The microaneurysms mask.

  • "hemorrhages": The hemorrhages mask.

  • "neovascularization": The neovascularization mask.

  • "red_uncertains": The mask of red lesions with uncertain type (microaneuryms or hemorrhages).

  • "dr": The Diabetic Retinopathy grade ('R0', 'R1', 'R2', 'R3', 'R4A'). See Grades de DR et de ME for more information.

  • "me": The Macular Edema grade ('M0', 'M1', 'M2'). See Grades de DR et de ME for more information.

Renvoie:

The training set.

Type renvoyé:

Dataset

Exemples

>>> import maples_dr
>>> maples_dr.configure(messidor_path="path/to/messidor/directory/")
>>> train_set = maples_dr.load_train_set()
>>> for sample in train_set:
>>>     fundus = sample["fundus"]           # The fundus image
>>>     vessels = sample["vessels"]         # The vessels mask
>>>     dr = sample["dr"]                   # The Diabetic Retinopathy grade
load_test_set()

Load the testing set.

See load_train_set() for more details.

Renvoie:

The testing set.

Type renvoyé:

Dataset

load_dataset(subset=DatasetSubset.ALL)

Load specific subset of the dataset (by default load the whole dataset without the duplicates).

Paramètres:

subset (DatasetSubset | str | list[str]) – The subset to load (see DatasetSubset for the available options), or a list of image names.

Renvoie:

The corresponding subset of MAPLES-DR. See load_train_set() for more details on the data format.

Type renvoyé:

Dataset

export_train_set(path, fields=None, fundus_as_jpg=True, n_workers=None)

Save the training set to a folder.

Paramètres:

  • path (str | Path) – The path to the directory where

  • fields (FundusField | BiomarkerField | List[FundusField | BiomarkerField] | Dict[FundusField | BiomarkerField, str] | None) –

    The field or list of fields to save. If None (by default), all fields will be saved.

    See maples_dr.dataset.ImageField for the list of available fields.

  • fundus_as_jpg (bool) – Whether to save the fundus images as JPG files. If False, the fundus images will be saved as PNG files. JPG format will drastically reduce the load time of the dataset, but may introduce compression artifacts.

  • n_workers (int | None) –

    The number of workers to use for exporting the dataset.

    If None (by default), the number of workers is automatically determined based on the number of available CPUs.

Type renvoyé:

None

Exemples

>>> import maples_dr
>>> maples_dr.configure(messidor_path="path/to/messidor/directory/")
>>> export_train_set("path/to/save", fields=["fundus", "red_lesions", "vessels"])
export_test_set(path, fields=None, fundus_as_jpg=True, n_workers=None)

Save the testing set to a folder.

Paramètres:

  • path (str | Path) – The path to save the dataset to.

  • fields (FundusField | BiomarkerField | List[FundusField | BiomarkerField] | Dict[FundusField | BiomarkerField, str] | None) –

    The field or list of fields to save. If None (by default), all fields will be saved.

    See maples_dr.dataset.ImageField for the list of available fields.

  • fundus_as_jpg (bool) – Whether to save the fundus images as JPG files. If False, the fundus images will be saved as PNG files. JPG format will drastically reduce the load time of the dataset, but may introduce compression artifacts.

  • n_workers (int | None) –

    The number of workers to use for exporting the dataset.

    If None (by default), the number of workers is automatically determined based on the number of available CPUs.

Exemples

>>> import maples_dr
>>> maples_dr.configure(messidor_path="path/to/messidor/directory/")
>>> export_test_set("path/to/save", fields=["fundus", "red_lesions", "vessels"])
clear_cache()

Clear the cache directory.

clear_download_cache()

Clear the download cache directory.