Added tests; updated documentation

Author: atbenmurray

monai/transforms/compose.py

@@ -197,20 +197,22 @@ def execute(
         ``execute`` provides the implementation that Compose uses to execute a sequence
         of transforms. As well as being used by Compose, it can be used by subclasses of
         Compose and by code that doesn't have a Compose instance but needs to execute a
-        sequence of transforms is if it were executed by Compose. For the most part, it
-        is recommended to use Compose instances, however.
+        sequence of transforms is if it were executed by Compose. It should only be used directly
+        when it is not possible to use ``Compose.__call__`` to achieve the same goal.
         Args:
             input_: a tensor-like object to be transformed
             transforms: a sequence of transforms to be carried out
-            map_items: whether to apply the transform to each item in ``data```.
+            map_items: whether to apply the transform to each item in ``data``.
             Defaults to True if not set.
             unpack_items: whether to unpack parameters using '*'. Defaults to False if not set
             log_stats: whether to log detailed information about the application of ``transforms``
             to ``input_``. For NumPy ndarrays and PyTorch tensors, log only the data shape and
             value range. Defaults to False if not set.
-            start:
-            end:
-            threading:
+            start: the index of the first transform to be executed. If not set, this defaults to 0
+            end: the index after the last transform to be exectued. If set, the transform at index-1
+            is the last transform that is executed. If this is not set, it defaults to len(transforms)
+            threading: whether executing is happening in a threaded environment. If set, copies are made
+            of transforms that have the ``RandomizedTrait`` interface.
 
         Returns:
 

tests/test_compose.py

@@ -13,9 +13,15 @@
 
 import sys
 import unittest
+from copy import deepcopy
+
+from parameterized import parameterized
+
+import numpy as np
+import torch
 
 from monai.data import DataLoader, Dataset
-from monai.transforms import AddChannel, Compose
+from monai.transforms import AddChannel, Compose, Flip, Rotate90, Zoom, NormalizeIntensity, Rotate, Rotated
 from monai.transforms.transform import Randomizable
 from monai.utils import set_determinism
 
@@ -56,8 +62,12 @@ def b(d):
             d["b"] += 1
             return d
 
-        c = Compose([a, b, a, b, a])
-        self.assertDictEqual(c({"a": 0, "b": 0}), {"a": 3, "b": 2})
+        transforms = [a, b, a, b, a]
+        data = {"a": 0, "b": 0}
+        expected = {"a": 3, "b": 2}
+
+        self.assertDictEqual(Compose(transforms)(data), expected)
+        self.assertDictEqual(Compose.execute(data, transforms), expected)
 
     def test_list_dict_compose(self):
         def a(d):  # transform to handle dict data
@@ -76,10 +86,15 @@ def c(d):  # transform to handle dict data
             d["c"] += 1
             return d
 
-        transforms = Compose([a, a, b, c, c])
-        value = transforms({"a": 0, "b": 0, "c": 0})
+        transforms = [a, a, b, c, c]
+        data = {"a": 0, "b": 0, "c": 0}
+        expected = {"a": 2, "b": 1, "c": 2}
+        value = Compose(transforms)(data)
+        for item in value:
+            self.assertDictEqual(item, expected)
+        value = Compose.execute(data, transforms)
         for item in value:
-            self.assertDictEqual(item, {"a": 2, "b": 1, "c": 2})
+            self.assertDictEqual(item, expected)
 
     def test_non_dict_compose_with_unpack(self):
         def a(i, i2):
@@ -88,8 +103,11 @@ def a(i, i2):
         def b(i, i2):
             return i + "b", i2 + "b2"
 
-        c = Compose([a, b, a, b], map_items=False, unpack_items=True)
-        self.assertEqual(c(("", "")), ("abab", "a2b2a2b2"))
+        transforms = [a, b, a, b]
+        data = ("", "")
+        expected = ("abab", "a2b2a2b2")
+        self.assertEqual(Compose(transforms, map_items=False, unpack_items=True)(data), expected)
+        self.assertEqual(Compose.execute(data, transforms, map_items=False, unpack_items=True), expected)
 
     def test_list_non_dict_compose_with_unpack(self):
         def a(i, i2):
@@ -98,8 +116,11 @@ def a(i, i2):
         def b(i, i2):
             return i + "b", i2 + "b2"
 
-        c = Compose([a, b, a, b], unpack_items=True)
-        self.assertEqual(c([("", ""), ("t", "t")]), [("abab", "a2b2a2b2"), ("tabab", "ta2b2a2b2")])
+        transforms = [a, b, a, b]
+        data = [("", ""), ("t", "t")]
+        expected = [("abab", "a2b2a2b2"), ("tabab", "ta2b2a2b2")]
+        self.assertEqual(Compose(transforms, unpack_items=True)(data), expected)
+        self.assertEqual(Compose.execute(data, transforms, unpack_items=True), expected)
 
     def test_list_dict_compose_no_map(self):
         def a(d):  # transform to handle dict data
@@ -119,10 +140,16 @@ def c(d):  # transform to handle dict data
                 di["c"] += 1
             return d
 
-        transforms = Compose([a, a, b, c, c], map_items=False)
-        value = transforms({"a": 0, "b": 0, "c": 0})
+        transforms = [a, a, b, c, c]
+        data = {"a": 0, "b": 0, "c": 0}
+        expected = {"a": 2, "b": 1, "c": 2}
+        value = Compose(transforms, map_items=False)(data)
         for item in value:
-            self.assertDictEqual(item, {"a": 2, "b": 1, "c": 2})
+            self.assertDictEqual(item, expected)
+        value = Compose.execute(data, transforms, map_items=False)
+        for item in value:
+            self.assertDictEqual(item, expected)
+
 
     def test_random_compose(self):
         class _Acc(Randomizable):
@@ -220,5 +247,106 @@ def test_backwards_compatible_imports(self):
         from monai.transforms.compose import MapTransform, RandomizableTransform, Transform  # noqa: F401
 
 
+TEST_COMPOSE_EXECUTE_TEST_CASES = [
+    [None, tuple()],
+    [None, (Rotate(np.pi/8),)],
+    [None, (Flip(0), Flip(1), Rotate90(1), Zoom(0.8), NormalizeIntensity())],
+    [('a',), (Rotated(('a',), np.pi/8),)],
+]
+
+
+class TestComposeExecute(unittest.TestCase):
+
+    @parameterized.expand(TEST_COMPOSE_EXECUTE_TEST_CASES)
+    def test_compose_execute_equivalence(self, keys, pipeline):
+
+        if keys is None:
+            data = torch.unsqueeze(torch.tensor(np.arange(24*32).reshape(24, 32)), axis=0)
+        else:
+            data = {}
+            for i_k, k in enumerate(keys):
+                data[k] = torch.unsqueeze(torch.tensor(np.arange(24*32)).reshape(24, 32) + i_k * 768,
+                                          axis=0)
+
+        expected = Compose(deepcopy(pipeline))(data)
+
+        for cutoff in range(len(pipeline)):
+
+            c = Compose(deepcopy(pipeline))
+            actual = c(c(data, end=cutoff), start=cutoff)
+            if isinstance(actual, dict):
+                for k in actual.keys():
+                    self.assertTrue(torch.allclose(expected[k], actual[k]))
+            else:
+                self.assertTrue(torch.allclose(expected, actual))
+
+            p = deepcopy(pipeline)
+            actual = Compose.execute(
+                Compose.execute(data, p, start=0, end=cutoff), p, start=cutoff)
+            if isinstance(actual, dict):
+                for k in actual.keys():
+                    self.assertTrue(torch.allclose(expected[k], actual[k]))
+            else:
+                self.assertTrue(torch.allclose(expected, actual))
+
+
+class TestOps:
+
+    @staticmethod
+    def concat(value):
+        def _inner(data):
+            return data + value
+
+        return _inner
+
+    @staticmethod
+    def concatd(value):
+        def _inner(data):
+            return {k: v + value for k, v in data.items()}
+
+        return _inner
+
+    @staticmethod
+    def concata(value):
+        def _inner(data1, data2):
+            return data1 + value, data2 + value
+
+        return _inner
+
+
+TEST_COMPOSE_EXECUTE_FLAG_TEST_CASES = [
+    [{}, ("",), (TestOps.concat('a'), TestOps.concat('b'))],
+    [{"unpack_items": True}, ("x", "y"), (TestOps.concat('a'), TestOps.concat('b'))],
+    [{"map_items": False}, {"x": "1", "y": "2"}, (TestOps.concatd('a'), TestOps.concatd('b'))],
+    [{"unpack_items": True, "map_items": False}, ("x", "y"), (TestOps.concata('a'), TestOps.concata('b'))],
+]
+
+
+class TestComposeExecuteWithFlags(unittest.TestCase):
+
+    @parameterized.expand(TEST_COMPOSE_EXECUTE_FLAG_TEST_CASES)
+    def test_compose_execute_equivalence_with_flags(self, flags, data, pipeline):
+        expected = Compose(pipeline, **flags)(data)
+
+        for cutoff in range(len(pipeline)):
+
+            c = Compose(deepcopy(pipeline), **flags)
+            actual = c(c(data, end=cutoff), start=cutoff)
+            if isinstance(actual, dict):
+                for k in actual.keys():
+                    self.assertEqual(expected[k], actual[k])
+            else:
+                self.assertTrue(expected, actual)
+
+            p = deepcopy(pipeline)
+            actual = Compose.execute(
+                Compose.execute(data, p, start=0, end=cutoff, **flags), p, start=cutoff, **flags)
+            if isinstance(actual, dict):
+                for k in actual.keys():
+                    self.assertTrue(expected[k], actual[k])
+            else:
+                self.assertTrue(expected, actual)
+
+
 if __name__ == "__main__":
     unittest.main()