Model Bundle#

Config Item#

class monai.bundle.Instantiable[source]#

Base class for an instantiable object.

abstract instantiate(*args, **kwargs)[source]#

Instantiate the target component and return the instance.

Return type

object

abstract is_disabled(*args, **kwargs)[source]#

Return a boolean flag to indicate whether the object should be instantiated.

Return type

bool

class monai.bundle.ComponentLocator(excludes=None)[source]#

Scan all the available classes and functions in the MONAI package and map them with the module paths in a table. It’s used to locate the module path for provided component name.

Parameters

excludes (Union[str, Sequence[str], None]) – if any string of the excludes exists in the full module name, don’t import this module.

get_component_module_name(name)[source]#

Get the full module name of the class or function with specified name. If target component name exists in multiple packages or modules, return a list of full module names.

Parameters

name (str) – name of the expected class or function.

Return type

Union[List[str], str, None]

class monai.bundle.ConfigComponent(config, id='', locator=None, excludes=None)[source]#

Subclass of monai.bundle.ConfigItem, this class uses a dictionary with string keys to represent a component of class or function and supports instantiation.

Currently, three special keys (strings surrounded by _) are defined and interpreted beyond the regular literals:

  • class or function identifier of the python module, specified by "_target_", indicating a build-in python class or function such as "LoadImageDict", or a full module name, such as "monai.transforms.LoadImageDict".

  • "_requires_" (optional): specifies reference IDs (string starts with "@") or ConfigExpression of the dependencies for this ConfigComponent object. These dependencies will be evaluated/instantiated before this object is instantiated. It is useful when the component doesn’t explicitly depend on the other ConfigItems via its arguments, but requires the dependencies to be instantiated/evaluated beforehand.

  • "_disabled_" (optional): a flag to indicate whether to skip the instantiation.

  • "_desc_" (optional): free text descriptions of the component for code readability.

Other fields in the config content are input arguments to the python module.

from monai.bundle import ComponentLocator, ConfigComponent

locator = ComponentLocator(excludes=["modules_to_exclude"])
config = {
    "_target_": "LoadImaged",
    "keys": ["image", "label"]
}

configer = ConfigComponent(config, id="test", locator=locator)
image_loader = configer.instantiate()
print(image_loader)  # <monai.transforms.io.dictionary.LoadImaged object at 0x7fba7ad1ee50>
Parameters
  • config (Any) – content of a config item.

  • id (str) – name of the current config item, defaults to empty string.

  • locator (Optional[ComponentLocator]) – a ComponentLocator to convert a module name string into the actual python module. if None, a ComponentLocator(excludes=excludes) will be used.

  • excludes (Union[str, Sequence[str], None]) – if locator is None, create a new ComponentLocator with excludes. See also: monai.bundle.ComponentLocator.

instantiate(**kwargs)[source]#

Instantiate component based on self.config content. The target component must be a class or a function, otherwise, return None.

Parameters

kwargs – args to override / add the config args when instantiation.

Return type

object

is_disabled()[source]#

Utility function used in instantiate() to check whether to skip the instantiation.

Return type

bool

static is_instantiable(config)[source]#

Check whether this config represents a class or function that is to be instantiated.

Parameters

config (Any) – input config content to check.

Return type

bool

resolve_args()[source]#

Utility function used in instantiate() to resolve the arguments from current config content.

resolve_module_name()[source]#

Resolve the target module name from current config content. The config content must have "_target_" key.

class monai.bundle.ConfigExpression(config, id='', globals=None)[source]#

Subclass of monai.bundle.ConfigItem, the ConfigItem represents an executable expression (execute based on eval(), or import the module to the globals if it’s an import statement).

For example:

import monai
from monai.bundle import ConfigExpression

config = "$monai.__version__"
expression = ConfigExpression(config, id="test", globals={"monai": monai})
print(expression.evaluate())
Parameters
  • config (Any) – content of a config item.

  • id (str) – name of current config item, defaults to empty string.

  • globals (Optional[Dict]) – additional global context to evaluate the string.

