histocartography.preprocessing.feature_extraction module¶

Extract features from images for a given structure

Summary¶

Classes:

`AugmentedDeepFeatureExtractor`	Helper class to extract deep features from instance maps with different augmentations
`DeepFeatureExtractor`	Helper class to extract deep features from instance maps
`FeatureExtractor`	Base class for feature extraction
`GridAugmentedDeepFeatureExtractor`
`GridDeepFeatureExtractor`
`GridPatchDataset`
`HandcraftedFeatureExtractor`	Helper class to extract handcrafted features from instance maps
`InstanceMapPatchDataset`	Helper class to use a give image and extracted instance maps as a dataset
`PatchFeatureExtractor`	Helper class to use a CNN to extract features from an image

class FeatureExtractor(save_path: Union[None, str, pathlib.Path] = None, precompute: bool = True, link_path: Union[None, str, pathlib.Path] = None, precompute_path: Union[None, str, pathlib.Path] = None)[source]¶

Bases: histocartography.pipeline.PipelineStep

Base class for feature extraction

precompute(link_path: Union[None, str, pathlib.Path] = None, precompute_path: Union[None, str, pathlib.Path] = None) → None[source]¶

Precompute all necessary information

Parameters

link_path (Union[None, str, Path], optional) – Path to link to. Defaults to None.
precompute_path (Union[None, str, Path], optional) – Path to save precomputation outputs. Defaults to None.

class HandcraftedFeatureExtractor(save_path: Union[None, str, pathlib.Path] = None, precompute: bool = True, link_path: Union[None, str, pathlib.Path] = None, precompute_path: Union[None, str, pathlib.Path] = None)[source]¶

Bases: histocartography.preprocessing.feature_extraction.FeatureExtractor

Helper class to extract handcrafted features from instance maps

class PatchFeatureExtractor(architecture: str, device: torch.device)[source]¶

Bases: object

Helper class to use a CNN to extract features from an image

__init__(architecture: str, device: torch.device) → None[source]¶

Create a patch feature extracter of a given architecture and put it on GPU if available.

Parameters

architecture (str) – String of architecture. According to torchvision.models syntax.
device (torch.device) – Torch Device.

class InstanceMapPatchDataset(image: numpy.ndarray, instance_map: numpy.ndarray, patch_size: int, stride: Optional[int], resize_size: Optional[int] = None, fill_value: Optional[int] = 255, mean: Optional[List[float]] = None, std: Optional[List[float]] = None, transform: Optional[Callable] = None)[source]¶

Bases: torch.utils.data.dataset.Dataset

Helper class to use a give image and extracted instance maps as a dataset

__init__(image: numpy.ndarray, instance_map: numpy.ndarray, patch_size: int, stride: Optional[int], resize_size: Optional[int] = None, fill_value: Optional[int] = 255, mean: Optional[List[float]] = None, std: Optional[List[float]] = None, transform: Optional[Callable] = None) → None[source]¶

Create a dataset for a given image and extracted instance map with desired patches of (patch_size, patch_size, 3). If fill_value is not None, it fills up pixels outside the instance maps with this value (all channels).

Parameters

image (np.ndarray) – RGB input image.
map (instance) – Extracted instance map.
patch_size (int) – Desired size of patch.
stride (int) – Desired stride for patch extraction. If None, stride is set to patch size. Defaults to None.
resize_size (int) – Desired resized size to input the network. If None, no resizing is done and the patches of size patch_size are provided to the network. Defaults to None.
fill_value (Optional[int]) – Value to fill outside the instance maps (None means do not fill).
mean (list[float], optional) – Channel-wise mean for image normalization.
std (list[float], optional) – Channel-wise std for image normalization.
transform (Callable) – Transform to apply. Defaults to None.

class DeepFeatureExtractor(architecture: str, patch_size: int, resize_size: Optional[int] = None, stride: Optional[int] = None, downsample_factor: int = 1, normalizer: Optional[dict] = None, batch_size: int = 32, fill_value: int = 255, num_workers: int = 0, verbose: bool = False, **kwargs)[source]¶

Bases: histocartography.preprocessing.feature_extraction.FeatureExtractor

Helper class to extract deep features from instance maps

__init__(architecture: str, patch_size: int, resize_size: Optional[int] = None, stride: Optional[int] = None, downsample_factor: int = 1, normalizer: Optional[dict] = None, batch_size: int = 32, fill_value: int = 255, num_workers: int = 0, verbose: bool = False, **kwargs) → None[source]¶

Create a deep feature extractor.

Parameters

architecture (str) – Name of the architecture to use. According to torchvision.models syntax.
patch_size (int) – Desired size of patch.
resize_size (int) – Desired resized size to input the network. If None, no resizing is done and the patches of size patch_size are provided to the network. Defaults to None.
stride (int) – Desired stride for patch extraction. If None, stride is set to patch size. Defaults to None.
downsample_factor (int) – Downsampling factor for image analysis. Defaults to 1.
normalizer (dict) – Dictionary of channel-wise mean and standard deviation for image normalization. If None, using ImageNet normalization factors. Defaults to None.
batch_size (int) – Batch size during processing of patches. Defaults to 32.
fill_value (int) – Constant pixel value for image padding. Defaults to 255.
num_workers (int) – Number of workers in data loader. Defaults to 0.
verbose (bool) – tqdm processing bar. Defaults to False.

