V1.3.0

.github/workflows/tests_full.yml

@@ -73,12 +73,14 @@ jobs:
       matrix:
         os: [ windows-2019, ubuntu-18.04, macos-11 ]
         python-version: [ 3.6, 3.7, 3.8, 3.9 ]
-        pytorch-version: [1.8.0, 1.9.0, 1.10.0, 1.11.0, 1.12.0]
+        pytorch-version: [1.8.0, 1.9.0, 1.10.0, 1.11.0, 1.12.0, 1.13.0]
         exclude:
           - python-version: 3.6
             pytorch-version: 1.11.0
           - python-version: 3.6
             pytorch-version: 1.12.0
+          - python-version: 3.6
+            pytorch-version: 1.13.0
 
     steps:
       - uses: actions/checkout@v1

README.md

@@ -8,8 +8,9 @@
 GPU-accelerated stain normalization tools for histopathological images. Compatible with PyTorch, TensorFlow, and Numpy.
 Normalization algorithms currently implemented:
 
-- Macenko et al. [\[1\]](#reference) (ported from [numpy implementation](https://github.com/schaugf/HEnorm_python))
-- Reinhard et al. [\[2\]](#reference) (only numpy & TensorFlow backend support)
+- Macenko [\[1\]](#reference) (ported from [numpy implementation](https://github.com/schaugf/HEnorm_python))
+- Reinhard [\[2\]](#reference)
+- Modified Reinhard [\[3\]](#reference)
 
 ## Installation
 
@@ -49,7 +50,8 @@ norm, H, E = normalizer.normalize(I=t_to_transform, stains=True)
 | Algorithm | numpy | torch | tensorflow |
 |-|-|-|-|
 | Macenko | ✓ | ✓ | ✓ |
-| Reinhard | ✓ | ✗ | ✓ |
+| Reinhard | ✓ | ✓ | ✓ |
+| Modified Reinhard | ✓ | ✓ | ✓ |
 
 ## Backend comparison
 
@@ -68,8 +70,9 @@ Results with 10 runs per size on a Intel(R) Core(TM) i5-8365U CPU @ 1.60GHz
 
 ## Reference
 
-- [1] Macenko, Marc, et al. "A method for normalizing histology slides for quantitative analysis." 2009 IEEE International Symposium on Biomedical Imaging: From Nano to Macro. IEEE, 2009.
-- [2] Reinhard, Erik, et al. "Color transfer between images." IEEE Computer Graphics and Applications. IEEE, 2001.
+- [1] Macenko, Marc et al. "A method for normalizing histology slides for quantitative analysis." 2009 IEEE International Symposium on Biomedical Imaging: From Nano to Macro. IEEE, 2009.
+- [2] Reinhard, Erik et al. "Color transfer between images." IEEE Computer Graphics and Applications. IEEE, 2001.
+- [3] Roy, Santanu et al. "Modified Reinhard Algorithm for Color Normalization of Colorectal Cancer Histopathology Images". 2021 29th European Signal Processing Conference (EUSIPCO), IEEE, 2021.
 
 ## Citing
 

example.py

@@ -83,7 +83,6 @@
 t_ = time.time()
 norm, H, E = tf_normalizer.normalize(I=t_to_transform, stains=True)
 print("tf runtime:", time.time() - t_)
-
 plt.figure()
 plt.suptitle('tensorflow normalizer')
 plt.subplot(2, 2, 1)

setup.py

@@ -6,7 +6,7 @@
 
 setup(
     name='torchstain',
-    version='1.2.0',
+    version='1.3.0',
     description='Stain normalization tools for histological analysis and computational pathology',
     long_description=README,
     long_description_content_type='text/markdown',

tests/test_tf.py

@@ -3,8 +3,6 @@
 import torchstain
 import torchstain.tf
 import tensorflow as tf
-import time
-from skimage.metrics import structural_similarity as ssim
 import numpy as np
 
 def test_cov():
@@ -22,7 +20,7 @@ def test_percentile():
 
     np.testing.assert_almost_equal(p_np, p_t)
 
-def test_normalize_tf():
+def test_macenko_tf():
     size = 1024
     curr_file_path = os.path.dirname(os.path.realpath(__file__))
     target = cv2.resize(cv2.cvtColor(cv2.imread(os.path.join(curr_file_path, "../data/target.png")), cv2.COLOR_BGR2RGB), (size, size))
@@ -44,8 +42,36 @@ def test_normalize_tf():
     result_tf, _, _ = tf_normalizer.normalize(I=t_to_transform, stains=True)
 
     # convert to numpy and set dtype
-    result_numpy = result_numpy.astype("float32")
-    result_tf = result_tf.numpy().astype("float32")
+    result_numpy = result_numpy.astype("float32") / 255.
+    result_tf = result_tf.numpy().astype("float32") / 255.
 
     # assess whether the normalized images are identical across backends
-    np.testing.assert_almost_equal(ssim(result_numpy.flatten(), result_tf.flatten()), 1.0, decimal=4, verbose=True)
+    np.testing.assert_almost_equal(result_numpy.flatten(), result_tf.flatten(), decimal=2, verbose=True)
+
+def test_reinhard_tf():
+    size = 1024
+    curr_file_path = os.path.dirname(os.path.realpath(__file__))
+    target = cv2.resize(cv2.cvtColor(cv2.imread(os.path.join(curr_file_path, "../data/target.png")), cv2.COLOR_BGR2RGB), (size, size))
+    to_transform = cv2.resize(cv2.cvtColor(cv2.imread(os.path.join(curr_file_path, "../data/source.png")), cv2.COLOR_BGR2RGB), (size, size))
+
+    # setup preprocessing and preprocess image to be normalized
+    T = lambda x: tf.convert_to_tensor(x, dtype=tf.float32)
+    t_to_transform = T(to_transform)
+
+    # initialize normalizers for each backend and fit to target image
+    normalizer = torchstain.normalizers.ReinhardNormalizer(backend='numpy')
+    normalizer.fit(target)
+
+    tf_normalizer = torchstain.normalizers.ReinhardNormalizer(backend='tensorflow')
+    tf_normalizer.fit(T(target))
+
+    # transform
+    result_numpy = normalizer.normalize(I=to_transform)
+    result_tf = tf_normalizer.normalize(I=t_to_transform)
+
+    # convert to numpy and set dtype
+    result_numpy = result_numpy.astype("float32") / 255.
+    result_tf = result_tf.numpy().astype("float32") / 255.
+
+    # assess whether the normalized images are identical across backends
+    np.testing.assert_almost_equal(result_numpy.flatten(), result_tf.flatten(), decimal=2, verbose=True)

tests/test_torch.py

@@ -4,10 +4,9 @@
 import torchstain.torch
 import torch
 import torchvision
-import time
 import numpy as np
 from torchvision import transforms
-from skimage.metrics import structural_similarity as ssim
+
 
 def setup_function(fn):
     print("torch version:", torch.__version__, "torchvision version:", torchvision.__version__)
@@ -27,7 +26,7 @@ def test_percentile():
 
     np.testing.assert_almost_equal(p_np, p_t)
 
-def test_normalize_torch():
+def test_macenko_torch():
     size = 1024
     curr_file_path = os.path.dirname(os.path.realpath(__file__))
     target = cv2.resize(cv2.cvtColor(cv2.imread(os.path.join(curr_file_path, "../data/target.png")), cv2.COLOR_BGR2RGB), (size, size))
@@ -36,7 +35,7 @@ def test_normalize_torch():
     # setup preprocessing and preprocess image to be normalized
     T = transforms.Compose([
         transforms.ToTensor(),
-        transforms.Lambda(lambda x: x*255)
+        transforms.Lambda(lambda x: x * 255)
     ])
     t_to_transform = T(to_transform)
 
@@ -52,8 +51,40 @@ def test_normalize_torch():
     result_torch, _, _ = torch_normalizer.normalize(I=t_to_transform, stains=True)
 
     # convert to numpy and set dtype
-    result_numpy = result_numpy.astype("float32")
-    result_torch = result_torch.numpy().astype("float32")
+    result_numpy = result_numpy.astype("float32") / 255.
+    result_torch = result_torch.numpy().astype("float32") / 255.
+
+    # assess whether the normalized images are identical across backends
+    np.testing.assert_almost_equal(result_numpy.flatten(), result_torch.flatten(), decimal=2, verbose=True)
+
+def test_reinhard_torch():
+    size = 1024
+    curr_file_path = os.path.dirname(os.path.realpath(__file__))
+    target = cv2.resize(cv2.cvtColor(cv2.imread(os.path.join(curr_file_path, "../data/target.png")), cv2.COLOR_BGR2RGB), (size, size))
+    to_transform = cv2.resize(cv2.cvtColor(cv2.imread(os.path.join(curr_file_path, "../data/source.png")), cv2.COLOR_BGR2RGB), (size, size))
+
+    # setup preprocessing and preprocess image to be normalized
+    T = transforms.Compose([
+        transforms.ToTensor(),
+        transforms.Lambda(lambda x: x * 255)
+    ])
+    t_to_transform = T(to_transform)
+
+    # initialize normalizers for each backend and fit to target image
+    normalizer = torchstain.normalizers.ReinhardNormalizer(backend='numpy')
+    normalizer.fit(target)
+
+    torch_normalizer = torchstain.normalizers.ReinhardNormalizer(backend='torch')
+    torch_normalizer.fit(T(target))
+
+    # transform
+    result_numpy = normalizer.normalize(I=to_transform)
+    result_torch = torch_normalizer.normalize(I=t_to_transform)
+
+    # convert to numpy and set dtype
+    result_numpy = result_numpy.astype("float32") / 255.
+    result_torch = result_torch.numpy().astype("float32") / 255.
 
+
     # assess whether the normalized images are identical across backends
-    np.testing.assert_almost_equal(ssim(result_numpy.flatten(), result_torch.flatten()), 1.0, decimal=4, verbose=True)
+    np.testing.assert_almost_equal(result_numpy.flatten(), result_torch.flatten(), decimal=2, verbose=True)

torchstain/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '1.2.0'
+__version__ = '1.3.0'
 
 from torchstain.base import normalizers

torchstain/base/normalizers/reinhard.py

@@ -1,11 +1,12 @@
-def ReinhardNormalizer(backend='numpy'):
+def ReinhardNormalizer(backend='numpy', method=None):
     if backend == 'numpy':
         from torchstain.numpy.normalizers import NumpyReinhardNormalizer
-        return NumpyReinhardNormalizer()
+        return NumpyReinhardNormalizer(method=method)
     elif backend == "torch":
-        raise NotImplementedError
+        from torchstain.torch.normalizers import TorchReinhardNormalizer
+        return TorchReinhardNormalizer(method=method)
     elif backend == "tensorflow":
         from torchstain.tf.normalizers import TensorFlowReinhardNormalizer
-        return TensorFlowReinhardNormalizer()
+        return TensorFlowReinhardNormalizer(method=method)
     else:
         raise Exception(f'Unknown backend {backend}')

torchstain/numpy/normalizers/macenko.py

@@ -16,7 +16,7 @@ def __init__(self):
 
     def __convert_rgb2od(self, I, Io=240, beta=0.15):
         # calculate optical density
-        OD = -np.log((I.astype(np.float)+1)/Io)
+        OD = -np.log((I.astype(float)+1)/Io)
 
         # remove transparent pixels
         ODhat = OD[~np.any(OD < beta, axis=1)]

torchstain/numpy/normalizers/reinhard.py

@@ -11,8 +11,9 @@
 https://github.com/Peter554/StainTools/blob/master/staintools/reinhard_color_normalizer.py
 """
 class NumpyReinhardNormalizer(HENormalizer):
-    def __init__(self):
+    def __init__(self, method=None):
         super().__init__()
+        self.method = method
         self.target_mus = None
         self.target_stds = None
 
@@ -41,9 +42,26 @@ def normalize(self, I):
         mus = stack_[:, 0]
         stds = stack_[:, 1]
 
-        # standardize intensities channel-wise and normalize using target mus and stds
-        result = [standardize(x, mu_, std_) * std_T + mu_T for x, mu_, std_, mu_T, std_T \
-            in zip(labs, mus, stds, self.target_means, self.target_stds)]
+        # normalize
+        if self.method is None:
+            # standardize intensities channel-wise and normalize using target mus and stds
+            result = [standardize(x, mu_, std_) * std_T + mu_T for x, mu_, std_, mu_T, std_T \
+                in zip(labs, mus, stds, self.target_means, self.target_stds)]
+
+        elif self.method == "modified":
+            # calculate q
+            q = (self.target_stds[0] - stds[0]) / self.target_stds[0]
+            q = 0.05 if q <= 0 else q
+
+            # normalize each channel independently
+            l_norm = mus[0] + (labs[0] - mus[0]) * (1 + q)
+            a_norm = self.target_means[1] + (labs[1] - mus[1])
+            b_norm = self.target_means[2] + (labs[2] - mus[2])
+
+            result = [l_norm, a_norm, b_norm]
+
+        else:
+            raise ValueError("Unsupported 'method' was chosen. Choose either {None, 'modified'}.")
 
         # rebuild LAB
         lab = lab_merge(*result)

torchstain/tf/normalizers/__init__.py

@@ -1,2 +1,2 @@
 from torchstain.tf.normalizers.macenko import TensorFlowMacenkoNormalizer
-from torchstain.tf.normalizers.reinhard import TensorFlowReinhardNormalizer
+from torchstain.tf.normalizers.reinhard import TensorFlowReinhardNormalizer

torchstain/tf/normalizers/reinhard.py

@@ -11,8 +11,9 @@
 https://github.com/Peter554/StainTools/blob/master/staintools/reinhard_color_normalizer.py
 """
 class TensorFlowReinhardNormalizer(HENormalizer):
-    def __init__(self):
+    def __init__(self, method=None):
         super().__init__()
+        self.method = method
         self.target_mus = None
         self.target_stds = None
 
@@ -41,9 +42,26 @@ def normalize(self, I):
         mus = stack_[:, 0]
         stds = stack_[:, 1]
 
-        # standardize intensities channel-wise and normalize using target mus and stds
-        result = [standardize(x, mu_, std_) * std_T + mu_T for x, mu_, std_, mu_T, std_T \
-            in zip(labs, mus, stds, self.target_means, self.target_stds)]
+        # normalize
+        if self.method is None:
+            # standardize intensities channel-wise and normalize using target mus and stds
+            result = [standardize(x, mu_, std_) * std_T + mu_T for x, mu_, std_, mu_T, std_T \
+                in zip(labs, mus, stds, self.target_means, self.target_stds)]
+
+        elif self.method == "modified":
+            # calculate q
+            q = (self.target_stds[0] - stds[0]) / self.target_stds[0]
+            q = 0.05 if q <= 0 else q
+
+            # normalize each channel independently
+            l_norm = mus[0] + (labs[0] - mus[0]) * (1 + q)
+            a_norm = self.target_means[1] + (labs[1] - mus[1])
+            b_norm = self.target_means[2] + (labs[2] - mus[2])
+
+            result = [l_norm, a_norm, b_norm]
+
+        else:
+            raise ValueError("Unsupported 'method' was chosen. Choose either {None, 'modified'}.")
 
         # rebuild LAB
         lab = lab_merge(*result)

torchstain/tf/utils/split.py

@@ -1,5 +1,4 @@
 import tensorflow as tf
-from torchstain.tf.utils.rgb2lab import rgb2lab
 
 def csplit(I):
     return [I[..., i] for i in range(I.shape[-1])]

torchstain/torch/normalizers/__init__.py

@@ -1 +1,2 @@
 from torchstain.torch.normalizers.macenko import TorchMacenkoNormalizer
+from torchstain.torch.normalizers.reinhard import TorchReinhardNormalizer

torchstain/torch/normalizers/macenko.py

@@ -15,6 +15,9 @@ def __init__(self):
                                    [0.4062, 0.5581]])
         self.maxCRef = torch.tensor([1.9705, 1.0308])
 
+        # Avoid using deprecated torch.lstsq (since 1.9.0)
+        self.updated_lstsq = hasattr(torch.linalg, 'lstsq')
+
     def __convert_rgb2od(self, I, Io, beta):
         I = I.permute(1, 2, 0)
 
@@ -49,13 +52,16 @@ def __find_concentration(self, OD, HE):
         Y = OD.T
 
         # determine concentrations of the individual stains
-        return torch.lstsq(Y, HE)[0][:2]
+        if not self.updated_lstsq:
+            return torch.lstsq(Y, HE)[0][:2]
+
+        return torch.linalg.lstsq(HE, Y)[0]
 
     def __compute_matrices(self, I, Io, alpha, beta):
         OD, ODhat = self.__convert_rgb2od(I, Io=Io, beta=beta)
 
         # compute eigenvectors
-        _, eigvecs = torch.symeig(cov(ODhat.T), eigenvectors=True)
+        _, eigvecs = torch.linalg.eigh(cov(ODhat.T)) 
         eigvecs = eigvecs[:, [1, 2]]
 
         HE = self.__find_HE(ODhat, eigvecs, alpha)