StainAugmentor

class StainAugmentor(method='vahadane', stain_matrix=None, sigma1=0.4, sigma2=0.2, p=0.5, *, augment_background=False, always_apply=False)[source]

Stain augmentation using predefined stain matrix or stain extraction methods.

This stain augmentation class can be used in ‘albumentations’ augmentation pipelines as well as stand alone. There is an option to use predefined stain_matrix in the input which enables the StainAugmentor to generate augmented images faster or do stain normalization to a specific target stain_matrix. Having stain matrix beforehand, we don’t need to do dictionary learning for stain matrix extraction, hence,speed up the stain augmentation/normalization process which makes it more appropriate for one-the-fly stain augmentation/normalization.

Parameters:

  • method (str) – The method to use for stain matrix and stain concentration extraction. Can be either “vahadane” (default) or “macenko”.

  • stain_matrix (numpy.ndarray) – Pre-extracted stain matrix of a target image. This can be used for both on-the-fly stain normalization and faster stain augmentation. User can use tools in tiatoolbox.tools.stainextract to extract this information. If None (default), the stain matrix will be automatically extracted using the method specified by user.

  • sigma1 (float) – Controls the extent of the stain concentrations scale parameter (alpha belonging to [1-sigma1, 1+sigma1] range). Default is 0.5.

  • sigma2 (float) – Controls the extent of the stain concentrations shift parameter (beta belonging to [-sigma2, sigma2] range). Default is 0.25.

  • augment_background (bool) – Specifies whether to apply stain augmentation on the background or not. Default is False, which indicates that only tissue region will be stain augmented.

  • always_apply (bool) – For use with ‘albumentations’ pipeline. Please refer to albumentations documentations for more information.

  • p (float) – For use with ‘albumentations’ pipeline which specifies the probability of using the augmentation in a ‘albumentations’ pipeline. . Please refer to albumentations documentations for more information.

stain_normalizer

Fitted stain normalization class.

stain_matrix

extracted stain matrix from the image

Type:

numpy.ndarray

source_concentrations

Extracted stain concentrations from the input image.

Type:

numpy.ndarray

n_stains

Number of stain channels in the stain concentrations. Expected to be 2 for H&E stained images.

Type:

int

tissue_mask

Tissue region mask in the image.

Type:

numpy.ndarray

Examples

>>> '''Using the stain augmentor in the 'albumentations' pipeline'''
>>> from tiatoolbox.tools.stainaugment import StainAugmentor
>>> import albumentations as A
>>> # Defining an exemplar stain matrix as reference
>>> stain_matrix = np.array([[0.91633014, -0.20408072, -0.34451435],
...                [0.17669817, 0.92528011, 0.33561059]])
>>> # Define albumentations pipeline
>>> aug_pipline = A.Compose([
...                         A.RandomRotate90(),
...                         A.Flip(),
...                         StainAugmentor(stain_matrix=stain_matrix)
...                         ])
>>> # apply the albumentations pipeline on an image (RGB numpy unit8 type)
>>> img_aug = aug(image=img)['image']

>>> '''Using the stain augmentor stand alone'''
>>> from tiatoolbox.tools.stainaugment import StainAugmentor
>>> # Defining an exemplar stain matrix as reference
>>> stain_matrix = np.array([[0.91633014, -0.20408072, -0.34451435],
...                [0.17669817, 0.92528011, 0.33561059]])
>>> # Instantiate the stain augmentor and fit it on an image
>>> stain_augmentor = StainAugmentor(stain_matrix=stain_matrix)
>>> stain_augmentor.fit(img)
>>> # Now using the fitted `stain_augmentor` in a loop to generate
>>> # several augmented instances from the same image.
>>> for i in range(10):
...     img_aug = stain_augmentor.augment()

Initialize StainAugmentor.

Methods

apply

Call the fit and augment functions to generate a stain augmented image.

augment

Return an augmented instance based on source stain concentrations.

fit

Fit function to extract information needed for stain augmentation.

get_params

Return randomly generated parameters based on input arguments.

get_params_dependent_on_targets

Does nothing, added to resolve flake 8 error.

get_transform_init_args_names

Return the argument names for albumentations use.

Attributes

interpolation

fill_value

mask_fill_value

apply(img, **params)[source]

Call the fit and augment functions to generate a stain augmented image.

Parameters:
Returns:

Stain augmented image with the same size and format as the input img.

Return type:

numpy.ndarray

augment()[source]

Return an augmented instance based on source stain concentrations.

Stain concentrations of the source image are altered (scaled and shifted) based on the random alpha and beta parameters, and then an augmented image is reconstructed from the altered concentrations. All parameters needed for this part are calculated when calling fit() function.

Returns:

Stain augmented image.

Return type:

numpy.ndarray

Parameters:

self (StainAugmentor)

fit(img, threshold=0.85)[source]

Fit function to extract information needed for stain augmentation.

The fit function uses either ‘Macenko’ or ‘Vahadane’ stain extraction methods to extract stain matrix and stain concentrations of the input image to be used in the augment function.

Parameters:

  • img (numpy.ndarray) – RGB image in the form of uint8 numpy array.

  • threshold (float) – The threshold value used to find tissue mask from the luminosity component of the image. The found tissue_mask will be used to filter out background area in stain augmentation process upon user setting augment_background=False.

  • self (StainAugmentor)

Return type:

None

get_params()[source]

Return randomly generated parameters based on input arguments.

Parameters:

self (StainAugmentor)

Return type:

dict

get_params_dependent_on_targets(params)[source]

Does nothing, added to resolve flake 8 error.

Parameters:
Return type:

dict

static get_transform_init_args_names(**kwargs)[source]

Return the argument names for albumentations use.

Parameters:

kwargs (dict)

Return type:

tuple[str, …]