class AugmentedDeepFeatureExtractor(rotations: Optional[List[int]] = None, flips: Optional[List[int]] = None, **kwargs)[source]¶

Bases: histocartography.preprocessing.feature_extraction.DeepFeatureExtractor

Helper class to extract deep features from instance maps with different augmentations

__init__(rotations: Optional[List[int]] = None, flips: Optional[List[int]] = None, **kwargs) → None[source]¶

Creates a feature extractor that extracts feature for all of the given augmentations. Otherwise works the same as the DeepFeatureExtractor.

Parameters

rotations (Optional[List[int]], optional) – List of rotations to use. Defaults to None.
flips (Optional[List[int]], optional) – List of flips to use, in {‘n’, ‘h’, ‘v’}. Defaults to None.

class GridPatchDataset(image: numpy.ndarray, patch_size: int, resize_size: int, stride: int, mean: Optional[List[float]] = None, std: Optional[List[float]] = None, transform: Optional[Callable] = None)[source]¶

Bases: torch.utils.data.dataset.Dataset

__init__(image: numpy.ndarray, patch_size: int, resize_size: int, stride: int, mean: Optional[List[float]] = None, std: Optional[List[float]] = None, transform: Optional[Callable] = None) → None[source]¶

Create a dataset for a given image and extracted instance maps with desired patches of (size, size, 3).

Parameters

image (np.ndarray) – RGB input image.
patch_size (int) – Desired size of patches.
resize_size (int) – Desired resized size to input the network. If None, no resizing is done and the patches of size patch_size are provided to the network. Defaults to None.
stride (int) – Desired stride for patch extraction.
mean (list[float], optional) – Channel-wise mean for image normalization.
std (list[float], optional) – Channel-wise std for image normalization.
transform (list[transforms], optional) – List of transformations for input image.

class GridDeepFeatureExtractor(architecture: str, patch_size: int, resize_size: Optional[int] = None, stride: Optional[int] = None, downsample_factor: int = 1, normalizer: Optional[dict] = None, batch_size: int = 32, fill_value: int = 255, num_workers: int = 0, verbose: bool = False, **kwargs)[source]¶

Bases: histocartography.preprocessing.feature_extraction.FeatureExtractor

__init__(architecture: str, patch_size: int, resize_size: Optional[int] = None, stride: Optional[int] = None, downsample_factor: int = 1, normalizer: Optional[dict] = None, batch_size: int = 32, fill_value: int = 255, num_workers: int = 0, verbose: bool = False, **kwargs) → None[source]¶

Create a deep feature extractor.

Parameters

architecture (str) – Name of the architecture to use. According to torchvision.models syntax.
patch_size (int) – Desired size of patches.
resize_size (int) – Desired resized size to input the network. If None, no resizing is done and the patches of size patch_size are provided to the network. Defaults to None.
stride (int) – Desired stride for patch extraction. If None, stride is set to patch size. Defaults to None.
downsample_factor (int) – Downsampling factor for image analysis. Defaults to 1.
normalizer (dict) – Dictionary of channel-wise mean and standard deviation for image normalization. If None, using ImageNet normalization factors. Defaults to None.
batch_size (int) – Batch size during processing of patches. Defaults to 32.
fill_value (int) – Constant pixel value for image padding. Defaults to 255.
num_workers (int) – Number of workers in data loader. Defaults to 0.
verbose (bool) – tqdm processing bar. Defaults to False.

class GridAugmentedDeepFeatureExtractor(rotations: Optional[List[int]] = None, flips: Optional[List[int]] = None, **kwargs)[source]¶

Bases: histocartography.preprocessing.feature_extraction.GridDeepFeatureExtractor

__init__(rotations: Optional[List[int]] = None, flips: Optional[List[int]] = None, **kwargs) → None[source]¶

Creates a feature extractor that extracts feature for all of the given augmentations. Otherwise works the same as the DeepFeatureExtractor.

Parameters

rotations (Optional[List[int]], optional) – List of rotations to use. Defaults to None.
flips (Optional[List[int]], optional) – List of flips to use, in {‘n’, ‘h’, ‘v’}. Defaults to None.

Reference¶

If you use histocartography in your projects, please cite the following:

@inproceedings{pati2021,
    title = {Hierarchical Graph Representations for Digital Pathology},
    author = {Pushpak Pati, Guillaume Jaume, Antonio Foncubierta, Florinda Feroce, Anna Maria Anniciello, Giosuè Scognamiglio, Nadia Brancati, Maryse Fiche, Estelle Dubruc, Daniel Riccio, Maurizio Di Bonito, Giuseppe De Pietro, Gerardo Botti, Jean-Philippe Thiran, Maria Frucci, Orcun Goksel, Maria Gabrani},
    booktitle = {https://arxiv.org/pdf/2102.11057},
    year = {2021}
}