evaluate(globals=None, locals=None)[source]#

Execute the current config content and return the result if it is expression, based on Python eval(). For more details: https://docs.python.org/3/library/functions.html#eval.

Parameters
  • globals (Optional[Dict]) – besides self.globals, other global symbols used in the expression at runtime.

  • locals (Optional[Dict]) – besides globals, may also have some local symbols used in the expression at runtime.

classmethod is_expression(config)[source]#

Check whether the config is an executable expression string. Currently, a string starts with "$" character is interpreted as an expression.

Parameters

config (Union[Dict, List, str]) – input config content to check.

Return type

bool

classmethod is_import_statement(config)[source]#

Check whether the config is an import statement (a special case of expression).

Parameters

config (Union[Dict, List, str]) – input config content to check.

Return type

bool

class monai.bundle.ConfigItem(config, id='')[source]#

Basic data structure to represent a configuration item.

A ConfigItem instance can optionally have a string id, so that other items can refer to it. It has a build-in config property to store the configuration object.

Parameters
  • config (Any) – content of a config item, can be objects of any types, a configuration resolver may interpret the content to generate a configuration object.

  • id (str) – name of the current config item, defaults to empty string.

get_config()[source]#

Get the config content of current config item.

get_id()[source]#

Get the ID name of current config item, useful to identify config items during parsing.

Return type

str

update_config(config)[source]#

Replace the content of self.config with new config. A typical usage is to modify the initial config content at runtime.

Parameters

config (Any) – content of a ConfigItem.

Reference Resolver#

class monai.bundle.ReferenceResolver(items=None)[source]#

Utility class to manage a set of ConfigItem and resolve the references between them.

This class maintains a set of ConfigItem objects and their associated IDs. The IDs must be unique within this set. A string in ConfigItem starting with @ will be treated as a reference to other ConfigItem objects by ID. Since ConfigItem may have a nested dictionary or list structure, the reference string may also contain a # character to refer to a substructure by key indexing for a dictionary or integer indexing for a list.

In this class, resolving references is essentially substitution of the reference strings with the corresponding python objects. A typical workflow of resolving references is as follows:

  • Add multiple ConfigItem objects to the ReferenceResolver by add_item().

  • Call get_resolved_content() to automatically resolve the references. This is done (recursively) by:
    • Convert the items to objects, for those do not have references to other items.
      • If it is instantiable, instantiate it and cache the class instance in resolved_content.

      • If it is an expression, evaluate it and save the value in resolved_content.

    • Substitute the reference strings with the corresponding objects.

Parameters

items (Optional[Sequence[ConfigItem]]) – ConfigItem``s to resolve, this could be added later with ``add_item().

add_item(item)[source]#

Add a ConfigItem to the resolver.

Parameters

item (ConfigItem) – a ConfigItem.

classmethod find_refs_in_config(config, id, refs=None)[source]#

Recursively search all the content of input config item to get the ids of references. References mean: the IDs of other config items ("@XXX" in this config item), or the sub-item in the config is instantiable, or the sub-item in the config is expression. For dict and list, recursively check the sub-items.

Parameters
  • config – input config content to search.

  • id (str) – ID name for the input config item.

  • refs (Optional[Dict[str, int]]) – dict of the ID name and count of found references, default to None.

Return type

Dict[str, int]

get_item(id, resolve=False, **kwargs)[source]#

Get the ConfigItem by id.

If resolve=True, the returned item will be resolved, that is, all the reference strings are substituted by the corresponding ConfigItem objects.

Parameters
  • id (str) – id of the expected config item.

  • resolve (bool) – whether to resolve the item if it is not resolved, default to False.

  • kwargs – keyword arguments to pass to _resolve_one_item(). Currently support instantiate and eval_expr. Both are defaulting to True.

get_resolved_content(id, **kwargs)[source]#

Get the resolved ConfigItem by id.

