Stain normalization by bhashemian · Pull Request #2666 · Project-MONAI/MONAI

bhashemian · 2021-07-28T22:36:49Z

Description

This PR implement an H&E stain normalization for histopathology images, which contains:

an H&E stain extractor using deconvolution methods from histopathology images, and
an H&E stain normalizer using the extracted stain vectors.

Unlike the previous PR (#1998), which was based on cupy, its purely based on numpy without any CUDA dependency. It expects numpy.ndarray as the input image and returns numpy.ndarray.

Status

Ready

Types of changes

Non-breaking change (fix or new feature that would not break existing functionality).
New tests added to cover the changes.
Integration tests passed locally by running ./runtests.sh -f -u --net --coverage.
Quick tests passed locally by running ./runtests.sh --quick --unittests.
In-line docstrings updated.
Documentation updated, tested make html command in the docs/ folder.

Signed-off-by: Neha Srivathsa <[email protected]>

Signed-off-by: Behrooz <[email protected]>

Signed-off-by: Neha Srivathsa <[email protected]>

Signed-off-by: Behrooz <[email protected]>

… into neha/stain-norm-2

Signed-off-by: Behrooz <[email protected]>

… into neha/stain-norm-2

Signed-off-by: Behrooz <[email protected]>

…lization

Signed-off-by: Behrooz <[email protected]>

wyli

looks good apart from the minor comments. @Nic-Ma could you please help confirm/approve this PR?

wyli · 2021-07-29T23:46:14Z

monai/apps/pathology/transforms/stain/array.py

+            and pseudo-max (100 - alpha percentile). Defaults to 1.
+        beta: absorbance threshold for transparent pixels. Defaults to 0.15
+        max_cref: reference maximum stain concentrations for Hematoxylin & Eosin (H&E).
+            Defaults to None.


the defauts are np.array([1.9705, 1.0308])

wyli · 2021-07-29T23:46:53Z

monai/apps/pathology/transforms/stain/array.py

+        # reshape image and calculate absorbance
+        image = image.reshape((-1, 3))
+        image = image.astype(np.float32) + 1.0
+        absorbance = -np.log(image.clip(max=self.tli) / self.tli)


do we need some validation of the input of np.log?

That's a good point! We should check if the input is intensity (0-255) and not any image or other scales. Thanks @wyli!

Now it checks the image values to be between 0 and 255.

Nic-Ma

Looks good to me except for some minor comments.
I didn't check whether the implementation matches some algorithm theory.

Thanks.

Nic-Ma · 2021-07-30T02:28:58Z

docs/source/apps.rst

+    :members:
+
+.. automodule:: monai.apps.pathology.transforms.stain.dictionary
+.. autoclass:: ExtractHEStainsD


Suggest to use ExtractHEStainsd to align with other docs, same as NormalizeHEStainsD.

Nic-Ma · 2021-07-30T02:30:52Z

monai/apps/pathology/transforms/stain/array.py

+
+        self.max_cref = max_cref
+        if self.max_cref is None:
+            self.max_cref = np.array([1.9705, 1.0308])


As @wyli commented, set default to 1.9705, 1.0308 directly.

Thanks.

Nic-Ma · 2021-07-30T02:31:46Z

monai/apps/pathology/transforms/stain/array.py

+        """Perform Stain Deconvolution and return stain matrix for the image.
+
+        Args:
+            img: uint8 RGB image to perform stain deconvolution of


Maybe of -> on or for?

Nic-Ma · 2021-07-30T02:37:49Z

monai/apps/pathology/transforms/stain/array.py

+            pseudo-max (100 - alpha percentile). Defaults to 1.
+        beta: absorbance threshold for transparent pixels. Defaults to 0.15.
+        target_he: target stain matrix. Defaults to None.
+        max_cref: reference maximum stain concentrations for Hematoxylin & Eosin (H&E).


Default values of target_he and max_cref are same as the other comment.

Nic-Ma · 2021-07-30T02:39:32Z

monai/apps/pathology/transforms/stain/dictionary.py

+        tli: float = 240,
+        alpha: float = 1,
+        beta: float = 0.15,
+        max_cref: Optional[np.ndarray] = None,


Same as the other comment.

Nic-Ma · 2021-07-30T02:39:54Z

monai/apps/pathology/transforms/stain/dictionary.py

+        tli: float = 240,
+        alpha: float = 1,
+        beta: float = 0.15,
+        target_he: Optional[np.ndarray] = None,


same comment for default value.

Signed-off-by: Behrooz <[email protected]>

…ain-normalization

bhashemian · 2021-07-30T03:44:34Z

@wyli and @Nic-Ma
Thanks for you comments. I addressed all of them. Please let me know if I missed anything.

* added stain norm and tests Signed-off-by: Neha Srivathsa <[email protected]> * import changes Signed-off-by: Neha Srivathsa <[email protected]> * changed stain extraction tests Signed-off-by: Neha Srivathsa <[email protected]> * edited stain norm tests Signed-off-by: Neha Srivathsa <[email protected]> * convert floats to float32 Signed-off-by: Neha Srivathsa <[email protected]> * added uint8 assumption to docstring Signed-off-by: Neha Srivathsa <[email protected]> * add error case Signed-off-by: Neha Srivathsa <[email protected]> * formatting change Signed-off-by: Neha Srivathsa <[email protected]> * modify tests wrt cupy import Signed-off-by: Neha Srivathsa <[email protected]> * minor change to pass lint test Signed-off-by: Neha Srivathsa <[email protected]> * import changes Signed-off-by: Neha Srivathsa <[email protected]> * refactored classes Signed-off-by: Neha Srivathsa <[email protected]> * Restructure and rename transforms Signed-off-by: Behrooz <[email protected]> * added dict transform Signed-off-by: Neha Srivathsa <[email protected]> * Move stain_extractor to init Signed-off-by: Behrooz <[email protected]> * Exclude pathology transform tests from mini tests Signed-off-by: Behrooz <[email protected]> * Fix type checking for cupy ndarray Signed-off-by: Behrooz <[email protected]> * Include pathology transform tests Signed-off-by: Behrooz <[email protected]> * Update to cupy 9.0.0 Signed-off-by: Behrooz <[email protected]> * Remove exact version for cupy Signed-off-by: Behrooz <[email protected]> * add to docs Signed-off-by: Neha Srivathsa <[email protected]> * Organize into stain dir Signed-off-by: Behrooz <[email protected]> * Add/update init files Signed-off-by: Behrooz <[email protected]> * Transit all from cupy to numpy Signed-off-by: Behrooz <[email protected]> * Update imports Signed-off-by: Behrooz <[email protected]> * Update test cases for numpy Signed-off-by: Behrooz <[email protected]> * Rename to NormalizeHEStains and NormalizeHEStainsD Signed-off-by: Behrooz <[email protected]> * Add dictionary variant names Signed-off-by: Behrooz <[email protected]> * Fix typing and formatting Signed-off-by: Behrooz <[email protected]> * Fix docs Signed-off-by: Behrooz <[email protected]> * Update test cases Signed-off-by: Behrooz <[email protected]> * Fix clip max Signed-off-by: Behrooz <[email protected]> * Fix var typing Signed-off-by: Behrooz <[email protected]> * Fix a typing issue Signed-off-by: Behrooz <[email protected]> * Update default values, and change D to d Signed-off-by: Behrooz <[email protected]> * Update docs Signed-off-by: Behrooz <[email protected]> * Add image value check Signed-off-by: Behrooz <[email protected]> * Add test cases for negative and invalid values Signed-off-by: Behrooz <[email protected]> Co-authored-by: Neha Srivathsa <[email protected]> Co-authored-by: nsrivathsa <[email protected]>

nsrivathsa and others added 30 commits April 12, 2021 18:17

added stain norm and tests

3e2de71

Signed-off-by: Neha Srivathsa <[email protected]>

Merge branch 'master' into neha/stain-norm-2

cc6bc76

import changes

e197f9d

Signed-off-by: Neha Srivathsa <[email protected]>

changed stain extraction tests

ad957fa

Signed-off-by: Neha Srivathsa <[email protected]>

edited stain norm tests

00518fa

Signed-off-by: Neha Srivathsa <[email protected]>

convert floats to float32

45a2ac5

Signed-off-by: Neha Srivathsa <[email protected]>

added uint8 assumption to docstring

4b0f696

Signed-off-by: Neha Srivathsa <[email protected]>

add error case

cb99aef

Signed-off-by: Neha Srivathsa <[email protected]>

Merge branch 'master' into neha/stain-norm-2

ad29340

formatting change

3fcc366

Signed-off-by: Neha Srivathsa <[email protected]>

modify tests wrt cupy import

fa95e0d

Signed-off-by: Neha Srivathsa <[email protected]>

Merge branch 'master' into neha/stain-norm-2

4746f33

minor change to pass lint test

f3b2909

Signed-off-by: Neha Srivathsa <[email protected]>

import changes

b80fc17

Signed-off-by: Neha Srivathsa <[email protected]>

Merge branch 'master' into neha/stain-norm-2

1e36ebc

refactored classes

05ec786

Signed-off-by: Neha Srivathsa <[email protected]>

Restructure and rename transforms

bcb2211

Signed-off-by: Behrooz <[email protected]>

Merge branch 'dev' into neha/stain-norm-2

a922bc2

added dict transform

283444e

Signed-off-by: Neha Srivathsa <[email protected]>

Merge branch 'dev' into neha/stain-norm-2

dbb95d8

Move stain_extractor to init

7440a5b

Signed-off-by: Behrooz <[email protected]>

Exclude pathology transform tests from mini tests

f6e9b38

Signed-off-by: Behrooz <[email protected]>

Merge branch 'dev' into neha/stain-norm-2

26c9e5a

Fix type checking for cupy ndarray

72e0448

Signed-off-by: Behrooz <[email protected]>

Merge branch 'neha/stain-norm-2' of https://github.com/nsrivathsa/MONAI…

58cc4b7

… into neha/stain-norm-2

Include pathology transform tests

be88f7d

Signed-off-by: Behrooz <[email protected]>

Merge branch 'dev' into neha/stain-norm-2

3589326

Update to cupy 9.0.0

dd5d82e

Signed-off-by: Behrooz <[email protected]>

Remove exact version for cupy

128f01d

Signed-off-by: Behrooz <[email protected]>

Merge branch 'neha/stain-norm-2' of https://github.com/nsrivathsa/MONAI…

a462c97

… into neha/stain-norm-2

bhashemian added 15 commits July 26, 2021 16:24

Add/update init files

eb411d7

Signed-off-by: Behrooz <[email protected]>

Transit all from cupy to numpy

9ddb4e1

Signed-off-by: Behrooz <[email protected]>

Update imports

24cdf11

Signed-off-by: Behrooz <[email protected]>

Update test cases for numpy

f26ef3a

Signed-off-by: Behrooz <[email protected]>

Rename to NormalizeHEStains and NormalizeHEStainsD

e7ad5a5

Signed-off-by: Behrooz <[email protected]>

Add dictionary variant names

7621fb4

Signed-off-by: Behrooz <[email protected]>

Merge branch 'dev' of github.com:Project-MONAI/MONAI into stain-norma…

f8934c3

…lization

Fix typing and formatting

e5b8c62

Signed-off-by: Behrooz <[email protected]>

Fix docs

b157c7c

Signed-off-by: Behrooz <[email protected]>

Update test cases

a050965

Signed-off-by: Behrooz <[email protected]>

Fix clip max

34c20c3

Signed-off-by: Behrooz <[email protected]>

Fix var typing

010326d

Signed-off-by: Behrooz <[email protected]>

Merge branch 'dev' into stain-normalization

ba52324

Fix a typing issue

d47312e

Signed-off-by: Behrooz <[email protected]>

Merge branch 'dev' into stain-normalization

721cba9

bhashemian requested review from wyli and yiheng-wang-nv and removed request for yiheng-wang-nv July 29, 2021 14:16

wyli reviewed Jul 29, 2021

View reviewed changes

wyli requested a review from Nic-Ma July 29, 2021 23:49

Nic-Ma approved these changes Jul 30, 2021

View reviewed changes

bhashemian added 5 commits July 30, 2021 03:13

Update default values, and change D to d

5f0681d

Signed-off-by: Behrooz <[email protected]>

Update docs

d398047

Signed-off-by: Behrooz <[email protected]>

Add image value check

9daead3

Signed-off-by: Behrooz <[email protected]>

Add test cases for negative and invalid values

bca9815

Signed-off-by: Behrooz <[email protected]>

Merge branch 'stain-normalization' of github.com:behxyz/MONAI into st…

4248261

…ain-normalization

wyli merged commit 30ce63d into Project-MONAI:dev Jul 30, 2021

gigony mentioned this pull request Sep 7, 2021

[FEA] Add Stain Normalization operation (in Python) rapidsai/cucim#96

Closed

Conversation

bhashemian commented Jul 28, 2021

Description

Status

Types of changes

Uh oh!

wyli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Nic-Ma left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhashemian commented Jul 30, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants