Applications

Datasets

class monai.apps.MedNISTDataset(root_dir, section, transform=(), download=False, seed=0, val_frac=0.1, test_frac=0.1, cache_num=9223372036854775807, cache_rate=1.0, num_workers=0)[source]

The Dataset to automatically download MedNIST data and generate items for training, validation or test. It’s based on CacheDataset to accelerate the training process.

Parameters

  • root_dir (str) – target directory to download and load MedNIST dataset.

  • section (str) – expected data section, can be: training, validation or test.

  • transform (Union[Sequence[Callable], Callable]) – transforms to execute operations on input data.

  • download (bool) – whether to download and extract the MedNIST from resource link, default is False. if expected file already exists, skip downloading even set it to True. user can manually copy MedNIST.tar.gz file or MedNIST folder to root directory.

  • seed (int) – random seed to randomly split training, validation and test datasets, default is 0.

  • val_frac (float) – percentage of of validation fraction in the whole dataset, default is 0.1.

  • test_frac (float) – percentage of of test fraction in the whole dataset, default is 0.1.

  • cache_num (int) – number of items to be cached. Default is sys.maxsize. will take the minimum of (cache_num, data_length x cache_rate, data_length).

  • cache_rate (float) – percentage of cached data in total, default is 1.0 (cache all). will take the minimum of (cache_num, data_length x cache_rate, data_length).

  • num_workers (int) – the number of worker threads to use. if 0 a single thread will be used. Default is 0.

Raises

  • ValueError – When root_dir is not a directory.

  • RuntimeError – When dataset_dir doesn’t exist and downloading is not selected (download=False).

get_num_classes()[source]

Get number of classes.

Return type

int

randomize(data)[source]

Within this method, self.R should be used, instead of np.random, to introduce random factors.

all self.R calls happen here so that we have a better chance to identify errors of sync the random state.

This method can generate the random factors based on properties of the input data.

Raises

NotImplementedError – When the subclass does not override this method.

Return type

None

class monai.apps.DecathlonDataset(root_dir, task, section, transform=(), download=False, seed=0, val_frac=0.2, cache_num=9223372036854775807, cache_rate=1.0, num_workers=0)[source]

