histomicstk.preprocessing.color_normalization

Functions to correct non-uniform staining issues.

histomicstk.preprocessing.color_normalization.background_intensity(*args, **kwargs)[source]

Sample the background of the slide identified by slide_path to compute the background intensities in the RGB channels. Arguments are as in histomicstk.utils.sample_pixels, with background forced to True.

Notes

The magnification parameter defaults to 1.25x, instead of the native scan magnification as in sample_pixels.

histomicstk.preprocessing.color_normalization.deconvolution_based_normalization(im_src, W_source=None, W_target=None, im_target=None, stains=None, mask_out=None, stain_unmixing_routine_params=None)[source]

Perform color normalization using color deconvolution to transform the.

… color characteristics of an image to a desired standard. After the image is deconvolved into its component stains (eg, H&E), it is convolved with a stain column vectors matrix from the target image from which the color characteristics need to be transferred.

Parameters
  • im_src (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.

  • W_target (np array, default is None) – A 3x3 matrix of target stain column vectors. If not provided, and im_target is also not provided, the default behavior is to use histomicstk.preprocessing.color_deconvolution.stain_color_map to provide an idealized target matrix.

  • im_target (array_like, default is None) – An RGB image (m x n x 3) that has good color properties that ought to be transferred to im_src. If you provide this parameter, im_target will be used to extract W_target and the W_target parameter will be ignored.

  • 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

  • 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.

  • stain_unmixing_routine_params (dict, default is empty dict) – k,v for stain_unmixing_routine().

Returns

Color Normalized RGB image (m x n x 3)

Return type

array_like

See also

histomicstk.preprocessing.color_deconvolution.color_deconvolution_routine, histomicstk.preprocessing.color_convolution.color_convolution

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.

3

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_normalization.reinhard(im_src, target_mu, target_sigma, src_mu=None, src_sigma=None, mask_out=None)[source]

Perform Reinhard color normalization.

Transform the color characteristics of an image to a desired standard. The standard is defined by the mean and standard deviations of the target image in LAB color space defined by Ruderman. The input image is converted to Ruderman’s LAB space, the LAB channels are each centered and scaled to zero-mean unit variance, and then rescaled and shifted to match the target image statistics. If the LAB statistics for the input image are provided (src_mu and src_sigma) then these will be used for normalization, otherwise they will be derived from the input image im_src.

Parameters
  • im_src (array_like) – An RGB image

  • target_mu (array_like) – A 3-element array containing the means of the target image channels in LAB color space.

  • target_sigma (array_like) – A 3-element array containing the standard deviations of the target image channels in LAB color space.

  • src_mu (array_like, optional) – A 3-element array containing the means of the source image channels in LAB color space. Used with reinhard_stats for uniform normalization of tiles from a slide.

  • src_sigma (array, optional) – A 3-element array containing the standard deviations of the source image channels in LAB color space. Used with reinhard_stats for uniform normalization of tiles tiles from a slide.

  • mask_out (array_like, default is None) – if not None, should be (m, n) boolean numpy array. This method uses numpy masked array functionality to only use non-masked areas in calculations. This is relevant because elements like blood, sharpie marker, white space, etc would throw off the reinhard normalization by affecting the mean and stdev. Ideally, you want to exclude these elements from both the target image (from which you calculate target_mu and target_sigma) and from the source image to be normalized.

Returns

im_normalized – Color Normalized RGB image

Return type

array_like

References

4

E. Reinhard, M. Adhikhmin, B. Gooch, P. Shirley, “Color transfer between images,” in IEEE Computer Graphics and Applications, vol.21, no.5,pp.34-41, 2001.

5

D. Ruderman, T. Cronin, and C. Chiao, “Statistics of cone responses to natural images: implications for visual coding,” J. Opt. Soc. Am. A vol.15, pp.2036-2045, 1998.

histomicstk.preprocessing.color_normalization.reinhard_stats(slide_path, sample_fraction, magnification=None, tissue_seg_mag=1.25)[source]

Samples a whole-slide-image to determine colorspace statistics (mean, variance) needed to perform global Reinhard color normalization.

Normalizing individual tiles independently creates a significant bias in the results of segmentation and feature extraction, as the color statistics of each tile in a whole-slide image can vary significantly. To remedy this, we sample a subset of pixels from the entire whole-slide image in order to estimate the global mean and standard deviation of each channel in the Lab color space that are needed for reinhard color normalization.

Parameters
  • slide_path (str) – path and filename of slide.

  • sample_fraction (double) – Fraction of pixels to sample (range (0, 1]).

  • magnification (scalar) – Desired magnification for sampling. Defaults to native scan magnification.

  • tissue_seg_mag (double, optional) – low resolution magnification at which foreground will be segmented. Default value = 1.25.

Returns

  • Mu (array_like) – A 3-element array containing the means of the target image channels in sample_pix_lab color space.

  • Sigma (array_like) – A 3-element list containing the standard deviations of the target image channels in sample_pix_lab color space.

Notes

Returns a namedtuple.