histomicstk.preprocessing.color_deconvolution¶

This package contains implementation of methods to deconvolve or separate.

… the stains of histopathology images.

histomicstk.preprocessing.color_deconvolution.color_convolution(im_stains, w, I_0=None)[source]¶

Perform Color Convolution.

Reconstructs a color image from the stain matrix w and the individual images stored as channels in im_stains and generated by ColorDeconvolution.

Parameters:

im_stains (array_like) – An RGB image where in each channel contains image of one stain
w (array_like) – A 3x3 matrix containing the stain colors in its columns. In the case of two stains, the third column is zero and will be complemented using cross-product. The matrix should contain a minimum two nonzero columns.
I_0 (float or array_like, optional) – A float a 3-vector containing background RGB intensities. If unspecified, use the old OD conversion.

Returns:

im_rgb – Reconstructed RGB image with intensity values ranging from [0, 255], suitable for display.

Return type:

array_like

histomicstk.preprocessing.color_deconvolution.color_deconvolution(im_rgb, w, I_0=None)[source]¶

Perform color deconvolution.

The given RGB Image I is first first transformed into optical density space, and then projected onto the stain vectors in the columns of the 3x3 stain matrix W.

For deconvolving H&E stained image use:

w = array([[0.650, 0.072, 0], [0.704, 0.990, 0], [0.286, 0.105, 0]])

Parameters:

im_rgb (array_like) – Input RGB Image that needs to be deconvolved.
w (array_like) – A 3x3 matrix containing the color vectors in columns. For two stain images the third column is zero and will be complemented using cross-product. At least two of the three columns must be non-zero.
I_0 (float or array_like, optional) – A float a 3-vector containing background RGB intensities. If unspecified, use the old OD conversion.

Returns:

Stains (array_like) – An rgb image where in each channel contains the image of the stain of the corresponding column in the stain matrix W. The intensity range of each channel is [0, 255] suitable for displaying.
StainsFloat (array_like) – An intensity image of deconvolved stains that is unbounded, suitable for reconstructing color images of deconvolved stains with color_convolution.
Wc (array_like) – A 3x3 complemented stain matrix. Useful for color image reconstruction with color_convolution.

histomicstk.preprocessing.color_deconvolution.color_deconvolution_routine(im_rgb, W_source=None, mask_out=None, **kwargs)[source]¶

Unmix stains mixing followed by deconvolution (wrapper).

Parameters:

im_rgb (array_like) – An RGB image (m x n x 3) to color normalize
W_source (np array, default is None) – A 3x3 matrix of source stain column vectors. Only provide this if you know the stains matrix in advance (unlikely) and would like to perform supervised deconvolution. If this is not provided, stain_unmixing_routine() is used to estimate W_source.
mask_out (array_like, default is None) – if not None, should be (m x n) boolean numpy array. This parameter ensures exclusion of non-masked areas from calculations and stain matrix. This is relevant because elements like blood, sharpie marker, white space, cannot be modeled as a mix of two stains.
kwargs (k,v pairs) – Passed as-is to stain_unmixing_routine() if W_source is None.

Return type:

Output from color_deconvolution()

histomicstk.preprocessing.color_deconvolution.complement_stain_matrix(w)[source]¶

Generates a complemented stain matrix Used to fill out empty columns of a stain matrix for use with color_deconvolution. Replaces right-most column with normalized cross-product of first two columns.

Parameters:: w (array_like) – A 3x3 stain calibration matrix with stain color vectors in columns.
Returns:: w_comp – A 3x3 complemented stain calibration matrix with a third orthogonal column.
Return type:: array_like

histomicstk.preprocessing.color_deconvolution.find_stain_index(reference, w)[source]¶

Identify the stain vector in w that best aligns with the reference vector.

This is used with adaptive deconvolution routines where the order of returned stain vectors is not guaranteed. This function identifies the stain vector of w that most closely aligns with the provided reference.

Parameters:

reference (array_like) – 1D array representing the stain vector query.
w (array_like) – 3xN array of where columns represent stain vectors to search.

Returns:

i – Column index of stain vector with best alignment to reference.

Return type:

int

Notes

Vectors are normalized to unit-norm prior to comparison using dot product. Alignment is determined by vector angles and not distances.

histomicstk.preprocessing.color_deconvolution.rgb_separate_stains_macenko_pca(im_rgb, I_0, *args, **kwargs)[source]¶

Compute the stain matrix for color deconvolution with the “Macenko” method from an RGB image or matrix.

Parameters:

im_rgb (array_like) – Image (MxNx3) or matrix (3xN) in RGB space for which to compute the stain matrix.
I_0 (float or array_like) – Per-channel background intensities, or one intensity to use for all channels if a float.

Returns:

