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
See also
histomicstk.preprocessing.color_deconvolution.complement_stain_matrix
,histomicstk.preprocessing.color_deconvolution.color_deconvolution
,histomicstk.preprocessing.color_conversion.rgb_to_od
,histomicstk.preprocessing.color_conversion.od_to_rgb
,histomicstk.preprocessing.color_conversion.rgb_to_sda
,histomicstk.preprocessing.color_conversion.sda_to_rgb
- 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.
See also
histomicstk.preprocessing.color_deconvolution.complement_stain_matrix
,histomicstk.preprocessing.color_deconvolution.color_convolution
,histomicstk.preprocessing.color_conversion.rgb_to_od
,histomicstk.preprocessing.color_conversion.od_to_rgb
,histomicstk.preprocessing.color_conversion.rgb_to_sda
,histomicstk.preprocessing.color_conversion.sda_to_rgb
- 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
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.
See also
histomicstk.preprocessing.color_deconvolution.color_deconvolution
,histomicstk.preprocessing.color_deconvolution.separate_stains_xu_snmf
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.
See also
histomicstk.preprocessing.color_deconvolution.color_deconvolution
,histomicstk.preprocessing.color_deconvolution.separate_stains_macenko_pca
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
See also
histomicstk.preprocessing.color_deconvolution.separate_stains_macenko_pca
,histomicstk.preprocessing.color_deconvolution.separate_stains_xu_snmf
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.