StainAugmentor

tiatoolbox . tools . stainaugment . StainAugmentor

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

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 beforhand, 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 (False) – For use with ‘albumentations’ pipeline. Please refer to albumentations documentations for more information.

• p (0.5) – 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.

Return type

numpy.ndarray

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 StainAugmentaiton
>>> import albumentations as A
>>> # Defining an examplar stain matrix as refrence
>>> 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(),
...                         StainAugmentaiton(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 StainAugmentaiton
>>> # Defining an examplar stain matrix as refrence
>>> 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()

Methods

apply	Call the fit and augment functions to generate an 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	Returns 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

apply(img, **params)

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

Parameters

img (numpy.ndarray) – Input RGB image in the form of unit8 numpy array.

Returns

Stain augmented image with the same

size and format as the input img.

Return type

numpy.ndarray

augment()

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 paramters, 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

img_augmented (numpy.ndarray)

fit(img, threshold=0.85)

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.

get_params()

Returns randomly generated parameters based on input arguments.

get_params_dependent_on_targets(params)

Does nothing, added to resolve flake 8 error

get_transform_init_args_names()

Return the argument names for albumentations use.