Parameters
  • id (str) – id name of the expected item.

  • kwargs – keyword arguments to pass to _resolve_one_item(). Currently support instantiate, eval_expr and default. instantiate and eval_expr are defaulting to True, default is the target config item if the id is not in the config content, must be a ConfigItem object.

classmethod match_refs_pattern(value)[source]#

Match regular expression for the input string to find the references. The reference string starts with "@", like: "@XXX#YYY#ZZZ".

Parameters

value (str) – input value to match regular expression.

Return type

Dict[str, int]

reset()[source]#

Clear all the added ConfigItem and all the resolved content.

classmethod update_config_with_refs(config, id, refs=None)[source]#

With all the references in refs, update the input config content with references and return the new config.

Parameters
  • config – input config content to update.

  • id (str) – ID name for the input config.

  • refs (Optional[Dict]) – all the referring content with ids, default to None.

classmethod update_refs_pattern(value, refs)[source]#

Match regular expression for the input string to update content with the references. The reference part starts with "@", like: "@XXX#YYY#ZZZ". References dictionary must contain the referring IDs as keys.

Parameters
  • value (str) – input value to match regular expression.

  • refs (Dict) – all the referring components with ids as keys, default to None.

Return type

str

Config Parser#

class monai.bundle.ConfigParser(config=None, excludes=None, globals=None)[source]#

The primary configuration parser. It traverses a structured config (in the form of nested Python dict or list), creates ConfigItem, and assign unique IDs according to the structures.

This class provides convenient access to the set of ConfigItem of the config by ID. A typical workflow of config parsing is as follows:

  • Initialize ConfigParser with the config source.

  • Call get_parsed_content() to get expected component with id.

from monai.bundle import ConfigParser

config = {
    "my_dims": 2,
    "dims_1": "$@my_dims + 1",
    "my_xform": {"_target_": "LoadImage"},
    "my_net": {"_target_": "BasicUNet", "spatial_dims": "@dims_1", "in_channels": 1, "out_channels": 4},
    "trainer": {"_target_": "SupervisedTrainer", "network": "@my_net", "preprocessing": "@my_xform"}
}
# in the example $@my_dims + 1 is an expression, which adds 1 to the value of @my_dims
parser = ConfigParser(config)

# get/set configuration content, the set method should happen before calling parse()
print(parser["my_net"]["in_channels"])  # original input channels 1
parser["my_net"]["in_channels"] = 4  # change input channels to 4
print(parser["my_net"]["in_channels"])

# instantiate the network component
parser.parse(True)
net = parser.get_parsed_content("my_net", instantiate=True)
print(net)

# also support to get the configuration content of parsed `ConfigItem`
trainer = parser.get_parsed_content("trainer", instantiate=False)
print(trainer)
Parameters
  • config (Optional[Any]) – input config source to parse.

  • excludes (Union[str, Sequence[str], None]) – when importing modules to instantiate components, excluding components from modules specified in excludes.

  • globals (Union[Dict[str, Any], None, bool]) – pre-import packages as global variables to ConfigExpression, so that expressions, for example, "$monai.data.list_data_collate" can use monai modules. The current supported globals and alias names are {"monai": "monai", "torch": "torch", "np": "numpy", "numpy": "numpy"}. These are MONAI’s minimal dependencies. Additional packages could be included with globals={“itk”: “itk”}. Set it to False to disable self.globals module importing.

See also

classmethod export_config_file(config, filepath, fmt='json', **kwargs)[source]#

Export the config content to the specified file path (currently support JSON and YAML files).

Parameters
  • config (Dict) – source config content to export.

  • filepath (Union[str, PathLike]) – target file path to save.

  • fmt – format of config content, currently support "json" and "yaml".

  • kwargs – other arguments for json.dump or yaml.safe_dump, depends on the file format.

get(id='', default=None)[source]#

Get the config by id.

Parameters
  • id (str) – id to specify the expected position. See also __getitem__().

  • default (Optional[Any]) – default value to return if the specified id is invalid.

