3482 add run API for common training, evaluation and inference

docs/requirements.txt

@@ -25,3 +25,5 @@ mlflow
 tensorboardX
 imagecodecs; platform_system == "Linux"
 tifffile; platform_system == "Linux"
+pyyaml
+fire

docs/source/bundle.rst

@@ -32,3 +32,7 @@ Model Bundle
 ---------------
 .. autoclass:: ConfigParser
     :members:
+
+`Scripts`
+---------
+.. autofunction:: run

docs/source/installation.md

@@ -190,10 +190,9 @@ Since MONAI v0.2.0, the extras syntax such as `pip install 'monai[nibabel]'` is
 
 - The options are
 ```
-[nibabel, skimage, pillow, tensorboard, gdown, ignite, torchvision, itk, tqdm, lmdb, psutil, cucim, openslide, pandas, einops, transformers, mlflow, matplotlib, tensorboardX, tifffile, imagecodecs]
+[nibabel, skimage, pillow, tensorboard, gdown, ignite, torchvision, itk, tqdm, lmdb, psutil, cucim, openslide, pandas, einops, transformers, mlflow, matplotlib, tensorboardX, tifffile, imagecodecs, pyyaml, fire]
 ```
 which correspond to `nibabel`, `scikit-image`, `pillow`, `tensorboard`,
-`gdown`, `pytorch-ignite`, `torchvision`, `itk`, `tqdm`, `lmdb`, `psutil`, `cucim`, `openslide-python`, `pandas`, `einops`, `transformers`, `mlflow`, `matplotlib`, `tensorboardX`,
-`tifffile`, `imagecodecs`, respectively.
+`gdown`, `pytorch-ignite`, `torchvision`, `itk`, `tqdm`, `lmdb`, `psutil`, `cucim`, `openslide-python`, `pandas`, `einops`, `transformers`, `mlflow`, `matplotlib`, `tensorboardX`, `tifffile`, `imagecodecs`, `pyyaml`, `fire`, respectively.
 
 - `pip install 'monai[all]'` installs all the optional dependencies.

environment-dev.yml

@@ -42,6 +42,8 @@ dependencies:
   - transformers
   - mlflow
   - tensorboardX
+  - pyyaml
+  - fire
   - pip
   - pip:
     # pip for itk as conda-forge version only up to v5.1

monai/__init__.py

@@ -39,7 +39,7 @@
 
 # handlers_* have some external decorators the users may not have installed
 # *.so files and folder "_C" may not exist when the cpp extensions are not compiled
-excludes = "(^(monai.handlers))|((\\.so)$)|(^(monai._C))"
+excludes = "(^(monai.handlers))|(^(monai.bundle))|((\\.so)$)|(^(monai._C))"
 
 # load directory modules only, skip loading individual files
 load_submodules(sys.modules[__name__], False, exclude_pattern=excludes)

monai/bundle/__init__.py

@@ -12,3 +12,5 @@
 from .config_item import ComponentLocator, ConfigComponent, ConfigExpression, ConfigItem, Instantiable
 from .config_parser import ConfigParser
 from .reference_resolver import ReferenceResolver
+from .scripts import run
+from .utils import EXPR_KEY, ID_REF_KEY, ID_SEP_KEY, MACRO_KEY

monai/bundle/__main__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 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.
+
+
+from monai.bundle.scripts import run
+
+if __name__ == "__main__":
+    from monai.utils import optional_import
+
+    fire, _ = optional_import("fire")
+    fire.Fire()

monai/bundle/config_item.py

@@ -17,6 +17,7 @@
 from importlib import import_module
 from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
 
+from monai.bundle.utils import EXPR_KEY
 from monai.utils import ensure_tuple, instantiate
 
 __all__ = ["ComponentLocator", "ConfigItem", "ConfigExpression", "ConfigComponent"]