The Dataset to automatically download the data of Medical Segmentation Decathlon challenge (http://medicaldecathlon.com/) and generate items for training, validation or test. It will also load these properties from the JSON config file of dataset. user can call get_properties() to get specified properties or all the properties loaded. It’s based on monai.data.CacheDataset to accelerate the training process.

Parameters

  • root_dir (str) – user’s local directory for caching and loading the MSD datasets.

  • task (str) – which task to download and execute: one of list (“Task01_BrainTumour”, “Task02_Heart”, “Task03_Liver”, “Task04_Hippocampus”, “Task05_Prostate”, “Task06_Lung”, “Task07_Pancreas”, “Task08_HepaticVessel”, “Task09_Spleen”, “Task10_Colon”).

  • section (str) – expected data section, can be: training, validation or test.

  • transform (Union[Sequence[Callable], Callable]) – transforms to execute operations on input data. for further usage, use AddChanneld or AsChannelFirstd to convert the shape to [C, H, W, D].

  • download (bool) – whether to download and extract the Decathlon from resource link, default is False. if expected file already exists, skip downloading even set it to True.

  • val_frac (float) – percentage of of validation fraction in the whole dataset, default is 0.2. user can manually copy tar file or dataset folder to the root directory.

  • seed (int) – random seed to randomly shuffle the datalist before splitting into training and validation, default is 0. note to set same seed for training and validation sections.

  • cache_num (int) – number of items to be cached. Default is sys.maxsize. will take the minimum of (cache_num, data_length x cache_rate, data_length).

  • cache_rate (float) – percentage of cached data in total, default is 1.0 (cache all). will take the minimum of (cache_num, data_length x cache_rate, data_length).

  • num_workers (int) – the number of worker threads to use. if 0 a single thread will be used. Default is 0.

Raises

  • ValueError – When root_dir is not a directory.

  • ValueError – When task is not one of [“Task01_BrainTumour”, “Task02_Heart”, “Task03_Liver”, “Task04_Hippocampus”, “Task05_Prostate”, “Task06_Lung”, “Task07_Pancreas”, “Task08_HepaticVessel”, “Task09_Spleen”, “Task10_Colon”].

  • RuntimeError – When dataset_dir doesn’t exist and downloading is not selected (download=False).

Example:

transform = Compose(
    [
        LoadImaged(keys=["image", "label"]),
        AddChanneld(keys=["image", "label"]),
        ScaleIntensityd(keys="image"),
        ToTensord(keys=["image", "label"]),
    ]
)

val_data = DecathlonDataset(
    root_dir="./", task="Task09_Spleen", transform=transform, section="validation", seed=12345, download=True
)

print(val_data[0]["image"], val_data[0]["label"])
get_indices()[source]

Get the indices of datalist used in this dataset.

Return type

ndarray

get_properties(keys=None)[source]

Get the loaded properties of dataset with specified keys. If no keys specified, return all the loaded properties.

randomize(data)[source]

Within this method, self.R should be used, instead of np.random, to introduce random factors.

all self.R calls happen here so that we have a better chance to identify errors of sync the random state.

This method can generate the random factors based on properties of the input data.

Raises

NotImplementedError – When the subclass does not override this method.

Return type

None

class monai.apps.CrossValidation(dataset_cls, nfolds=5, seed=0, **dataset_params)[source]

Cross validation dataset based on the general dataset which must have _split_datalist API.

Parameters

  • dataset_cls – dataset class to be used to create the cross validation partitions. It must have _split_datalist API.

  • nfolds (int) – number of folds to split the data for cross validation.

  • seed (int) – random seed to randomly shuffle the datalist before splitting into N folds, default is 0.

  • dataset_params – other additional parameters for the dataset_cls base class.

Example of 5 folds cross validation training:

cvdataset = CrossValidation(
    dataset_cls=DecathlonDataset,
    nfolds=5,
    seed=12345,
    root_dir="./",
    task="Task09_Spleen",
    section="training",
    download=True,
)
dataset_fold0_train = cvdataset.get_dataset(folds=[1, 2, 3, 4])
dataset_fold0_val = cvdataset.get_dataset(folds=0)
# execute training for fold 0 ...

dataset_fold1_train = cvdataset.get_dataset(folds=[1])
dataset_fold1_val = cvdataset.get_dataset(folds=[0, 2, 3, 4])
# execute training for fold 1 ...

...

dataset_fold4_train = ...
# execute training for fold 4 ...
get_dataset(folds)[source]

Generate dataset based on the specified fold indice in the cross validation group.

Parameters

folds (Union[Sequence[int], int]) – index of folds for training or validation, if a list of values, concatenate the data.

Utilities

monai.apps.check_hash(filepath, val=None, hash_type='md5')[source]

Verify hash signature of specified file.

Parameters

  • filepath (str) – path of source file to verify hash value.

  • val (Optional[str]) – expected hash value of the file.

  • hash_type (str) – ‘md5’ or ‘sha1’, defaults to ‘md5’.

Return type

bool

monai.apps.download_url(url, filepath, hash_val=None, hash_type='md5')[source]

Download file from specified URL link, support process bar and hash check.

Parameters

  • url (str) – source URL link to download file.

  • filepath (str) – target filepath to save the downloaded file.

  • hash_val (Optional[str]) – expected hash value to validate the downloaded file. if None, skip hash validation.

  • hash_type (str) – ‘md5’ or ‘sha1’, defaults to ‘md5’.

Raises

  • RuntimeError – When the hash validation of the filepath existing file fails.

  • RuntimeError – When a network issue or denied permission prevents the file download from url to filepath.

  • URLError – See urllib.request.urlretrieve.

  • HTTPError – See urllib.request.urlretrieve.

  • ContentTooShortError – See urllib.request.urlretrieve.

  • IOError – See urllib.request.urlretrieve.

  • RuntimeError – When the hash validation of the url downloaded file fails.

Return type

None

monai.apps.extractall(filepath, output_dir, hash_val=None, hash_type='md5')[source]

Extract file to the output directory. Expected file types are: zip, tar.gz and tar.

Parameters

  • filepath (str) – the file path of compressed file.

  • output_dir (str) – target directory to save extracted files.

  • hash_val (Optional[str]) – expected hash value to validate the compressed file. if None, skip hash validation.

  • hash_type (str) – ‘md5’ or ‘sha1’, defaults to ‘md5’.

Raises

  • RuntimeError – When the hash validation of the filepath compressed file fails.

  • ValueError – When the filepath file extension is not one of [zip”, “tar.gz”, “tar”].

Return type

None

monai.apps.download_and_extract(url, filepath, output_dir, hash_val=None, hash_type='md5')[source]

Download file from URL and extract it to the output directory.

Parameters

  • url (str) – source URL link to download file.

  • filepath (str) – the file path of compressed file.

  • output_dir (str) – target directory to save extracted files. default is None to save in current directory.

  • hash_val (Optional[str]) – expected hash value to validate the downloaded file. if None, skip hash validation.

  • hash_type (str) – ‘md5’ or ‘sha1’, defaults to ‘md5’.

Return type

None

Deepgrow

monai.apps.deepgrow.dataset.create_dataset(datalist, output_dir, dimension, pixdim, image_key='image', label_key='label', base_dir=None, limit=0, relative_path=False, transforms=None)[source]

Utility to pre-process and create dataset list for Deepgrow training over on existing one. The input data list is normally a list of images and labels (3D volume) that needs pre-processing for Deepgrow training pipeline.

Parameters

  • datalist –

    A list of data dictionary. Each entry should at least contain ‘image_key’: <image filename>. For example, typical input data can be a list of dictionaries:

    [{'image': <image filename>, 'label': <label filename>}]

  • output_dir (str) – target directory to store the training data for Deepgrow Training

  • pixdim – output voxel spacing.

  • dimension (int) – dimension for Deepgrow training. It can be 2 or 3.

  • image_key (str) – image key in input datalist. Defaults to ‘image’.

  • label_key (str) – label key in input datalist. Defaults to ‘label’.

  • base_dir – base directory in case related path is used for the keys in datalist. Defaults to None.

  • limit (int) – limit number of inputs for pre-processing. Defaults to 0 (no limit).

  • relative_path (bool) – output keys values should be based on relative path. Defaults to False.

  • transforms – explicit transforms to execute operations on input data.

Raises

  • ValueError – When dimension is not one of [2, 3]

  • ValueError – When datalist is Empty

Return type

List[Dict]

Returns

A new datalist that contains path to the images/labels after pre-processing.

Example:

datalist = create_dataset(
    datalist=[{'image': 'img1.nii', 'label': 'label1.nii'}],
    base_dir=None,
    output_dir=output_2d,
    dimension=2,
    image_key='image',
    label_key='label',
    pixdim=(1.0, 1.0),
    limit=0,
    relative_path=True
)

print(datalist[0]["image"], datalist[0]["label"])
class monai.apps.deepgrow.interaction.Interaction(transforms, max_interactions, train, key_probability='probability')[source]

Ignite handler used to introduce interactions (simulation of clicks) for Deepgrow Training/Evaluation. This implementation is based on:

Sakinis et al., Interactive segmentation of medical images through fully convolutional neural networks. (2019) https://arxiv.org/abs/1903.08205

Parameters

  • transforms (Union[Sequence[Callable], Callable]) – execute additional transformation during every iteration (before train). Typically, several Tensor based transforms composed by Compose.

  • max_interactions (int) – maximum number of interactions per iteration

  • train (bool) – training or evaluation

  • key_probability (str) – field name to fill probability for every interaction

class monai.apps.deepgrow.transforms.AddInitialSeedPointd(label='label', guidance='guidance', sids='sids', sid='sid', connected_regions=5)[source]

Add random guidance as initial seed point for a given label.

Note that the label is of size (C, D, H, W) or (C, H, W)

The guidance is of size (2, N, # of dims) where N is number of guidance added. # of dims = 4 when C, D, H, W; # of dims = 3 when (C, H, W)

Parameters

  • label (str) – label source.

  • guidance (str) – key to store guidance.

  • sids (str) – key that represents list of valid slice indices for the given label.

  • sid (str) – key that represents the slice to add initial seed point. If not present, random sid will be chosen.

  • connected_regions (int) – maximum connected regions to use for adding initial points.

randomize(data)[source]

Within this method, self.R should be used, instead of np.random, to introduce random factors.

all self.R calls happen here so that we have a better chance to identify errors of sync the random state.

This method can generate the random factors based on properties of the input data.

Raises

NotImplementedError – When the subclass does not override this method.

class monai.apps.deepgrow.transforms.AddGuidanceSignald(image='image', guidance='guidance', sigma=2, number_intensity_ch=1, batched=False)[source]

Add Guidance signal for input image.

Based on the “guidance” points, apply gaussian to them and add them as new channel for input image.

Parameters

  • image (str) – key to the image source.

  • guidance (str) – key to store guidance.

  • sigma (int) – standard deviation for Gaussian kernel.

  • number_intensity_ch (int) – channel index.

  • batched (bool) – whether input is batched or not.

class monai.apps.deepgrow.transforms.AddRandomGuidanced(guidance='guidance', discrepancy='discrepancy', probability='probability', batched=True)[source]

Add random guidance based on discrepancies that were found between label and prediction.

If batched is True, input shape is as below:

Guidance is of shape (B, 2, N, # of dim) where B is batch size, 2 means positive and negative, N means how many guidance points, # of dim is the total number of dimensions of the image (for example if the image is CDHW, then # of dim would be 4).

Discrepancy is of shape (B, 2, C, D, H, W) or (B, 2, C, H, W)

Probability is of shape (B, 1)

else:

Guidance is of shape (2, N, # of dim)

Discrepancy is of shape (2, C, D, H, W) or (2, C, H, W)

Probability is of shape (1)

Parameters

  • guidance (str) – key to guidance source.

  • discrepancy (str) – key that represents discrepancies found between label and prediction.

  • probability (str) – key that represents click/interaction probability.

  • batched (bool) – whether input is batched or not.

randomize(data=None)[source]

Within this method, self.R should be used, instead of np.random, to introduce random factors.

all self.R calls happen here so that we have a better chance to identify errors of sync the random state.

This method can generate the random factors based on properties of the input data.

Raises

NotImplementedError – When the subclass does not override this method.

class monai.apps.deepgrow.transforms.AddGuidanceFromPointsd(ref_image, guidance='guidance', foreground='foreground', background='background', axis=0, depth_first=True, dimensions=2, slice_key='slice', meta_key_postfix='meta_dict')[source]

Add guidance based on user clicks.

We assume the input is loaded by LoadImaged and has the shape of (H, W, D) originally. Clicks always specify the coordinates in (H, W, D)

If depth_first is True:

Input is now of shape (D, H, W), will return guidance that specifies the coordinates in (D, H, W)

else:

Input is now of shape (H, W, D), will return guidance that specifies the coordinates in (H, W, D)

Parameters

  • ref_image – key to reference image to fetch current and original image details.

  • guidance (str) – output key to store guidance.

  • foreground (str) – key that represents user foreground (+ve) clicks.

  • background (str) – key that represents user background (-ve) clicks.

  • axis (int) – axis that represents slices in 3D volume. (axis to Depth)

  • depth_first (bool) – if depth (slices) is positioned at first dimension.

  • dimensions (int) – dimensions based on model used for deepgrow (2D vs 3D).

  • slice_key (str) – key that represents applicable slice to add guidance.

  • meta_key_postfix (str) – use {ref_image}_{postfix} to to fetch the meta data according to the key data, default is meta_dict, the meta data is a dictionary object. For example, to handle key image, read/write affine matrices from the metadata image_meta_dict dictionary’s affine field.

class monai.apps.deepgrow.transforms.SpatialCropForegroundd(keys, source_key, spatial_size, select_fn=<function SpatialCropForegroundd.<lambda>>, channel_indices=None, margin=0, meta_key_postfix='meta_dict', start_coord_key='foreground_start_coord', end_coord_key='foreground_end_coord', original_shape_key='foreground_original_shape', cropped_shape_key='foreground_cropped_shape', allow_missing_keys=False)[source]

Crop only the foreground object of the expected images.

Difference VS monai.transforms.CropForegroundd:

  1. If the bounding box is smaller than spatial size in all dimensions then this transform will crop the object using box’s center and spatial_size.

  2. This transform will set “start_coord_key”, “end_coord_key”, “original_shape_key” and “cropped_shape_key” in data[{key}_{meta_key_postfix}]

The typical usage is to help training and evaluation if the valid part is small in the whole medical image. The valid part can be determined by any field in the data with source_key, for example:

  • Select values > 0 in image field as the foreground and crop on all fields specified by keys.

  • Select label = 3 in label field as the foreground to crop on all fields specified by keys.

  • Select label > 0 in the third channel of a One-Hot label field as the foreground to crop all keys fields.

Users can define arbitrary function to select expected foreground from the whole source image or specified channels. And it can also add margin to every dim of the bounding box of foreground object.

Parameters

  • keys (Union[Collection[Hashable], Hashable]) – keys of the corresponding items to be transformed. See also: monai.transforms.MapTransform

  • source_key (str) – data source to generate the bounding box of foreground, can be image or label, etc.

  • spatial_size (Union[Sequence[int], ndarray]) – minimal spatial size of the image patch e.g. [128, 128, 128] to fit in.

  • select_fn (Callable) – function to select expected foreground, default is to select values > 0.

  • channel_indices (Union[Iterable[int], int, None]) – if defined, select foreground only on the specified channels of image. if None, select foreground on the whole image.

  • margin (int) – add margin value to spatial dims of the bounding box, if only 1 value provided, use it for all dims.

  • meta_key_postfix – use {key}_{meta_key_postfix} to to fetch/store the meta data according to the key data, default is meta_dict, the meta data is a dictionary object. For example, to handle key image, read/write affine matrices from the metadata image_meta_dict dictionary’s affine field.

  • start_coord_key (str) – key to record the start coordinate of spatial bounding box for foreground.

  • end_coord_key (str) – key to record the end coordinate of spatial bounding box for foreground.

  • original_shape_key (str) – key to record original shape for foreground.

  • cropped_shape_key (str) – key to record cropped shape for foreground.

  • allow_missing_keys (bool) – don’t raise exception if key is missing.

class monai.apps.deepgrow.transforms.SpatialCropGuidanced(keys, guidance, spatial_size, margin=20, meta_key_postfix='meta_dict', start_coord_key='foreground_start_coord', end_coord_key='foreground_end_coord', original_shape_key='foreground_original_shape', cropped_shape_key='foreground_cropped_shape', allow_missing_keys=False)[source]

Crop image based on guidance with minimal spatial size.

  • If the bounding box is smaller than spatial size in all dimensions then this transform will crop the object using box’s center and spatial_size.

  • This transform will set “start_coord_key”, “end_coord_key”, “original_shape_key” and “cropped_shape_key” in data[{key}_{meta_key_postfix}]

Input data is of shape (C, spatial_1, [spatial_2, …])

Parameters

  • keys (Union[Collection[Hashable], Hashable]) – keys of the corresponding items to be transformed.

  • guidance (str) – key to the guidance. It is used to generate the bounding box of foreground

  • spatial_size – minimal spatial size of the image patch e.g. [128, 128, 128] to fit in.

  • margin – add margin value to spatial dims of the bounding box, if only 1 value provided, use it for all dims.

  • meta_key_postfix – use key_{postfix} to to fetch the meta data according to the key data, default is meta_dict, the meta data is a dictionary object. For example, to handle key image, read/write affine matrices from the metadata image_meta_dict dictionary’s affine field.

  • start_coord_key (str) – key to record the start coordinate of spatial bounding box for foreground.

  • end_coord_key (str) – key to record the end coordinate of spatial bounding box for foreground.

  • original_shape_key (str) – key to record original shape for foreground.

  • cropped_shape_key (str) – key to record cropped shape for foreground.

  • allow_missing_keys (bool) – don’t raise exception if key is missing.

class monai.apps.deepgrow.transforms.RestoreLabeld(keys, ref_image, slice_only=False, mode=<InterpolateMode.NEAREST: 'nearest'>, align_corners=None, meta_key_postfix='meta_dict', start_coord_key='foreground_start_coord', end_coord_key='foreground_end_coord', original_shape_key='foreground_original_shape', cropped_shape_key='foreground_cropped_shape', allow_missing_keys=False)[source]

Restores label based on the ref image.

The ref_image is assumed that it went through the following transforms:

  1. Fetch2DSliced (If 2D)

  2. Spacingd

  3. SpatialCropGuidanced

  4. Resized

And its shape is assumed to be (C, D, H, W)

This transform tries to undo these operation so that the result label can be overlapped with original volume. It does the following operation:

  1. Undo Resized

  2. Undo SpatialCropGuidanced

  3. Undo Spacingd

  4. Undo Fetch2DSliced

The resulting label is of shape (D, H, W)

Parameters

  • keys (Union[Collection[Hashable], Hashable]) – keys of the corresponding items to be transformed.

  • ref_image (str) – reference image to fetch current and original image details

  • slice_only (bool) – apply only to an applicable slice, in case of 2D model/prediction

  • mode (Union[Sequence[Union[InterpolateMode, str]], InterpolateMode, str]) – {"constant", "edge", "linear_ramp", "maximum", "mean", "median", "minimum", "reflect", "symmetric", "wrap", "empty"} One of the listed string values or a user supplied function for padding. Defaults to "constant". See also: https://numpy.org/doc/1.18/reference/generated/numpy.pad.html

  • align_corners (Union[Sequence[Optional[bool]], bool, None]) – Geometrically, we consider the pixels of the input as squares rather than points. See also: https://pytorch.org/docs/stable/nn.functional.html#grid-sample It also can be a sequence of bool, each element corresponds to a key in keys.

  • meta_key_postfix (str) – use {ref_image}_{meta_key_postfix} to to fetch the meta data according to the key data, default is meta_dict, the meta data is a dictionary object. For example, to handle key image, read/write affine matrices from the metadata image_meta_dict dictionary’s affine field.

  • start_coord_key (str) – key that records the start coordinate of spatial bounding box for foreground.

  • end_coord_key (str) – key that records the end coordinate of spatial bounding box for foreground.

  • original_shape_key (str) – key that records original shape for foreground.

  • cropped_shape_key (str) – key that records cropped shape for foreground.

  • allow_missing_keys (bool) – don’t raise exception if key is missing.

class monai.apps.deepgrow.transforms.ResizeGuidanced(guidance, ref_image, meta_key_postfix='meta_dict', cropped_shape_key='foreground_cropped_shape')[source]

Resize the guidance based on cropped vs resized image.

This transform assumes that the images have been cropped and resized. And the shape after cropped is store inside the meta dict of ref image.

Parameters

  • guidance (str) – key to guidance

  • ref_image (str) – key to reference image to fetch current and original image details

  • meta_key_postfix – use {ref_image}_{postfix} to to fetch the meta data according to the key data, default is meta_dict, the meta data is a dictionary object. For example, to handle key image, read/write affine matrices from the metadata image_meta_dict dictionary’s affine field.

  • cropped_shape_key (str) – key that records cropped shape for foreground.

class monai.apps.deepgrow.transforms.FindDiscrepancyRegionsd(label='label', pred='pred', discrepancy='discrepancy', batched=True)[source]

Find discrepancy between prediction and actual during click interactions during training.

If batched is true:

label is in shape (B, C, D, H, W) or (B, C, H, W) pred has same shape as label discrepancy will have shape (B, 2, C, D, H, W) or (B, 2, C, H, W)

Parameters

  • label (str) – key to label source.

  • pred (str) – key to prediction source.

  • discrepancy (str) – key to store discrepancies found between label and prediction.

  • batched (bool) – whether input is batched or not.

class monai.apps.deepgrow.transforms.FindAllValidSlicesd(label='label', sids='sids')[source]

Find/List all valid slices in the label. Label is assumed to be a 4D Volume with shape CDHW, where C=1.

Parameters

  • label (str) – key to the label source.

  • sids (str) – key to store slices indices having valid label map.

class monai.apps.deepgrow.transforms.Fetch2DSliced(keys, guidance='guidance', axis=0, meta_key_postfix='meta_dict', allow_missing_keys=False)[source]

Fetch one slice in case of a 3D volume.

The volume only contains spatial coordinates.

Parameters

  • keys – keys of the corresponding items to be transformed.

  • guidance – key that represents guidance.

  • axis (int) – axis that represents slice in 3D volume.

  • meta_key_postfix (str) – use key_{meta_key_postfix} to to fetch the meta data according to the key data, default is meta_dict, the meta data is a dictionary object. For example, to handle key image, read/write affine matrices from the metadata image_meta_dict dictionary’s affine field.

  • allow_missing_keys (bool) – don’t raise exception if key is missing.

Pathology

class monai.apps.pathology.datasets.PatchWSIDataset(data, region_size, grid_shape, patch_size, transform=None, image_reader_name='cuCIM')[source]

This dataset reads whole slide images, extracts regions, and creates patches. It also reads labels for each patch and provides each patch with its associated class labels.

Parameters

  • data (List) – the list of input samples including image, location, and label (see the note below for more details).

  • region_size (Union[int, Tuple[int, int]]) – the size of regions to be extracted from the whole slide image.

  • grid_shape (Union[int, Tuple[int, int]]) – the grid shape on which the patches should be extracted.

  • patch_size (Union[int, Tuple[int, int]]) – the size of patches extracted from the region on the grid.

  • transform (Optional[Callable]) – transforms to be executed on input data.

  • image_reader_name (str) – the name of library to be used for loading whole slide imaging, either CuCIM or OpenSlide. Defaults to CuCIM.

Note

The input data has the following form as an example: [{“image”: “path/to/image1.tiff”, “location”: [200, 500], “label”: [0,0,0,1]}].

This means from “image1.tiff” extract a region centered at the given location location with the size of region_size, and then extract patches with the size of patch_size from a grid with the shape of grid_shape. Be aware the the grid_shape should construct a grid with the same number of element as labels, so for this example the grid_shape should be (2, 2).

Args: data: input data to load and transform to generate dataset for model. transform: a callable data transform on input data.

class monai.apps.pathology.datasets.SmartCachePatchWSIDataset(data, region_size, grid_shape, patch_size, transform, image_reader_name='cuCIM', replace_rate=0.5, cache_num=9223372036854775807, cache_rate=1.0, num_init_workers=None, num_replace_workers=None, progress=True)[source]

Add SmartCache functionality to PatchWSIDataset.

Parameters

  • data (List) – the list of input samples including image, location, and label (see PatchWSIDataset for more details)

  • region_size (Union[int, Tuple[int, int]]) – the region to be extracted from the whole slide image.

  • grid_shape (Union[int, Tuple[int, int]]) – the grid shape on which the patches should be extracted.

  • patch_size (Union[int, Tuple[int, int]]) – the size of patches extracted from the region on the grid.

  • image_reader_name (str) – the name of library to be used for loading whole slide imaging, either CuCIM or OpenSlide. Defaults to CuCIM.

  • transform (Union[Sequence[Callable], Callable]) – transforms to be executed on input data.

  • replace_rate (float) – percentage of the cached items to be replaced in every epoch.

  • cache_num (int) – number of items to be cached. Default is sys.maxsize. will take the minimum of (cache_num, data_length x cache_rate, data_length).

  • cache_rate (float) – percentage of cached data in total, default is 1.0 (cache all). will take the minimum of (cache_num, data_length x cache_rate, data_length).

  • num_init_workers (Optional[int]) – the number of worker threads to initialize the cache for first epoch. If num_init_workers is None then the number returned by os.cpu_count() is used.

  • num_replace_workers (Optional[int]) – the number of worker threads to prepare the replacement cache for every epoch. If num_replace_workers is None then the number returned by os.cpu_count() is used.

  • progress (bool) – whether to display a progress bar when caching for the first epoch.

class monai.apps.pathology.datasets.MaskedInferenceWSIDataset(data, patch_size, transform=None, image_reader_name='cuCIM')[source]

This dataset load the provided foreground masks at an arbitrary resolution level, and extract patches based on that mask from the associated whole slide image.

Parameters

  • data (List[Dict[str, str]]) – a list of sample including the path to the whole slide image and the path to the mask. Like this: [{“image”: “path/to/image1.tiff”, “mask”: “path/to/mask1.npy}, …]”.

  • patch_size (Union[int, Tuple[int, int]]) – the size of patches to be extracted from the whole slide image for inference.

  • transform (Optional[Callable]) – transforms to be executed on extracted patches.

  • image_reader_name (str) – the name of library to be used for loading whole slide imaging, either CuCIM or OpenSlide.

  • to CuCIM. (Defaults) –

Note

The resulting output (probability maps) after performing inference using this dataset is

supposed to be the same size as the foreground mask and not the original wsi image size.

Args: data: input data to load and transform to generate dataset for model. transform: a callable data transform on input data.

class monai.apps.pathology.handlers.ProbMapProducer(output_dir='./', output_postfix='', dtype=<class 'numpy.float64'>, name=None)[source]

Event handler triggered on completing every iteration to save the probability map

Parameters

  • output_dir (str) – output directory to save probability maps.

  • output_postfix (str) – a string appended to all output file names.

  • dtype (Union[dtype, type, None]) – the data type in which the probability map is stored. Default np.float64.

  • name (Optional[str]) – identifier of logging.logger to use, defaulting to engine.logger.

attach(engine)[source]
Parameters

engine (Engine) – Ignite Engine, it can be a trainer, validator or evaluator.

Return type

None

save_prob_map(name)[source]

This method save the probability map for an image, when its inference is finished, and delete that probability map from memory.

Parameters

name (str) – the name of image to be saved.

Return type

None

class monai.apps.pathology.metrics.LesionFROC(data, grow_distance=75, itc_diameter=200, eval_thresholds=(0.25, 0.5, 1, 2, 4, 8), nms_sigma=0.0, nms_prob_threshold=0.5, nms_box_size=48, image_reader_name='cuCIM')[source]

Evaluate with Free Response Operating Characteristic (FROC) score.

Parameters

  • data (List[Dict]) – either the list of dictionaries containing probability maps (inference result) and tumor mask (ground truth), as below, or the path to a json file containing such list. { “prob_map”: “path/to/prob_map_1.npy”, “tumor_mask”: “path/to/ground_truth_1.tiff”, “level”: 6, “pixel_spacing”: 0.243 }

  • grow_distance (int) – Euclidean distance (in micrometer) by which to grow the label the ground truth’s tumors. Defaults to 75, which is the equivalent size of 5 tumor cells.

  • itc_diameter (int) – the maximum diameter of a region (in micrometer) to be considered as an isolated tumor cell. Defaults to 200.

  • eval_thresholds (Tuple) – the false positive rates for calculating the average sensitivity. Defaults to (0.25, 0.5, 1, 2, 4, 8) which is the same as the CAMELYON 16 Challenge.

  • nms_sigma (float) – the standard deviation for gaussian filter of non-maximal suppression. Defaults to 0.0.

  • nms_prob_threshold (float) – the probability threshold of non-maximal suppression. Defaults to 0.5.

  • nms_box_size (int) – the box size (in pixel) to be removed around the the pixel for non-maximal suppression.

  • image_reader_name (str) – the name of library to be used for loading whole slide imaging, either CuCIM or OpenSlide. Defaults to CuCIM.

Note

For more info on nms_* parameters look at monai.utils.prob_nms.ProbNMS`.

compute_fp_tp()[source]

Compute false positive and true positive probabilities for tumor detection, by comparing the model outputs with the prepared ground truths for all samples

evaluate()[source]

Evaluate the detection performance of a model based on the model probability map output, the ground truth tumor mask, and their associated metadata (e.g., pixel_spacing, level)

prepare_ground_truth(sample)[source]

Prepare the ground truth for evaluation based on the binary tumor mask

prepare_inference_result(sample)[source]

Prepare the probability map for detection evaluation.

monai.apps.pathology.utils.compute_multi_instance_mask(mask, threshold)[source]

This method computes the segmentation mask according to the binary tumor mask.

Parameters

  • mask (ndarray) – the binary mask array

  • threshold (float) – the threshold to fill holes

monai.apps.pathology.utils.compute_isolated_tumor_cells(tumor_mask, threshold)[source]

This method computes identifies Isolated Tumor Cells (ITC) and return their labels.

Parameters

  • tumor_mask (ndarray) – the tumor mask.

  • threshold (float) – the threshold (at the mask level) to define an isolated tumor cell (ITC). A region with the longest diameter less than this threshold is considered as an ITC.

Return type

List[int]

class monai.apps.pathology.utils.PathologyProbNMS(spatial_dims=2, sigma=0.0, prob_threshold=0.5, box_size=48)[source]

This class extends monai.utils.ProbNMS and add the resolution option for Pathology.