get_parsed_content(id='', **kwargs)[source]#

Get the parsed result of ConfigItem with the specified id.

  • If the item is ConfigComponent and instantiate=True, the result is the instance.

  • If the item is ConfigExpression and eval_expr=True, the result is the evaluated output.

  • Else, the result is the configuration content of ConfigItem.

Parameters
  • id (str) – id of the ConfigItem, "#" in id are interpreted as special characters to go one level further into the nested structures. Use digits indexing from “0” for list or other strings for dict. For example: "xform#5", "net#channels". "" indicates the entire self.config.

  • kwargs – additional keyword arguments to be passed to _resolve_one_item. Currently support lazy (whether to retain the current config cache, default to True), instantiate (whether to instantiate the ConfigComponent, default to True) and eval_expr (whether to evaluate the ConfigExpression, default to True), default (the default config item if the id is not in the config content).

classmethod load_config_file(filepath, **kwargs)[source]#

Load config file with specified file path (currently support JSON and YAML files).

Parameters
  • filepath (Union[str, PathLike]) – path of target file to load, supported postfixes: .json, .yml, .yaml.

  • kwargs – other arguments for json.load or `yaml.safe_load, depends on the file format.

classmethod load_config_files(files, **kwargs)[source]#

Load config files into a single config dict. The latter config file in the list will override or add the former config file. "#" in the config keys are interpreted as special characters to go one level further into the nested structures.

Parameters
  • files (Union[str, PathLike, Sequence[Union[str, PathLike]], dict]) – path of target files to load, supported postfixes: .json, .yml, .yaml.

  • kwargs – other arguments for json.load or `yaml.safe_load, depends on the file format.

Return type

Dict

parse(reset=True)[source]#

Recursively resolve self.config to replace the macro tokens with target content. Then recursively parse the config source, add every item as ConfigItem to the reference resolver.

Parameters

reset (bool) – whether to reset the reference_resolver before parsing. Defaults to True.

read_config(f, **kwargs)[source]#

Read the config from specified JSON or YAML file. The config content in the self.config dictionary.

Parameters
  • f (Union[str, PathLike, Sequence[Union[str, PathLike]], Dict]) – filepath of the config file, the content must be a dictionary, if providing a list of files, wil merge the content of them. if providing a dictionary directly, use it as config.

  • kwargs – other arguments for json.load or yaml.safe_load, depends on the file format.

read_meta(f, **kwargs)[source]#

Read the metadata from specified JSON or YAML file. The metadata as a dictionary will be stored at self.config["_meta_"].

Parameters
  • f (Union[str, PathLike, Sequence[Union[str, PathLike]], Dict]) – filepath of the metadata file, the content must be a dictionary, if providing a list of files, will merge the content of them. if providing a dictionary directly, use it as metadata.

  • kwargs – other arguments for json.load or yaml.safe_load, depends on the file format.

resolve_macro_and_relative_ids()[source]#

Recursively resolve self.config to replace the relative ids with absolute ids, for example, @##A means A in the upper level. and replace the macro tokens with target content, The macro tokens are marked as starting with “%”, can be from another structured file, like: "%default_net", "%/data/config.json#net".

classmethod resolve_relative_ids(id, value)[source]#

To simplify the reference or macro tokens ID in the nested config content, it’s available to use relative ID name which starts with the ID_SEP_KEY, for example, “@#A” means A in the same level, @##A means A in the upper level. It resolves the relative ids to absolute ids. For example, if the input data is:

{
    "A": 1,
    "B": {"key": "@##A", "value1": 2, "value2": "%#value1", "value3": [3, 4, "@#1"]},
}

