Merge pull request #62 from EIDOSLAB/development

Development

Author: carloalbertobarbano

.github/workflows/build.yaml

@@ -9,8 +9,8 @@ jobs:
     runs-on: ubuntu-20.04
 
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
         with:
           python-version: '3.x'
 
@@ -20,7 +20,7 @@ jobs:
       - name: Build wheels
         run: python setup.py sdist bdist_wheel
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           path: ./dist/*
 
@@ -31,7 +31,7 @@ jobs:
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
 
     steps:
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         with:
           name: artifact
           path: dist

.github/workflows/tests_full.yml

@@ -1,4 +1,4 @@
-name: tests
+name: Full Tests
 
 on:
   push:
@@ -7,6 +7,7 @@ on:
   pull_request:
     branches:
       - main
+  workflow_dispatch:
 
 jobs:
   build:
@@ -15,9 +16,9 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v') != true
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Set up Python 3.6
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: 3.6
 
@@ -28,7 +29,7 @@ jobs:
         run: python setup.py bdist_wheel
 
       - name: Upload Python wheel
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: Python wheel
           path: ${{github.workspace}}/dist/torchstain-*.whl
@@ -39,24 +40,24 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ windows-2019, ubuntu-20.04, macos-12 ]
+        os: [ windows-2019, ubuntu-20.04, macos-13 ]
         python-version: [ 3.7, 3.8, 3.9 ]
         tf-version: [2.7.0, 2.8.0, 2.9.0]
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Download artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: "Python wheel"
 
       - name: Install dependencies
-        run: pip install tensorflow==${{ matrix.tf-version }} protobuf==3.20.* opencv-python-headless scikit-image pytest
+        run: pip install tensorflow==${{ matrix.tf-version }} protobuf==3.20.* opencv-python-headless scikit-image pytest "numpy<2"
 
       - name: Install wheel
         run: pip install --find-links=${{github.workspace}} torchstain-*
@@ -70,31 +71,24 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ windows-2019, ubuntu-20.04, macos-12 ]
-        python-version: [ 3.6, 3.7, 3.8, 3.9 ]
+        os: [ windows-2019, ubuntu-20.04, macos-13 ]
+        python-version: [ 3.7, 3.8, 3.9 ]
         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
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Download artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: "Python wheel"
 
       - name: Install dependencies
-        run: pip install torch==${{ matrix.pytorch-version }} torchvision opencv-python-headless scikit-image pytest
+        run: pip install torch==${{ matrix.pytorch-version }} torchvision opencv-python-headless scikit-image pytest "numpy<2"
 
       - name: Install wheel
         run: pip install --find-links=${{github.workspace}} torchstain-*

.github/workflows/tests_quick.yml

@@ -1,4 +1,4 @@
-name: tests
+name: Quick Tests
 
 on:
   push:
@@ -7,14 +7,15 @@ on:
   pull_request:
     branches-ignore:
       - main
+  workflow_dispatch:
 
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Set up Python 3.6
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: 3.6
 
@@ -25,7 +26,7 @@ jobs:
         run: python setup.py bdist_wheel
 
       - name: Upload Python wheel
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: Python wheel
           path: ${{github.workspace}}/dist/torchstain-*.whl
@@ -36,14 +37,14 @@ jobs:
     runs-on: ubuntu-20.04
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Set up Python 3.8
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: 3.8
 
       - name: Download artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: "Python wheel"
 
@@ -62,14 +63,14 @@ jobs:
     runs-on: ubuntu-20.04
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Set up Python 3.8
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: 3.8
 
       - name: Download artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: "Python wheel"
 

README.md

@@ -5,12 +5,16 @@
 [![Pip Downloads](https://img.shields.io/pypi/dm/torchstain?label=pip%20downloads&logo=python)](https://pypi.org/project/torchstain/)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7692014.svg)](https://doi.org/10.5281/zenodo.7692014)
 
-GPU-accelerated stain normalization tools for histopathological images. Compatible with PyTorch, TensorFlow, and Numpy.
-Normalization algorithms currently implemented:
+GPU-accelerated stain tools for histopathological images. Compatible with PyTorch, TensorFlow, and Numpy.
 
+Normalization algorithms currently implemented:
 - Macenko [\[1\]](#reference) (ported from [numpy implementation](https://github.com/schaugf/HEnorm_python))
 - Reinhard [\[2\]](#reference)
 - Modified Reinhard [\[3\]](#reference)
+- Multi-target Macenko [\[4\]](#reference)
+
+Augmentation algorithms currently implemented:
+- Macenko-Aug [\[1\]](#reference) (inspired by [StainTools](https://github.com/Peter554/StainTools))
 
 ## Installation
 
@@ -52,10 +56,12 @@ norm, H, E = normalizer.normalize(I=t_to_transform, stains=True)
 | Macenko | ✓ | ✓ | ✓ |
 | Reinhard | ✓ | ✓ | ✓ |
 | Modified Reinhard | ✓ | ✓ | ✓ |
+| Multi-target Macenko | ✗ | ✓ | ✗ |
+| Macenko-Aug | ✓ | ✓ | ✓ |
 
 ## Backend comparison
 
-Results with 10 runs per size on a Intel(R) Core(TM) i5-8365U CPU @ 1.60GHz
+Runtimes using the Macenko algorithm using different backends. Metrics were calculated from 10 repeated runs for each quadratic image size on an Intel(R) Core(TM) i5-8365U CPU @ 1.60GHz.
 
 |   size | numpy avg. time   | torch avg. time   | tf avg. time     |
 |--------|-------------------|-------------------|------------------|
@@ -73,15 +79,15 @@ Results with 10 runs per size on a Intel(R) Core(TM) i5-8365U CPU @ 1.60GHz
 - [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.
+- [4] Ivanov, Desislav et al. "Multi-target stain normalization for histology slides". arXiv (preprint). 2024.
 
 ## Citing
 
 If you find this software useful for your research, please cite it as: 
 
 ```bibtex
 @software{barbano2022torchstain,
-  author       = {Carlo Alberto Barbano and
-                  André Pedersen},
+  author       = {Carlo Alberto Barbano and André Pedersen},
   title        = {EIDOSLAB/torchstain: v1.2.0-stable},
   month        = aug,
   year         = 2022,

apps/example_norm.py

@@ -6,7 +6,6 @@
 import time
 import os
 
-
 size = 1024
 dir_path = os.path.dirname(os.path.abspath(__file__))
 target = cv2.resize(cv2.cvtColor(cv2.imread(dir_path + "/../data/target.png"), cv2.COLOR_BGR2RGB), (size, size))

compare.py

@@ -1,7 +1,6 @@
 import torch
 from torchvision import transforms
 import torchstain
-
 import cv2
 import matplotlib.pyplot as plt
 import time

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(float)+1)/Io)
+        OD = -np.log((I.astype(float) + 1) / Io)
 
         # remove transparent pixels
         ODhat = OD[~np.any(OD < beta, axis=1)]
@@ -26,22 +26,22 @@ def __convert_rgb2od(self, I, Io=240, beta=0.15):
     def __find_HE(self, ODhat, eigvecs, alpha):
         #project on the plane spanned by the eigenvectors corresponding to the two
         # largest eigenvalues
-        That = ODhat.dot(eigvecs[:,1:3])
+        That = ODhat.dot(eigvecs[:, 1:3])
 
-        phi = np.arctan2(That[:,1],That[:,0])
+        phi = np.arctan2(That[:, 1], That[:, 0])
 
         minPhi = np.percentile(phi, alpha)
-        maxPhi = np.percentile(phi, 100-alpha)
+        maxPhi = np.percentile(phi, 100 - alpha)
 
-        vMin = eigvecs[:,1:3].dot(np.array([(np.cos(minPhi), np.sin(minPhi))]).T)
-        vMax = eigvecs[:,1:3].dot(np.array([(np.cos(maxPhi), np.sin(maxPhi))]).T)
+        vMin = eigvecs[:, 1:3].dot(np.array([(np.cos(minPhi), np.sin(minPhi))]).T)
+        vMax = eigvecs[:, 1:3].dot(np.array([(np.cos(maxPhi), np.sin(maxPhi))]).T)
 
         # a heuristic to make the vector corresponding to hematoxylin first and the
         # one corresponding to eosin second
         if vMin[0] > vMax[0]:
-            HE = np.array((vMin[:,0], vMax[:,0])).T
+            HE = np.array((vMin[:, 0], vMax[:, 0])).T
         else:
-            HE = np.array((vMax[:,0], vMin[:,0])).T
+            HE = np.array((vMax[:, 0], vMin[:, 0])).T
 
         return HE
 
@@ -55,7 +55,7 @@ def __find_concentration(self, OD, HE):
         return C
 
     def __compute_matrices(self, I, Io, alpha, beta):
-        I = I.reshape((-1,3))
+        I = I.reshape((-1, 3))
 
         OD, ODhat = self.__convert_rgb2od(I, Io=Io, beta=beta)
 
@@ -67,7 +67,7 @@ def __compute_matrices(self, I, Io, alpha, beta):
         C = self.__find_concentration(OD, HE)
 
         # normalize stain concentrations
-        maxC = np.array([np.percentile(C[0,:], 99), np.percentile(C[1,:],99)])
+        maxC = np.array([np.percentile(C[0, :], 99), np.percentile(C[1, :],99)])
 
         return HE, C, maxC
 
@@ -81,7 +81,7 @@ def normalize(self, I, Io=240, alpha=1, beta=0.15, stains=True):
         ''' Normalize staining appearence of H&E stained images
 
         Example use:
-            see test.py
+            see example.py
 
         Input:
             I: RGB input image
@@ -97,7 +97,7 @@ def normalize(self, I, Io=240, alpha=1, beta=0.15, stains=True):
             Macenko et al., ISBI 2009
         '''
         h, w, c = I.shape
-        I = I.reshape((-1,3))
+        I = I.reshape((-1, 3))
 
         HE, C, maxC = self.__compute_matrices(I, Io, alpha, beta)
 
@@ -113,11 +113,11 @@ def normalize(self, I, Io=240, alpha=1, beta=0.15, stains=True):
 
         if stains:
             # unmix hematoxylin and eosin
-            H = np.multiply(Io, np.exp(np.expand_dims(-self.HERef[:,0], axis=1).dot(np.expand_dims(C2[0,:], axis=0))))
+            H = np.multiply(Io, np.exp(np.expand_dims(-self.HERef[:, 0], axis=1).dot(np.expand_dims(C2[0, :], axis=0))))
             H[H > 255] = 255
             H = np.reshape(H.T, (h, w, c)).astype(np.uint8)
 
-            E = np.multiply(Io, np.exp(np.expand_dims(-self.HERef[:,1], axis=1).dot(np.expand_dims(C2[1,:], axis=0))))
+            E = np.multiply(Io, np.exp(np.expand_dims(-self.HERef[:, 1], axis=1).dot(np.expand_dims(C2[1, :], axis=0))))
             E[E > 255] = 255
             E = np.reshape(E.T, (h, w, c)).astype(np.uint8)
 

torchstain/numpy/normalizers/reinhard.py

@@ -25,8 +25,7 @@ def fit(self, target):
         lab = rgb2lab(target)
 
         # get summary statistics
-#         stack_ = np.apply_along_axis(get_mean_std, 1, lab_split(lab))
-        stack_ = np.apply_along_axis(get_mean_std, axis=1, arr=lab_split(lab))
+        stack_ = np.array([get_mean_std(x) for x in lab_split(lab)])
 
         self.target_means = stack_[:, 0]
         self.target_stds = stack_[:, 1]
@@ -40,8 +39,7 @@ def normalize(self, I):
         labs = lab_split(lab)
 
         # get summary statistics from LAB
-#         stack_ = np.apply_along_axis(get_mean_std, 1, labs)
-        stack_ = np.apply_along_axis(get_mean_std, axis=1, arr=labs)
+        stack_ = np.array([get_mean_std(x) for x in labs])
 
         mus = stack_[:, 0]
         stds = stack_[:, 1]