Repository: Project-MONAI/MONAI

Issue:
Nonlinear histogram intensity transform
**Describe the solution you'd like**
I think it would be useful to have a transform that provides random, nonlinear warping of an image's intensity histogram. This is motivated by research showing that strong contrast adjustments can force networks to focus on learning shapes, rather than intensity differences, increasing the generalisability of trained networks to new data, see e.g. [here](https://arxiv.org/pdf/2003.01995.pdf).

**Additional context**
I've already worked on a version of this transform for my own research, and included a couple of examples below. I can integrate into MONAI if you think it would be a good addition.

Mild augmentation:
![image](https://user-images.githubusercontent.com/7947315/89523331-92906380-d7da-11ea-9bd6-2470bc6c46db.png)

Strong augmentation:
![image](https://user-images.githubusercontent.com/7947315/89523766-58739180-d7db-11ea-87ca-a5c270f1e770.png)





Discussion:
looks great, just wanted to note that some intensity mappings would cause information loss, for example, in the strong augmentation case, original intensities 5.5 to 7.5 are all mapped to about 8, the relevant tissues become indistinguishable in the transform output
Hi @marksgraham ,

Welcome to contribute your idea to MONAI!
BTW, we have some similar intensity transforms:
https://github.com/Project-MONAI/MONAI/blob/master/monai/transforms/intensity/array.py#L300

https://github.com/Project-MONAI/MONAI/blob/master/monai/transforms/intensity/array.py#L554

Thanks.

Resolving patch:
diff --git a/monai/transforms/intensity/array.py b/monai/transforms/intensity/array.py
--- a/monai/transforms/intensity/array.py
+++ b/monai/transforms/intensity/array.py
@@ -656,3 +656,46 @@ def __call__(self, img: np.ndarray) -> np.ndarray:
         sigma1 = ensure_tuple_size(tup=(self.x1, self.y1, self.z1), dim=img.ndim - 1)
         sigma2 = ensure_tuple_size(tup=(self.x2, self.y2, self.z2), dim=img.ndim - 1)
         return GaussianSharpen(sigma1=sigma1, sigma2=sigma2, alpha=self.a)(img)
+
+
+class RandHistogramShift(Randomizable, Transform):
+    """
+    Apply random nonlinear transform to the image's intensity histogram.
+
+    Args:
+        num_control_points: number of control points governing the nonlinear intensity mapping.
+            a smaller number of control points allows for larger intensity shifts. if two values provided, number of
+            control points selecting from range (min_value, max_value).
+        prob: probability of histogram shift.
+    """
+
+    def __init__(self, num_control_points: Union[Tuple[int, int], int] = 10, prob: float = 0.1) -> None:
+
+        if isinstance(num_control_points, int):
+            assert num_control_points > 2, "num_control_points should be greater than or equal to 3"
+            self.num_control_points = (num_control_points, num_control_points)
+        else:
+            assert len(num_control_points) == 2, "num_control points should be a number or a pair of numbers"
+            assert min(num_control_points) > 2, "num_control_points should be greater than or equal to 3"
+            self.num_control_points = (min(num_control_points), max(num_control_points))
+        self.prob = prob
+        self._do_transform = False
+
+    def randomize(self, data: Optional[Any] = None) -> None:
+        self._do_transform = self.R.random() < self.prob
+        num_control_point = self.R.randint(self.num_control_points[0], self.num_control_points[1] + 1)
+        self.reference_control_points = np.linspace(0, 1, num_control_point)
+        self.floating_control_points = np.copy(self.reference_control_points)
+        for i in range(1, num_control_point - 1):
+            self.floating_control_points[i] = self.R.uniform(
+                self.floating_control_points[i - 1], self.floating_control_points[i + 1]
+            )
+
+    def __call__(self, img: np.ndarray) -> np.ndarray:
+        self.randomize()
+        if not self._do_transform:
+            return img
+        img_min, img_max = img.min(), img.max()
+        reference_control_points_scaled = self.reference_control_points * (img_max - img_min) + img_min
+        floating_control_points_scaled = self.floating_control_points * (img_max - img_min) + img_min
+        return np.interp(img, reference_control_points_scaled, floating_control_points_scaled)
diff --git a/monai/transforms/intensity/dictionary.py b/monai/transforms/intensity/dictionary.py
--- a/monai/transforms/intensity/dictionary.py
+++ b/monai/transforms/intensity/dictionary.py
@@ -599,6 +599,57 @@ def __call__(self, data):
         return d
 
 
+class RandHistogramShiftd(Randomizable, MapTransform):
+    """
+    Dictionary-based version :py:class:`monai.transforms.RandHistogramShift`.
+    Apply random nonlinear transform the the image's intensity histogram.
+
+    Args:
+        keys: keys of the corresponding items to be transformed.
+            See also: monai.transforms.MapTransform
+        num_control_points: number of control points governing the nonlinear intensity mapping.
+            a smaller number of control points allows for larger intensity shifts. if two values provided, number of
+            control points selecting from range (min_value, max_value).
+        prob: probability of histogram shift.
+    """
+
+    def __init__(
+        self, keys: KeysCollection, num_control_points: Union[Tuple[int, int], int] = 10, prob: float = 0.1
+    ) -> None:
+        super().__init__(keys)
+        if isinstance(num_control_points, int):
+            assert num_control_points > 2, "num_control_points should be greater than or equal to 3"
+            self.num_control_points = (num_control_points, num_control_points)
+        else:
+            assert len(num_control_points) == 2, "num_control points should be a number or a pair of numbers"
+            assert min(num_control_points) > 2, "num_control_points should be greater than or equal to 3"
+            self.num_control_points = (min(num_control_points), max(num_control_points))
+        self.prob = prob
+        self._do_transform = False
+
+    def randomize(self, data: Optional[Any] = None) -> None:
+        self._do_transform = self.R.random() < self.prob
+        num_control_point = self.R.randint(self.num_control_points[0], self.num_control_points[1] + 1)
+        self.reference_control_points = np.linspace(0, 1, num_control_point)
+        self.floating_control_points = np.copy(self.reference_control_points)
+        for i in range(1, num_control_point - 1):
+            self.floating_control_points[i] = self.R.uniform(
+                self.floating_control_points[i - 1], self.floating_control_points[i + 1]
+            )
+
+    def __call__(self, data: Mapping[Hashable, np.ndarray]) -> Dict[Hashable, np.ndarray]:
+        d = dict(data)
+        self.randomize()
+        if not self._do_transform:
+            return d
+        for key in self.keys:
+            img_min, img_max = d[key].min(), d[key].max()
+            reference_control_points_scaled = self.reference_control_points * (img_max - img_min) + img_min
+            floating_control_points_scaled = self.floating_control_points * (img_max - img_min) + img_min
+            d[key] = np.interp(d[key], reference_control_points_scaled, floating_control_points_scaled)
+        return d
+
+
 RandGaussianNoiseD = RandGaussianNoiseDict = RandGaussianNoised
 ShiftIntensityD = ShiftIntensityDict = ShiftIntensityd
 RandShiftIntensityD = RandShiftIntensityDict = RandShiftIntensityd
@@ -615,3 +666,4 @@ def __call__(self, data):
 RandGaussianSmoothD = RandGaussianSmoothDict = RandGaussianSmoothd
 GaussianSharpenD = GaussianSharpenDict = GaussianSharpend
 RandGaussianSharpenD = RandGaussianSharpenDict = RandGaussianSharpend
+RandHistogramShiftD = RandHistogramShiftDict = RandHistogramShiftd


Test patch:
diff --git a/tests/test_rand_histogram_shift.py b/tests/test_rand_histogram_shift.py
new file mode 100644
--- /dev/null
+++ b/tests/test_rand_histogram_shift.py
@@ -0,0 +1,48 @@
+# Copyright 2020 MONAI Consortium
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+import numpy as np
+from parameterized import parameterized
+
+from monai.transforms import RandHistogramShift
+
+TEST_CASES = [
+    [
+        {"num_control_points": 5, "prob": 0.0},
+        {"img": np.arange(8).reshape((1, 2, 2, 2))},
+        np.arange(8).reshape((1, 2, 2, 2)),
+    ],
+    [
+        {"num_control_points": 5, "prob": 0.9},
+        {"img": np.arange(8).reshape((1, 2, 2, 2))},
+        np.array([[[[0.0, 0.57227867], [1.1391707, 1.68990281]], [[2.75833219, 4.34445884], [5.70913743, 7.0]]]]),
+    ],
+    [
+        {"num_control_points": (5, 20), "prob": 0.9},
+        {"img": np.arange(8).reshape((1, 2, 2, 2))},
+        np.array([[[[0.0, 1.17472492], [2.21553091, 2.88292011]], [[3.98407301, 5.01302123], [6.09275004, 7.0]]]]),
+    ],
+]
+
+
+class TestRandHistogramShift(unittest.TestCase):
+    @parameterized.expand(TEST_CASES)
+    def test_rand_histogram_shift(self, input_param, input_data, expected_val):
+        g = RandHistogramShift(**input_param)
+        g.set_random_state(123)
+        result = g(**input_data)
+        np.testing.assert_allclose(result, expected_val, rtol=1e-4, atol=1e-4)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_rand_histogram_shiftd.py b/tests/test_rand_histogram_shiftd.py
new file mode 100644
--- /dev/null
+++ b/tests/test_rand_histogram_shiftd.py
@@ -0,0 +1,61 @@
+# Copyright 2020 MONAI Consortium
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+import numpy as np
+from parameterized import parameterized
+
+from monai.transforms import RandHistogramShiftD
+
+TEST_CASES = [
+    [
+        {"keys": ("img"), "num_control_points": 5, "prob": 0.0},
+        {"img": np.arange(8).reshape((1, 2, 2, 2)), "seg": np.ones(8).reshape((1, 2, 2, 2))},
+        {"img": np.arange(8).reshape((1, 2, 2, 2)), "seg": np.ones(8).reshape((1, 2, 2, 2))},
+    ],
+    [
+        {"keys": ("img"), "num_control_points": 5, "prob": 0.9},
+        {"img": np.arange(8).reshape((1, 2, 2, 2)), "seg": np.ones(8).reshape((1, 2, 2, 2))},
+        {
+            "img": np.array(
+                [[[[0.0, 0.57227867], [1.1391707, 1.68990281]], [[2.75833219, 4.34445884], [5.70913743, 7.0]]]]
+            ),
+            "seg": np.ones(8).reshape((1, 2, 2, 2)),
+        },
+    ],
+    [
+        {"keys": ("img"), "num_control_points": (5, 20), "prob": 0.9},
+        {"img": np.arange(8).reshape((1, 2, 2, 2)), "seg": np.ones(8).reshape((1, 2, 2, 2))},
+        {
+            "img": np.array(
+                [[[[0.0, 1.17472492], [2.21553091, 2.88292011]], [[3.98407301, 5.01302123], [6.09275004, 7.0]]]]
+            ),
+            "seg": np.ones(8).reshape((1, 2, 2, 2)),
+        },
+    ],
+]
+
+
+class TestRandHistogramShiftD(unittest.TestCase):
+    @parameterized.expand(TEST_CASES)
+    def test_rand_histogram_shiftd(self, input_param, input_data, expected_val):
+        g = RandHistogramShiftD(**input_param)
+        g.set_random_state(123)
+        res = g(input_data)
+        for key in res:
+            result = res[key]
+            expected = expected_val[key] if isinstance(expected_val, dict) else expected_val
+            np.testing.assert_allclose(result, expected, rtol=1e-4, atol=1e-4)
+
+
+if __name__ == "__main__":
+    unittest.main()