It will resolve B to {“key”: “@A”, “value1”: 2, “value2”: “%B#value1”, “value3”: [3, 4, “@B#value3#1”]}.

Parameters
  • id (str) – id name for current config item to compute relative id.

  • value (str) – input value to resolve relative ids.

Return type

str

set(config, id='', recursive=True)[source]#

Set config by id.

Parameters
  • config (Any) – config to set at location id.

  • id (str) – id to specify the expected position. See also __setitem__().

  • recursive (bool) – if the nested id doesn’t exist, whether to recursively create the nested items in the config. default to True. for the nested id, only support dict for the missing section.

classmethod split_path_id(src)[source]#

Split src string into two parts: a config file path and component id. The file path should end with (json|yaml|yml). The component id should be separated by # if it exists. If no path or no id, return “”.

Parameters

src (str) – source string to split.

Return type

Tuple[str, str]

update(pairs)[source]#

Set the id and the corresponding config content in pairs, see also __setitem__(). For example, parser.update({"train#epoch": 100, "train#lr": 0.02})

Parameters

pairs (Dict[str, Any]) – dictionary of id and config pairs.

Scripts#

monai.bundle.ckpt_export(net_id=None, filepath=None, ckpt_file=None, meta_file=None, config_file=None, key_in_ckpt=None, args_file=None, **override)[source]#

Export the model checkpoint to the given filepath with metadata and config included as JSON files.

Typical usage examples:

python -m monai.bundle ckpt_export network --filepath <export path> --ckpt_file <checkpoint path> ...
Parameters
  • net_id (Optional[str]) – ID name of the network component in the config, it must be torch.nn.Module.

  • filepath (Union[str, PathLike, None]) – filepath to export, if filename has no extension it becomes .ts.

  • ckpt_file (Optional[str]) – filepath of the model checkpoint to load.

  • meta_file (Union[str, Sequence[str], None]) – filepath of the metadata file, if it is a list of file paths, the content of them will be merged.

  • config_file (Union[str, Sequence[str], None]) – filepath of the config file to save in TorchScript model and extract network information, the saved key in the TorchScript model is the config filename without extension, and the saved config value is always serialized in JSON format no matter the original file format is JSON or YAML. it can be a single file or a list of files. if None, must be provided in args_file.

  • key_in_ckpt (Optional[str]) – for nested checkpoint like {“model”: XXX, “optimizer”: XXX, …}, specify the key of model weights. if not nested checkpoint, no need to set.

  • args_file (Optional[str]) – a JSON or YAML file to provide default values for meta_file, config_file, net_id and override pairs. so that the command line inputs can be simplified.

  • override – id-value pairs to override or add the corresponding config content. e.g. --_meta#network_data_format#inputs#image#num_channels 3.

monai.bundle.download(name=None, version=None, bundle_dir=None, source='github', repo='Project-MONAI/model-zoo/hosting_storage_v1', url=None, progress=True, args_file=None)[source]#

download bundle from the specified source or url. The bundle should be a zip file and it will be extracted after downloading. This function refers to: https://pytorch.org/docs/stable/_modules/torch/hub.html

Typical usage examples:

# Execute this module as a CLI entry, and download bundle from the model-zoo repo:
python -m monai.bundle download --name <bundle_name> --version "0.1.0" --bundle_dir "./"

# Execute this module as a CLI entry, and download bundle:
python -m monai.bundle download --name <bundle_name> --source "github" --repo "repo_owner/repo_name/release_tag"

# Execute this module as a CLI entry, and download bundle via URL:
python -m monai.bundle download --name <bundle_name> --url <url>

# Set default args of `run` in a JSON / YAML file, help to record and simplify the command line.
# Other args still can override the default args at runtime.
# The content of the JSON / YAML file is a dictionary. For example:
# {"name": "spleen", "bundle_dir": "download", "source": ""}
# then do the following command for downloading:
python -m monai.bundle download --args_file "args.json" --source "github"
Parameters
  • name (Optional[str]) – bundle name. If None and url is None, it must be provided in args_file. for example: “spleen_ct_segmentation”, “prostate_mri_anatomy” in the model-zoo: Project-MONAI/model-zoo.

  • version (Optional[str]) – version name of the target bundle to download, like: “0.1.0”.

  • bundle_dir (Union[str, PathLike, None]) – target directory to store the downloaded data. Default is bundle subfolder under torch.hub.get_dir().

  • source (str) – storage location name. This argument is used when url is None. “github” is currently the only supported value.

  • repo (str) – repo name. This argument is used when url is None. If source is “github”, it should be in the form of “repo_owner/repo_name/release_tag”.

  • url (Optional[str]) – url to download the data. If not None, data will be downloaded directly and source will not be checked. If name is None, filename is determined by monai.apps.utils._basename(url).

  • progress (bool) – whether to display a progress bar.

  • args_file (Optional[str]) – a JSON or YAML file to provide default values for all the args in this function. so that the command line inputs can be simplified.

monai.bundle.load(name, version=None, model_file=None, load_ts_module=False, bundle_dir=None, source='github', repo='Project-MONAI/model-zoo/hosting_storage_v1', progress=True, device=None, key_in_ckpt=None, config_files=(), net_name=None, **net_kwargs)[source]#

Load model weights or TorchScript module of a bundle.

Parameters
  • name (str) – bundle name, for example: “spleen_ct_segmentation”, “prostate_mri_anatomy” in the model-zoo: Project-MONAI/model-zoo.

  • version (Optional[str]) – version name of the target bundle to download, like: “0.1.0”.

  • model_file (Optional[str]) – the relative path of the model weights or TorchScript module within bundle. If None, “models/model.pt” or “models/model.ts” will be used.

  • load_ts_module (bool) – a flag to specify if loading the TorchScript module.

  • bundle_dir (Union[str, PathLike, None]) – directory the weights/TorchScript module will be loaded from. Default is bundle subfolder under torch.hub.get_dir().

  • source (str) – storage location name. This argument is used when model_file is not existing locally and need to be downloaded first. “github” is currently the only supported value.

  • repo (str) – repo name. This argument is used when model_file is not existing locally and need to be downloaded first. If source is “github”, it should be in the form of “repo_owner/repo_name/release_tag”.

  • progress (bool) – whether to display a progress bar when downloading.

  • device (Optional[str]) – target device of returned weights or module, if None, prefer to “cuda” if existing.

  • key_in_ckpt (Optional[str]) – for nested checkpoint like {“model”: XXX, “optimizer”: XXX, …}, specify the key of model weights. if not nested checkpoint, no need to set.

  • config_files (Sequence[str]) – extra filenames would be loaded. The argument only works when loading a TorchScript module, see _extra_files in torch.jit.load for more details.

  • net_name (Optional[str]) – if not None, a corresponding network will be instantiated and load the achieved weights. This argument only works when loading weights.

  • net_kwargs – other arguments that are used to instantiate the network class defined by net_name.

Returns

  1. If load_ts_module is False and net_name is None, return model weights.

  2. If load_ts_module is False and net_name is not None,

    return an instantiated network that loaded the weights.

  3. If load_ts_module is True, return a triple that include a TorchScript module,

    the corresponding metadata dict, and extra files dict. please check monai.data.load_net_with_metadata for more details.

monai.bundle.get_all_bundles_list(repo='Project-MONAI/model-zoo', tag='hosting_storage_v1', auth_token=None)[source]#

Get all bundles names (and the latest versions) that are stored in the release of specified repository with the provided tag. The default values of arguments correspond to the release of MONAI model zoo. In order to increase the rate limits of calling GIthub APIs, you can input your personal access token. Please check the following link for more details about rate limiting: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting

The following link shows how to create your personal access token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Parameters
  • repo (str) – it should be in the form of “repo_owner/repo_name/”.

  • tag (str) – the tag name of the release.

  • auth_token (Optional[str]) – github personal access token.

Returns

a list of tuple in the form of (bundle name, latest version).

monai.bundle.get_bundle_info(bundle_name, version=None, repo='Project-MONAI/model-zoo', tag='hosting_storage_v1', auth_token=None)[source]#

Get all information (include “id”, “name”, “size”, “download_count”, “browser_download_url”, “created_at”, “updated_at”) of a bundle with the specified bundle name and version. In order to increase the rate limits of calling GIthub APIs, you can input your personal access token. Please check the following link for more details about rate limiting: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting

The following link shows how to create your personal access token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Parameters
  • bundle_name (str) – bundle name.

  • version (Optional[str]) – version name of the target bundle, if None, the latest version will be used.

  • repo (str) – it should be in the form of “repo_owner/repo_name/”.

  • tag (str) – the tag name of the release.

  • auth_token (Optional[str]) – github personal access token.

Returns

a dictionary that contains the bundle’s information.

monai.bundle.get_bundle_versions(bundle_name, repo='Project-MONAI/model-zoo', tag='hosting_storage_v1', auth_token=None)[source]#

Get the latest version, as well as all existing versions of a bundle that is stored in the release of specified repository with the provided tag. In order to increase the rate limits of calling GIthub APIs, you can input your personal access token. Please check the following link for more details about rate limiting: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting

The following link shows how to create your personal access token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Parameters
  • bundle_name (str) – bundle name.

  • repo (str) – it should be in the form of “repo_owner/repo_name/”.

  • tag (str) – the tag name of the release.

  • auth_token (Optional[str]) – github personal access token.

Returns

a dictionary that contains the latest version and all versions of a bundle.

monai.bundle.run(runner_id=None, meta_file=None, config_file=None, logging_file=None, tracking=None, args_file=None, **override)[source]#

Specify meta_file and config_file to run monai bundle components and workflows.

Typical usage examples:

# Execute this module as a CLI entry:
python -m monai.bundle run training --meta_file <meta path> --config_file <config path>

# Override config values at runtime by specifying the component id and its new value:
python -m monai.bundle run training --net#input_chns 1 ...

# Override config values with another config file `/path/to/another.json`:
python -m monai.bundle run evaluating --net %/path/to/another.json ...

# Override config values with part content of another config file:
python -m monai.bundle run training --net %/data/other.json#net_arg ...

# Set default args of `run` in a JSON / YAML file, help to record and simplify the command line.
# Other args still can override the default args at runtime:
python -m monai.bundle run --args_file "/workspace/data/args.json" --config_file <config path>
Parameters
  • runner_id (Union[str, Sequence[str], None]) – ID name of the expected config expression to run, can also be a list of IDs to run in order.

  • meta_file (Union[str, Sequence[str], None]) – filepath of the metadata file, if it is a list of file paths, the content of them will be merged.

  • config_file (Union[str, Sequence[str], None]) – filepath of the config file, if None, must be provided in args_file. if it is a list of file paths, the content of them will be merged.

  • logging_file (Optional[str]) – config file for logging module in the program, default to None. for more details: https://docs.python.org/3/library/logging.config.html#logging.config.fileConfig.

  • tracking (Union[str, dict, None]) –

    enable the experiment tracking feature at runtime with optionally configurable and extensible. if “mlflow”, will add MLFlowHandler to the parsed bundle with default loggging settings, if other string, treat it as file path to load the logging settings, if dict, treat it as logging settings, otherwise, use all the default settings. will patch the target config content with tracking handlers and the top-level items of configs. example of customized settings:

    tracking = {
        "handlers_id": {
            "trainer": {"id": "train#trainer", "handlers": "train#handlers"},
            "validator": {"id": "evaluate#evaluator", "handlers": "evaluate#handlers"},
            "evaluator": {"id": "evaluator", "handlers": "handlers"},
        },
        "configs": {
            "tracking_uri": "<path>",
            "trainer": {
                "_target_": "MLFlowHandler",
                "tracking_uri": "@tracking_uri",
                "iteration_log": True,
                "output_transform": "$monai.handlers.from_engine(['loss'], first=True)",
            },
            "validator": {
                "_target_": "MLFlowHandler", "tracking_uri": "@tracking_uri", "iteration_log": False,
            },
            "evaluator": {
                "_target_": "MLFlowHandler", "tracking_uri": "@tracking_uri", "iteration_log": False,
            },
        },
    },
    

  • args_file (Optional[str]) – a JSON or YAML file to provide default values for runner_id, meta_file, config_file, logging, and override pairs. so that the command line inputs can be simplified.

  • override – id-value pairs to override or add the corresponding config content. e.g. --net#input_chns 42.

monai.bundle.verify_metadata(meta_file=None, filepath=None, create_dir=None, hash_val=None, hash_type=None, args_file=None, **kwargs)[source]#

Verify the provided metadata file based on the predefined schema. metadata content must contain the schema field for the URL of schema file to download. The schema standard follows: http://json-schema.org/.

Parameters
  • meta_file (Union[str, Sequence[str], None]) – filepath of the metadata file to verify, if None, must be provided in args_file. if it is a list of file paths, the content of them will be merged.

  • filepath (Union[str, PathLike, None]) – file path to store the downloaded schema.

  • create_dir (Optional[bool]) – whether to create directories if not existing, default to True.

  • hash_val (Optional[str]) – if not None, define the hash value to verify the downloaded schema file.

  • hash_type (Optional[str]) – if not None, define the hash type to verify the downloaded schema file. Defaults to “md5”.

  • args_file (Optional[str]) – a JSON or YAML file to provide default values for all the args in this function. so that the command line inputs can be simplified.

  • kwargs – other arguments for jsonschema.validate(). for more details: https://python-jsonschema.readthedocs.io/en/stable/validate/#jsonschema.validate.

monai.bundle.verify_net_in_out(net_id=None, meta_file=None, config_file=None, device=None, p=None, n=None, any=None, args_file=None, **override)[source]#

Verify the input and output data shape and data type of network defined in the metadata. Will test with fake Tensor data according to the required data shape in metadata.

Typical usage examples:

python -m monai.bundle verify_net_in_out network --meta_file <meta path> --config_file <config path>
Parameters
  • net_id (Optional[str]) – ID name of the network component to verify, it must be torch.nn.Module.

  • meta_file (Union[str, Sequence[str], None]) – filepath of the metadata file to get network args, if None, must be provided in args_file. if it is a list of file paths, the content of them will be merged.

  • config_file (Union[str, Sequence[str], None]) – filepath of the config file to get network definition, if None, must be provided in args_file. if it is a list of file paths, the content of them will be merged.

  • device (Optional[str]) – target device to run the network forward computation, if None, prefer to “cuda” if existing.

  • p (Optional[int]) – power factor to generate fake data shape if dim of expected shape is “x**p”, default to 1.

  • n (Optional[int]) – multiply factor to generate fake data shape if dim of expected shape is “x*n”, default to 1.

  • any (Optional[int]) – specified size to generate fake data shape if dim of expected shape is “*”, default to 1.

  • args_file (Optional[str]) – a JSON or YAML file to provide default values for net_id, meta_file, config_file, device, p, n, any, and override pairs. so that the command line inputs can be simplified.

  • override – id-value pairs to override or add the corresponding config content. e.g. --_meta#network_data_format#inputs#image#num_channels 3.

monai.bundle.init_bundle(bundle_dir, ckpt_file=None, network=None, dataset_license=False, metadata_str=None, inference_str=None)[source]#

Initialise a new bundle directory with some default configuration files and optionally network weights.

Typical usage example:

python -m monai.bundle init_bundle /path/to/bundle_dir network_ckpt.pt
Parameters
  • bundle_dir (Union[str, PathLike]) – directory name to create, must not exist but parent direct must exist

  • ckpt_file (Union[str, PathLike, None]) – optional checkpoint file to copy into bundle

  • network (Optional[Module]) – if given instead of ckpt_file this network’s weights will be stored in bundle

  • dataset_license (bool) – if True, a default license file called “data_license.txt” will be produced. This file is required if there are any license conditions stated for data your bundle uses.