@@ -160,25 +161,24 @@ def __repr__(self) -> str:
 
 class ConfigComponent(ConfigItem, Instantiable):
     """
-    Subclass of :py:class:`monai.apps.ConfigItem`, this class uses a dictionary with string keys to
+    Subclass of :py:class:`monai.bundle.ConfigItem`, this class uses a dictionary with string keys to
     represent a component of `class` or `function` and supports instantiation.
 
-    Currently, four special keys (strings surrounded by ``<>``) are defined and interpreted beyond the regular literals:
+    Currently, two special keys (strings surrounded by ``_``) are defined and interpreted beyond the regular literals:
 
         - class or function identifier of the python module, specified by one of the two keys.
-            - ``"<name>"``: indicates build-in python classes or functions such as "LoadImageDict".
-            - ``"<path>"``: full module name, such as "monai.transforms.LoadImageDict".
-        - ``"<args>"``: input arguments to the python module.
-        - ``"<disabled>"``: a flag to indicate whether to skip the instantiation.
+            - ``"_target_"``: indicates build-in python classes or functions such as "LoadImageDict",
+                or full module name, such as "monai.transforms.LoadImageDict".
+        - ``"_disabled_"``: a flag to indicate whether to skip the instantiation.
+
+    Other fields in the config content are input arguments to the python module.
 
     .. code-block:: python
 
         locator = ComponentLocator(excludes=["modules_to_exclude"])
         config = {
-            "<name>": "LoadImaged",
-            "<args>": {
-                "keys": ["image", "label"]
-            }
+            "_target_": "LoadImaged",
+            "keys": ["image", "label"]
         }
 
         configer = ConfigComponent(config, id="test", locator=locator)
@@ -195,6 +195,8 @@ class ConfigComponent(ConfigItem, Instantiable):
 
     """
 
+    non_arg_keys = {"_target_", "_disabled_"}
+
     def __init__(
         self,
         config: Any,
@@ -214,52 +216,45 @@ def is_instantiable(config: Any) -> bool:
             config: input config content to check.
 
         """
-        return isinstance(config, Mapping) and ("<path>" in config or "<name>" in config)
+        return isinstance(config, Mapping) and "_target_" in config
 
     def resolve_module_name(self):
         """
         Resolve the target module name from current config content.
-        The config content must have ``"<path>"`` or ``"<name>"``.
-        When both are specified, ``"<path>"`` will be used.
+        The config content must have ``"_target_"`` key.
 
         """
         config = dict(self.get_config())
-        path = config.get("<path>")
-        if path is not None:
-            if not isinstance(path, str):
-                raise ValueError(f"'<path>' must be a string, but got: {path}.")
-            if "<name>" in config:
-                warnings.warn(f"both '<path>' and '<name>', default to use '<path>': {path}.")
-            return path
-
-        name = config.get("<name>")
-        if not isinstance(name, str):
-            raise ValueError("must provide a string for `<path>` or `<name>` of target component to instantiate.")
+        target = config.get("_target_")
+        if not isinstance(target, str):
+            raise ValueError("must provide a string for the `_target_` of component to instantiate.")
 
-        module = self.locator.get_component_module_name(name)
+        module = self.locator.get_component_module_name(target)
         if module is None:
-            raise ModuleNotFoundError(f"can not find component '{name}' in {self.locator.MOD_START} modules.")
+            # target is the full module name, no need to parse
+            return target
+
         if isinstance(module, list):
             warnings.warn(
-                f"there are more than 1 component have name `{name}`: {module}, use the first one `{module[0]}."
-                f" if want to use others, please set its module path in `<path>` directly."
+                f"there are more than 1 component have name `{target}`: {module}, use the first one `{module[0]}."
+                f" if want to use others, please set its full module path in `_target_` directly."
             )
             module = module[0]
-        return f"{module}.{name}"
+        return f"{module}.{target}"
 
     def resolve_args(self):
         """
         Utility function used in `instantiate()` to resolve the arguments from current config content.
 
         """
-        return self.get_config().get("<args>", {})
+        return {k: v for k, v in self.get_config().items() if k not in self.non_arg_keys}
 
     def is_disabled(self) -> bool:  # type: ignore
         """
         Utility function used in `instantiate()` to check whether to skip the instantiation.
 
         """
-        _is_disabled = self.get_config().get("<disabled>", False)
+        _is_disabled = self.get_config().get("_disabled_", False)
         return _is_disabled.lower().strip() == "true" if isinstance(_is_disabled, str) else bool(_is_disabled)
 
     def instantiate(self, **kwargs) -> object:  # type: ignore
@@ -283,7 +278,7 @@ def instantiate(self, **kwargs) -> object:  # type: ignore
 
 class ConfigExpression(ConfigItem):
     """
-    Subclass of :py:class:`monai.apps.ConfigItem`, the `ConfigItem` represents an executable expression
+    Subclass of :py:class:`monai.bundle.ConfigItem`, the `ConfigItem` represents an executable expression
     (execute based on ``eval()``).
 
     See also:
@@ -308,7 +303,7 @@ class ConfigExpression(ConfigItem):
 
     """
 
-    prefix = "$"
+    prefix = EXPR_KEY
     run_eval = False if os.environ.get("MONAI_EVAL_EXPR", "1") == "0" else True
 
     def __init__(self, config: Any, id: str = "", globals: Optional[Dict] = None) -> None: