Patch locations/sampling pool classes¶

dplabtools offers a set of Pool classes providing a parallel execution interface for classes described in Patch locations/sampling. Using pool classes for calculating patch locations allows for the processing of multiple WSIs at the same time as well as automatically collecting patch and label counts for an entire collection of WSIs. Additionally, patch location pool classes can be fed directly into Patch extraction pool classes for the actual patch extraction process.

Pool classes for patches on whole images¶

The following pool classes share the same execution interface:

class dplabtools.slides.patches.WholeImageRandomPatchesPool(...)¶: Patches pool implementation for WholeImageRandomPatches.

class dplabtools.slides.patches.WholeImagePoissonDiskPatchesPool(...)¶: Patches pool implementation for WholeImagePoissonDiskPatches.

class dplabtools.slides.patches.WholeImageGridPatchesPool(...)¶: Patches pool implementation for WholeImageGridPatches.

Basic usage¶

Conversion of the code that processes a single WSI:

from dplabtools.slides.patches import WholeImageRandomPatches

wsi_file = "/tmp/wsi1.svs"
mask_file = "/tmp/mask1.png"

random_patches = WholeImageRandomPatches(
    wsi_file=wsi_file,
    mask_data=mask_file,
    patch_size=256,
    num_patches=20,
)

into the code where three WSIs are processed simultaneously using the same set of arguments:

from dplabtools.slides.patches import WholeImageRandomPatchesPool

wsi_file_list = ["/tmp/wsi1.svs", "/tmp/wsi2.svs", "/tmp/wsi3.svs"]
mask_data_list = ["/tmp/mask1.png", "/tmp/mask2.png", "/tmp/mask3.png"]

patches_args = {
    "patch_size": 256,
    "num_patches": 20,
}

random_patches_pool = WholeImageRandomPatchesPool(
    wsi_file_list=wsi_file_list,
    mask_data_list=mask_data_list,
    patches_args=patches_args,
    proc_num_workers=3,
)

See also

patches_args

Class details¶

Pool classes for patches on whole images have no class specific parameters.

Pool classes for inverted patches on whole images¶

The following pool classes share the same execution interface:

class dplabtools.slides.patches.WholeImageInvertedRandomPatchesPool(...)¶: Patches pool implementation for WholeImageInvertedRandomPatches.

class dplabtools.slides.patches.WholeImageInvertedPoissonDiskPatchesPool(...)¶: Patches pool implementation for WholeImageInvertedPoissonDiskPatches.

class dplabtools.slides.patches.WholeImageInvertedGridPatchesPool(...)¶: Patches pool implementation for WholeImageInvertedGridPatches.

Basic usage¶

Conversion of the code that processes a single WSI:

from dplabtools.slides.patches import WholeImageInvertedPoissonDiskPatches

wsi_file = "/tmp/wsi1.svs"
mask_file = "/tmp/mask1.png"
polygons = [poly1, poly2] # list elements are not defined here

poisson_patches = WholeImageInvertedPoissonDiskPatches(
    wsi_file=wsi_file,
    mask_data=mask_file,
    patch_size=256,
    poisson_spacing=50,
    polygon_data=polygons,
)

into the code where three WSIs are processed simultaneously using the same set of arguments:

from dplabtools.slides.patches import WholeImageInvertedPoissonDiskPatchesPool

wsi_file_list = ["/tmp/wsi1.svs", "/tmp/wsi2.svs", "/tmp/wsi3.svs"]
mask_data_list = ["/tmp/mask1.png", "/tmp/mask2.png", "/tmp/mask3.png"]
polygon_data_list = [polygons1, polygons2, polygons3] # list elements are not defined here

patches_args = {
    "patch_size": 256,
    "poisson_spacing": 50,
}

poisson_patches_pool = WholeImageInvertedPoissonDiskPatchesPool(
    wsi_file_list=wsi_file_list,
    mask_data_list=mask_data_list,
    polygon_data_list=polygon_data_list,
    patches_args=patches_args,
    proc_num_workers=3,
)

See also

patches_args

Class details¶

Parameters specific to pool classes for inverted patches on whole images:

class dplabtoolshiddenclass_5f6126d2fd454c8ebc41fa49a6b68bc0

Parameters:: polygon_data_list (list of objects) – Polygon data representing excluded regions for different WSIs. Each data element is a list of AnnotationPolygon objects or a JSON file/string.

Pool classes for patches on polygon regions¶

The following pool classes share the same execution interface:

class dplabtools.slides.patches.PolygonRegionRandomPatchesPool(...)¶: Patches pool implementation for PolygonRegionRandomPatches.

class dplabtools.slides.patches.PolygonRegionPoissonDiskPatchesPool(...)¶: Patches pool implementation for PolygonRegionPoissonDiskPatches.

class dplabtools.slides.patches.PolygonRegionGridPatchesPool(...)¶: Patches pool implementation for PolygonRegionGridPatches.

Basic usage¶

Conversion of the code that processes a single WSI:

from dplabtools.slides.patches import PolygonRegionGridPatches

wsi_file = "/tmp/wsi1.svs"
mask_file = "/tmp/mask1.png"
polygons = [poly1, poly2] # list elements are not defined here

grid_patches = PolygonRegionGridPatches(
    wsi_file=wsi_file,
    mask_data=mask_file,
    patch_size=256,
    patch_stride=1,
    polygon_data=polygons,
)

