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
).
-
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_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 ...
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. If undefined, os.path.basename(url) will be used.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
tofilepath
.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', file_type='')[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’.file_type (
str
) – string of file type for decompressing. Leave it empty to infer the type from the filepath basename.
- Raises
RuntimeError – When the hash validation of the
filepath
compressed file fails.NotImplementedError – 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', file_type='')[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 the downloaded compressed file. use this option to keep the directly downloaded compressed file, to avoid further repeated downloads.output_dir (
str
) – target directory to save extracted files. default is the 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’.file_type (
str
) – string of file type for decompressing. Leave it empty to infer the type from url’s base file name.
- 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 Trainingpixdim – 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 iterationtrain (
bool
) – training or evaluationkey_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
: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}]
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 foregroundspatial_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:
Fetch2DSliced (If 2D)
Spacingd
SpatialCropGuidanced
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:
Undo Resized
Undo SpatialCropGuidanced
Undo Spacingd
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 detailsslice_only (
bool
) – apply only to an applicable slice, in case of 2D model/predictionmode (
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.htmlalign_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 inkeys
.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 guidanceref_image (
str
) – key to reference image to fetch current and original image detailsmeta_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.
-
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)
-
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 arraythreshold (
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
]