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 minumum 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. Atleast 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.

Returns

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]

Find the index of the stain column vector in w corresponding to the reference vector. Useful in connection with adaptive deconvolution routines in order to find the column corresponding with a certain expected stain.

Parameters
  • reference (array_like) – 1D array that is the stain vector to find

  • w (array_like) – 2D array of columns the same size as reference. The columns should be normalized.

Returns

i – Column of w corresponding to reference

Return type

int

Notes

The index of the vector with the smallest angular distance is returned.

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

1

Van Eycke, Y. R., Allard, J., Salmon, I., Debeir, O., & Decaestecker, C. (2017). Image processing in digital pathology: an opportunity to solve inter-batch variability of immunohistochemical staining. Scientific Reports, 7.

2

Macenko, M., Niethammer, M., Marron, J. S., Borland, D., Woosley, J. T., Guan, X., … & Thomas, N. E. (2009, June). A method for normalizing histology slides for quantitative analysis. In Biomedical Imaging: From Nano to Macro, 2009. ISBI’09. IEEE International Symposium on (pp. 1107-1110). IEEE.

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

3

Van Eycke, Y. R., Allard, J., Salmon, I., Debeir, O., & Decaestecker, C. (2017). Image processing in digital pathology: an opportunity to solve inter-batch variability of immunohistochemical staining. Scientific Reports, 7.

4

Xu, J., Xiang, L., Wang, G., Ganesan, S., Feldman, M., Shih, N. N., … & Madabhushi, A. (2015). Sparse Non-negative Matrix Factorization (SNMF) based color unmixing for breast histopathological image analysis. Computerized Medical Imaging and Graphics, 46, 20-29.

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

5

Macenko, M., Niethammer, M., Marron, J. S., Borland, D., Woosley, J. T., Guan, X., … & Thomas, N. E. (2009, June). A method for normalizing histology slides for quantitative analysis. In Biomedical Imaging: From Nano to Macro, 2009. ISBI’09. IEEE International Symposium on (pp. 1107-1110). IEEE.

6

Xu, J., Xiang, L., Wang, G., Ganesan, S., Feldman, M., Shih, N. N., …& Madabhushi, A. (2015). Sparse Non-negative Matrix Factorization (SNMF) based color unmixing for breast histopathological image analysis. Computerized Medical Imaging and Graphics, 46, 20-29.