w – A 3x3 matrix of stain column vectors, in SDA space

Return type:

array_like

Note

For additional input arguments and documentation, please see histomicstk.preprocessing.color_deconvolution.separate_stains_macenko_pca. im_sda is computed and passed as part of this routine.

histomicstk.preprocessing.color_deconvolution.rgb_separate_stains_xu_snmf(im_rgb, I_0, *args, **kwargs)[source]¶

Compute the stain matrix for color deconvolution with SNMF from an RGB image or matrix.

Parameters:

im_rgb (array_like) – Image (MxNx3) or matrix (3xN) in RGB space for which to compute the stain matrix.
I_0 (float or array_like) – Per-channel background intensities, or one intensity to use for all channels if a float.

Returns:

w – A 3x3 matrix of stain column vectors, in SDA space

Return type:

array_like

Note

This is a thin wrapper around separate_stains_xu_snmf and as such the w_init parameter must be manually passed.

For additional input arguments and documentation, please see histomicstk.preprocessing.color_deconvolution.separate_stains_xu_snmf. im_sda is computed and passed as part of this routine.

histomicstk.preprocessing.color_deconvolution.separate_stains_macenko_pca(im_sda, minimum_magnitude=16, min_angle_percentile=0.01, max_angle_percentile=0.99, mask_out=None)[source]¶

Compute the stain matrix for color deconvolution with the Macenko method.

For a two-stain image or matrix in SDA space, this method works by computing a best-fit plane with PCA, wherein it selects the stain vectors as percentiles in the “angle distribution” in that plane.

Parameters:

im_sda (array_like) – Image (MxNx3) or matrix (3xN) in SDA space for which to compute the stain matrix.
minimum_magnitude (float) –
The magnitude below which vectors will be excluded from the computation of the angle distribution.

The default is based on the paper value of 0.15, adjusted for our method of calculating SDA, thus 0.15 * 255 * log(10)/log(255)
min_angle_percentile (float) – The smaller percentile of one of the vectors to pick from the angle distribution
max_angle_percentile (float) – The larger percentile of one of the vectors to pick from the angle distribution
mask_out (array_like) – if not None, should be (m, n) boolean numpy array. This parameter ensures exclusion of non-masked areas from calculations. This is relevant because elements like blood, sharpie marker, white space, etc may throw off the normalization somewhat.

Returns:

w – A 3x3 matrix of stain column vectors

Return type:

array_like

Note

All input pixels not otherwise excluded are used in the computation of the principal plane and the angle distribution.

References

histomicstk.preprocessing.color_deconvolution.separate_stains_xu_snmf(im_sda, w_init=None, beta=0.2)[source]¶

Compute the stain matrix for color deconvolution with SNMF.

… (sparse non-negative matrix factorization).

Parameters:

im_sda (array_like) – Image (MxNx3) or matrix (3xN) in SDA space for which to compute the stain matrix.
w_init (array_like, default is None) – Initial value for the stain matrix. if not provided, default initialization is used.
beta (float) – Regularization factor for the sparsity of the deconvolved pixels

Returns:

w – A 3x3 matrix of stain column vectors

Return type:

array_like

Note

All input pixels are used in the factorization.

References

histomicstk.preprocessing.color_deconvolution.stain_color_map = {'dab': [0.27, 0.57, 0.78], 'eosin': [0.07, 0.99, 0.11], 'hematoxylin': [0.65, 0.7, 0.29], 'null': [0.0, 0.0, 0.0]}¶: A dictionary of names for reference stain vectors

histomicstk.preprocessing.color_deconvolution.stain_unmixing_routine(im_rgb, stains=None, stain_unmixing_method='macenko_pca', stain_unmixing_params=None, mask_out=None)[source]¶

Perform stain unmixing using the method of choice (wrapper).

Parameters:

im_rgb (array_like) – An RGB image (m x n x 3) to unmix.
stains (list, optional) – List of stain names (order is important). Default is H&E. This is particularly relevant in macenco where the order of stains is not preserved during stain unmixing, so this method uses histomicstk.preprocessing.color_deconvolution.find_stain_index to reorder the stains matrix to the order provided by this parameter
stain_unmixing_method (str, default is 'macenko_pca') – stain unmixing method to use. It should be one of the following ‘macenko_pca’, or ‘xu_snmf’.
stain_unmixing_params (dict, default is an empty dict) – kwargs to pass as-is to the stain unmixing method.
mask_out (array_like, default is None) – if not None, should be (m x n) boolean numpy array. This parameter ensures exclusion of non-masked areas from calculations and normalization. This is relevant because elements like blood, sharpie marker, white space, etc may throw off the normalization.

Returns:

Wc – A 3x3 complemented stain matrix.

Return type:

array_like

References