into the code where three WSIs are processed simultaneously using the same set of arguments:

from dplabtools.slides.patches import PolygonRegionGridPatchesPool

wsi_file_list = ["/tmp/wsi1.svs", "/tmp/wsi2.svs", "/tmp/wsi3.svs"]
mask_data_list = ["/tmp/mask1.png", "/tmp/mask2.png", "/tmp/mask3.png"]
polygon_data_list = [polygons1, polygons2, polygons3] # list elements are not defined here

patches_args = {
    "patch_size": 256,
    "patch_stride": 1,
}

grid_patches_pool = PolygonRegionGridPatchesPool(
    wsi_file_list=wsi_file_list,
    mask_data_list=mask_data_list,
    polygon_data_list=polygon_data_list,
    patches_args=patches_args,
    proc_num_workers=3,
)

See also

patches_args

Class details¶

Parameters specific to pool classes for patches on polygon regions:

class dplabtoolshiddenclass_3b1a09f83c844024887e61357d305fc2

Parameters:: polygon_data_list (list of objects) – Polygon data representing regions of interest for different WSIs. Each data element is a list of AnnotationPolygon objects or a JSON file/string.

patches_args¶

patches_args is a Python dictionary object which should hold all necessary arguments for the Patch locations/sampling class of the user interest.

Preview images¶

Similarly to the Patch locations/sampling classes, patch related pool classes can also generate preview images for each processed WSI. Arguments passed to the save_preview_image method should be passed in a Python dictionary object assigned to save_preview_image_args:

from dplabtools.slides.patches import WholeImageRandomPatchesPool

wsi_file_list = ["/tmp/wsi1.svs", "/tmp/wsi2.svs", "/tmp/wsi3.svs"]
mask_data_list = ["/tmp/mask1.png", "/tmp/mask2.png", "/tmp/mask3.png"]

patches_args = {
    "patch_size": 256,
    "num_patches": 20,
}

save_preview_image_args = {
    "image_file": "/tmp/_preview.tif",
    "level_or_minsize": 1,
    "thickness": 1,
}

random_patches_pool = WholeImageRandomPatchesPool(
    wsi_file_list=wsi_file_list,
    mask_data_list=mask_data_list,
    patches_args=patches_args,
    proc_num_workers=3,
    save_preview_image_args=save_preview_image_args,
)

The image_file key in the dictionary object above is a suffix name for the new file names. The actual files created for the preview images will be as follows:

/tmp/wsi1_preview.tif
/tmp/wsi2_preview.tif
/tmp/wsi3_preview.tif

Expandable parameters¶

Similarly to the Patch locations/sampling classes, patch related pool classes also support expandable parameters passed via patches_args. In the example below, different foreground_ratio values will be used for different WSIs:

from dplabtools.slides.patches import WholeImageRandomPatchesPool

wsi_file_list = ["/tmp/wsi1.svs", "/tmp/wsi2.svs", "/tmp/wsi3.svs"]
mask_data_list = ["/tmp/mask1.png", "/tmp/mask2.png", "/tmp/mask3.png"]

patches_args = {
    "foreground_ratio": [0.5, 0.6, 0.7],
    "patch_size": 256,
    "num_patches": 20,
}

random_patches_pool = WholeImageRandomPatchesPool(
    wsi_file_list=wsi_file_list,
    mask_data_list=mask_data_list,
    patches_args=patches_args,
    proc_num_workers=3,
)

In a more advanced scenario involving one of the polygon based classes, patches_args can also accept nested values to customize selected arguments within each processed WSI:

patches_args = {
    "foreground_ratio": [[0.5, 0.52, 0.54], [0.6, 0.65], [0.7]],
    "patch_size": 256,
    "num_patches": 20,
}

Parameters common in all patches pool classes¶

class dplabtoolshiddenclass_34d19184627045a6a2eddf4a8a14bc10

Parameters:

wsi_file_list (list of str) – List of WSIs (files names or paths).
mask_data_list (list of str or objects) – List of masks for WSIs. Each mask is: NumPy array (file or object), or Pillow image (file or object).
patches_args (dict) – Dictionary object with arguments for the patches class.
proc_num_workers (int) – Number of processes in the pool. This value corresponds directly to the number of WSIs to be processed simultaneously.
mp_chunksize (int, default=1) – Data chunk size used in parallel processing.
save_preview_image_args (dict, optional) – Dictionary object with arguments for save_preview_image.

Methods and properties common to all patches pool classes¶

Common methods and properties are derived from the base class.

class dplabtools.slides.patches.locations.pools.BasePatchesPool(...)¶

Abstract base class for all patches pool classes.

property patch_count¶: Return the combined patch count for all processed WSIs.

property patch_details¶: Return the combined patch details for all processed WSIs.

property patch_info¶: Return the combined patch information for all processed WSIs.

property patch_labels¶: Return the distinct polygon labels for all processed WSIs.

property pids¶: Return the IDs of the executed processes.

Patch locations/sampling pool classes¶

Pool classes for patches on whole images¶

Basic usage¶

Class details¶

Pool classes for inverted patches on whole images¶

Basic usage¶

Class details¶

Pool classes for patches on polygon regions¶

Basic usage¶

Class details¶

patches_args¶

Preview images¶

Expandable parameters¶

Parameters common in all patches pool classes¶

Methods and properties common to all patches pool classes¶

Table of Contents

This Page