Utilities¶
Configurations¶
- class monai.config.deviceconfig.IgniteInfo[source]¶
Config information of the PyTorch ignite package.
- monai.config.deviceconfig.get_system_info()[source]¶
Get system info as an ordered dictionary.
- Return type
OrderedDict
- monai.config.deviceconfig.print_config(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]¶
Print the package versions to file.
- Parameters
file – print() text stream file. Defaults to sys.stdout.
- monai.config.deviceconfig.print_debug_info(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]¶
Print config (installed dependencies, etc.) and system info for debugging.
- Parameters
file – print() text stream file. Defaults to sys.stdout.
- Return type
None
Module utils¶
- exception monai.utils.module.InvalidPyTorchVersionError(required_version, name)[source]¶
Raised when called function or method requires a more recent PyTorch version than that installed.
- exception monai.utils.module.OptionalImportError[source]¶
Could not import APIs from an optional dependency.
- monai.utils.module.damerau_levenshtein_distance(s1, s2)[source]¶
Calculates the Damerau–Levenshtein distance between two strings for spelling correction. https://en.wikipedia.org/wiki/Damerau–Levenshtein_distance
- monai.utils.module.exact_version(the_module, version_str='')[source]¶
Returns True if the module’s __version__ matches version_str
- Return type
bool
- monai.utils.module.export(modname)[source]¶
Make the decorated object a member of the named module. This will also add the object under its aliases if it has a __aliases__ member, thus this decorator should be before the alias decorator to pick up those names. Alias names which conflict with package names or existing members will be ignored.
- monai.utils.module.get_package_version(dep_name, default='NOT INSTALLED or UNKNOWN VERSION.')[source]¶
Try to load package and get version. If not found, return default.
- monai.utils.module.get_torch_version_tuple()[source]¶
- Returns
tuple of ints represents the pytorch major/minor version.
- monai.utils.module.load_submodules(basemod, load_all=True, exclude_pattern='(.*[tT]est.*)|(_.*)')[source]¶
Traverse the source of the module structure starting with module basemod, loading all packages plus all files if load_all is True, excluding anything whose name matches exclude_pattern.
- monai.utils.module.look_up_option(opt_str, supported, default='no_default')[source]¶
Look up the option in the supported collection and return the matched item. Raise a value error possibly with a guess of the closest match.
- Parameters
opt_str – The option string or Enum to look up.
supported (
Collection
) – The collection of supported options, it can be list, tuple, set, dict, or Enum.default – If it is given, this method will return default when opt_str is not found, instead of raising a ValueError. Otherwise, it defaults to “no_default”, so that the method may raise a ValueError.
Examples:
from enum import Enum from monai.utils import look_up_option class Color(Enum): RED = "red" BLUE = "blue" look_up_option("red", Color) # <Color.RED: 'red'> look_up_option(Color.RED, Color) # <Color.RED: 'red'> look_up_option("read", Color) # ValueError: By 'read', did you mean 'red'? # 'read' is not a valid option. # Available options are {'blue', 'red'}. look_up_option("red", {"red", "blue"}) # "red"
Adapted from https://github.com/NifTK/NiftyNet/blob/v0.6.0/niftynet/utilities/util_common.py#L249
- monai.utils.module.min_version(the_module, min_version_str='')[source]¶
Convert version strings into tuples of int and compare them.
Returns True if the module’s version is greater or equal to the ‘min_version’. When min_version_str is not provided, it always returns True.
- Return type
bool
- monai.utils.module.optional_import(module, version='', version_checker=<function min_version>, name='', descriptor='{}', version_args=None, allow_namespace_pkg=False)[source]¶
Imports an optional module specified by module string. Any importing related exceptions will be stored, and exceptions raise lazily when attempting to use the failed-to-import module.
- Parameters
module (
str
) – name of the module to be imported.version (
str
) – version string used by the version_checker.version_checker (
Callable
[…,bool
]) – a callable to check the module version, Defaults to monai.utils.min_version.name (
str
) – a non-module attribute (such as method/class) to import from the imported module.descriptor (
str
) – a format string for the final error message when using a not imported module.version_args – additional parameters to the version checker.
allow_namespace_pkg (
bool
) – whether importing a namespace package is allowed. Defaults to False.
- Return type
Tuple
[Any
,bool
]- Returns
The imported module and a boolean flag indicating whether the import is successful.
Examples:
>>> torch, flag = optional_import('torch', '1.1') >>> print(torch, flag) <module 'torch' from 'python/lib/python3.6/site-packages/torch/__init__.py'> True >>> the_module, flag = optional_import('unknown_module') >>> print(flag) False >>> the_module.method # trying to access a module which is not imported OptionalImportError: import unknown_module (No module named 'unknown_module'). >>> torch, flag = optional_import('torch', '42', exact_version) >>> torch.nn # trying to access a module for which there isn't a proper version imported OptionalImportError: import torch (requires version '42' by 'exact_version'). >>> conv, flag = optional_import('torch.nn.functional', '1.0', name='conv1d') >>> print(conv) <built-in method conv1d of type object at 0x11a49eac0> >>> conv, flag = optional_import('torch.nn.functional', '42', name='conv1d') >>> conv() # trying to use a function from the not successfully imported module (due to unmatched version) OptionalImportError: from torch.nn.functional import conv1d (requires version '42' by 'min_version').
- monai.utils.module.pytorch_after(major, minor, patch=0, current_ver_string=None)[source]¶
Compute whether the current pytorch version is after or equal to the specified version. The current system pytorch version is determined by torch.__version__ or via system environment variable PYTORCH_VER.
- Parameters
major – major version number to be compared with
minor – minor version number to be compared with
patch – patch version number to be compared with
current_ver_string – if None, torch.__version__ will be used.
- Return type
bool
- Returns
True if the current pytorch version is greater than or equal to the specified version.
- monai.utils.module.require_pkg(pkg_name, version='', version_checker=<function min_version>, raise_error=True)[source]¶
Decorator function to check the required package installation.
- Parameters
pkg_name (
str
) – required package name, like: “itk”, “nibabel”, etc.version (
str
) – required version string used by the version_checker.version_checker (
Callable
[…,bool
]) – a callable to check the module version, defaults to monai.utils.min_version.raise_error (
bool
) – if True, raise OptionalImportError error if the required package is not installed or the version doesn’t match requirement, if False, print the error in a warning.
Aliases¶
This module is written for configurable workflow, not currently in use.
- monai.utils.aliases.alias(*names)[source]¶
Stores the decorated function or class in the global aliases table under the given names and as the __aliases__ member of the decorated object. This new member will contain all alias names declared for that object.
- monai.utils.aliases.resolve_name(name)[source]¶
Search for the declaration (function or class) with the given name. This will first search the list of aliases to see if it was declared with this aliased name, then search treating name as a fully qualified name, then search the loaded modules for one having a declaration with the given name. If no declaration is found, raise ValueError.
- Raises
ValueError – When the module is not found.
ValueError – When the module does not have the specified member.
ValueError – When multiple modules with the declaration name are found.
ValueError – When no module with the specified member is found.
Misc¶
- monai.utils.misc.copy_to_device(obj, device, non_blocking=True, verbose=False)[source]¶
Copy object or tuple/list/dictionary of objects to
device
.- Parameters
obj (
Any
) – object or tuple/list/dictionary of objects to move todevice
.device (
Union
[str
,device
,None
]) – moveobj
to this device. Can be a string (e.g.,cpu
,cuda
,cuda:0
, etc.) or of typetorch.device
.non_blocking (
bool
) – when True, moves data to device asynchronously if possible, e.g., moving CPU Tensors with pinned memory to CUDA devices.verbose (
bool
) – when True, will print a warning for any elements of incompatible type not copied todevice
.
- Return type
Any
- Returns
- Same as input, copied to
device
where possible. Original input will be unchanged.
- Same as input, copied to
- monai.utils.misc.ensure_tuple_rep(tup, dim)[source]¶
Returns a copy of tup with dim values by either shortened or duplicated input.
- Raises
ValueError – When
tup
is a sequence andtup
length is notdim
.
Examples:
>>> ensure_tuple_rep(1, 3) (1, 1, 1) >>> ensure_tuple_rep(None, 3) (None, None, None) >>> ensure_tuple_rep('test', 3) ('test', 'test', 'test') >>> ensure_tuple_rep([1, 2, 3], 3) (1, 2, 3) >>> ensure_tuple_rep(range(3), 3) (0, 1, 2) >>> ensure_tuple_rep([1, 2], 3) ValueError: Sequence must have length 3, got length 2.
- Return type
Tuple
[Any
, …]
- monai.utils.misc.ensure_tuple_size(tup, dim, pad_val=0)[source]¶
Returns a copy of tup with dim values by either shortened or padded with pad_val as necessary.
- Return type
Tuple
[Any
, …]
- monai.utils.misc.fall_back_tuple(user_provided, default, func=<function <lambda>>)[source]¶
Refine user_provided according to the default, and returns as a validated tuple.
The validation is done for each element in user_provided using func. If func(user_provided[idx]) returns False, the corresponding default[idx] will be used as the fallback.
Typically used when user_provided is a tuple of window size provided by the user, default is defined by data, this function returns an updated user_provided with its non-positive components replaced by the corresponding components from default.
- Parameters
user_provided (
Any
) – item to be validated.default (
Union
[Sequence
,ndarray
]) – a sequence used to provided the fallbacks.func (
Callable
) – a Callable to validate every components of user_provided.
Examples:
>>> fall_back_tuple((1, 2), (32, 32)) (1, 2) >>> fall_back_tuple(None, (32, 32)) (32, 32) >>> fall_back_tuple((-1, 10), (32, 32)) (32, 10) >>> fall_back_tuple((-1, None), (32, 32)) (32, 32) >>> fall_back_tuple((1, None), (32, 32)) (1, 32) >>> fall_back_tuple(0, (32, 32)) (32, 32) >>> fall_back_tuple(range(3), (32, 64, 48)) (32, 1, 2) >>> fall_back_tuple([0], (32, 32)) ValueError: Sequence must have length 2, got length 1.
- Return type
Tuple
[Any
, …]
- monai.utils.misc.first(iterable, default=None)[source]¶
Returns the first item in the given iterable or default if empty, meaningful mostly with ‘for’ expressions.
- monai.utils.misc.has_option(obj, keywords)[source]¶
Return a boolean indicating whether the given callable obj has the keywords in its signature.
- Return type
bool
- monai.utils.misc.is_module_ver_at_least(module, version)[source]¶
Determine if a module’s version is at least equal to the given value.
- Parameters
module – imported module’s name, e.g., np or torch.
version – required version, given as a tuple, e.g., (1, 8, 0).
- Returns
True if module is the given version or newer.
- monai.utils.misc.issequenceiterable(obj)[source]¶
Determine if the object is an iterable sequence and is not a string.
- Return type
bool
- monai.utils.misc.list_to_dict(items)[source]¶
To convert a list of “key=value” pairs into a dictionary. For examples: items: [“a=1”, “b=2”, “c=3”], return: {“a”: “1”, “b”: “2”, “c”: “3”}. If no “=” in the pair, use None as the value, for example: [“a”], return: {“a”: None}. Note that it will remove the blanks around keys and values.
- monai.utils.misc.progress_bar(index, count, desc=None, bar_len=30, newline=False)[source]¶
print a progress bar to track some time consuming task.
- Parameters
index (
int
) – current status in progress.count (
int
) – total steps of the progress.desc (
Optional
[str
]) – description of the progress bar, if not None, show before the progress bar.bar_len (
int
) – the total length of the bar on screen, default is 30 char.newline (
bool
) – whether to print in a new line for every index.
- Return type
None
- monai.utils.misc.set_determinism(seed=4294967295, use_deterministic_algorithms=None, additional_settings=None)[source]¶
Set random seed for modules to enable or disable deterministic training.
- Parameters
seed (
Optional
[int
]) – the random seed to use, default is np.iinfo(np.int32).max. It is recommended to set a large seed, i.e. a number that has a good balance of 0 and 1 bits. Avoid having many 0 bits in the seed. if set to None, will disable deterministic training.use_deterministic_algorithms (
Optional
[bool
]) – Set whether PyTorch operations must use “deterministic” algorithms.additional_settings (
Union
[Sequence
[Callable
[[int
],Any
]],Callable
[[int
],Any
],None
]) – additional settings that need to set random seed.
- Return type
None
NVTX Annotations¶
Decorators and context managers for NVIDIA Tools Extension to profile MONAI components
- class monai.utils.nvtx.Range(name=None, methods=None, append_method_name=None)[source]¶
A decorator and context manager for NVIDIA Tools Extension (NVTX) Range for profiling. When used as a decorator it encloses a specific method of the object with an NVTX Range. When used as a context manager, it encloses the runtime context (created by with statement) with an NVTX Range.
- Parameters
name (
Optional
[str
]) – the name to be associated to the rangemethods (
Union
[str
,Tuple
[str
, …],None
]) – (only when used as decorator) the name of a method (or a list of the name of the methods) to be wrapped by NVTX range. If None (default), the method(s) will be inferred based on the object’s type for various MONAI components, such as Networks, Losses, Functions, Transforms, and Datasets. Otherwise, it look up predefined methods: “forward”, “__call__”, “__next__”, “__getitem__”append_method_name (
Optional
[bool
]) – if append the name of the methods to be decorated to the range’s name If None (default), it appends the method’s name only if we are annotating more than one method.
Profiling¶
- class monai.utils.profiling.PerfContext[source]¶
Context manager for tracking how much time is spent within context blocks. This uses time.perf_counter to accumulate the total amount of time in seconds in the attribute total_time over however many context blocks the object is used in.
- monai.utils.profiling.torch_profiler_full(func)[source]¶
A decorator which will run the torch profiler for the decorated function, printing the results in full. Note: Enforces a gpu sync point which could slow down pipelines.
Deprecated¶
- monai.utils.deprecate_utils.deprecated(since=None, removed=None, msg_suffix='', version_val='0.8.0+0.g3915492.dirty')[source]¶
Marks a function or class as deprecated. If since is given this should be a version at or earlier than the current version and states at what version of the definition was marked as deprecated. If removed is given this can be any version and marks when the definition was removed.
When the decorated definition is called, that is when the function is called or the class instantiated, a DeprecationWarning is issued if since is given and the current version is at or later than that given. a DeprecatedError exception is instead raised if removed is given and the current version is at or later than that, or if neither since nor removed is provided.
The relevant docstring of the deprecating function should also be updated accordingly, using the Sphinx directives such as .. versionchanged:: version and .. deprecated:: version. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
- Parameters
since (
Optional
[str
]) – version at which the definition was marked deprecated but not removed.removed (
Optional
[str
]) – version at which the definition was removed and no longer usable.msg_suffix (
str
) – message appended to warning/exception detailing reasons for deprecation and what to use instead.version_val (
str
) – (used for testing) version to compare since and removed against, default is MONAI version.
- Returns
Decorated definition which warns or raises exception when used
- monai.utils.deprecate_utils.deprecated_arg(name, since=None, removed=None, msg_suffix='', version_val='0.8.0+0.g3915492.dirty', new_name=None)[source]¶
Marks a particular named argument of a callable as deprecated. The same conditions for since and removed as described in the deprecated decorator.
When the decorated definition is called, that is when the function is called or the class instantiated with args, a DeprecationWarning is issued if since is given and the current version is at or later than that given. a DeprecatedError exception is instead raised if removed is given and the current version is at or later than that, or if neither since nor removed is provided.
The relevant docstring of the deprecating function should also be updated accordingly, using the Sphinx directives such as .. versionchanged:: version and .. deprecated:: version. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
In the current implementation type annotations are not preserved.
- Parameters
name – name of position or keyword argument to mark as deprecated.
since (
Optional
[str
]) – version at which the argument was marked deprecated but not removed.removed (
Optional
[str
]) – version at which the argument was removed and no longer usable.msg_suffix (
str
) – message appended to warning/exception detailing reasons for deprecation and what to use instead.version_val (
str
) – (used for testing) version to compare since and removed against, default is MONAI version.new_name (
Optional
[str
]) – name of position or keyword argument to replace the deprecated argument.
- Returns
Decorated callable which warns or raises exception when deprecated argument used.
Type conversion¶
- monai.utils.type_conversion.convert_data_type(data, output_type=None, device=None, dtype=None, wrap_sequence=False)[source]¶
Convert to torch.Tensor/np.ndarray from torch.Tensor/np.ndarray/float/int etc.
- Parameters
data (
Any
) – data to be convertedoutput_type (
Optional
[type
]) – torch.Tensor or np.ndarray (if blank, unchanged)device (
Optional
[device
]) – if output is torch.Tensor, select device (if blank, unchanged)dtype (
Union
[dtype
,type
,None
,dtype
]) – dtype of output data. Converted to correct library type (e.g., np.float32 is converted to torch.float32 if output type is torch.Tensor). If left blank, it remains unchanged.wrap_sequence (
bool
) – if False, then lists will recursively call this function. E.g., [1, 2] -> [array(1), array(2)]. If True, then [1, 2] -> array([1, 2]).
- Return type
Tuple
[Union
[ndarray
,Tensor
],type
,Optional
[device
]]- Returns
modified data, orig_type, orig_device
Note
When both output_type and dtype are specified with different backend (e.g., torch.Tensor and np.float32), the output_type will be used as the primary type, for example:
>>> convert_data_type(1, torch.Tensor, dtype=np.float32) (1.0, <class 'torch.Tensor'>, None)
- monai.utils.type_conversion.convert_to_cupy(data, dtype, wrap_sequence=False)[source]¶
Utility to convert the input data to a cupy array. If passing a dictionary, list or tuple, recursively check every item and convert it to cupy array.
- Parameters
data –
input data can be PyTorch Tensor, numpy array, cupy array, list, dictionary, int, float, bool, str, etc. Tensor, numpy array, cupy array, float, int, bool are converted to cupy arrays
for dictionary, list or tuple, convert every item to a numpy array if applicable.
dtype – target data type when converting to Cupy array.
wrap_sequence (
bool
) – if False, then lists will recursively call this function. E.g., [1, 2] -> [array(1), array(2)]. If True, then [1, 2] -> array([1, 2]).
- monai.utils.type_conversion.convert_to_dst_type(src, dst, dtype=None, wrap_sequence=False)[source]¶
Convert source data to the same data type and device as the destination data. If dst is an instance of torch.Tensor or its subclass, convert src to torch.Tensor with the same data type as dst, if dst is an instance of numpy.ndarray or its subclass, convert to numpy.ndarray with the same data type as dst, otherwise, convert to the type of dst directly.
- Parameters
src (
Any
) – source data to convert type.dst (
Union
[ndarray
,Tensor
]) – destination data that convert to the same data type as it.dtype (
Union
[dtype
,type
,None
,dtype
]) – an optional argument if the target dtype is different from the original dst’s data type.wrap_sequence (
bool
) – if False, then lists will recursively call this function. E.g., [1, 2] -> [array(1), array(2)]. If True, then [1, 2] -> array([1, 2]).
See also
- Return type
Tuple
[Union
[ndarray
,Tensor
],type
,Optional
[device
]]
- monai.utils.type_conversion.convert_to_numpy(data, dtype=None, wrap_sequence=False)[source]¶
Utility to convert the input data to a numpy array. If passing a dictionary, list or tuple, recursively check every item and convert it to numpy array.
- Parameters
data – input data can be PyTorch Tensor, numpy array, list, dictionary, int, float, bool, str, etc. will convert Tensor, Numpy array, float, int, bool to numpy arrays, strings and objects keep the original. for dictionary, list or tuple, convert every item to a numpy array if applicable.
dtype (
Union
[dtype
,type
,None
]) – target data type when converting to numpy array.wrap_sequence (
bool
) – if False, then lists will recursively call this function. E.g., [1, 2] -> [array(1), array(2)]. If True, then [1, 2] -> array([1, 2]).
- monai.utils.type_conversion.convert_to_tensor(data, dtype=None, device=None, wrap_sequence=False)[source]¶
Utility to convert the input data to a PyTorch Tensor. If passing a dictionary, list or tuple, recursively check every item and convert it to PyTorch Tensor.
- Parameters
data – input data can be PyTorch Tensor, numpy array, list, dictionary, int, float, bool, str, etc. will convert Tensor, Numpy array, float, int, bool to Tensor, strings and objects keep the original. for dictionary, list or tuple, convert every item to a Tensor if applicable.
dtype (
Optional
[dtype
]) – target data type to when converting to Tensor.device (
Optional
[device
]) – target device to put the converted Tensor data.wrap_sequence (
bool
) – if False, then lists will recursively call this function. E.g., [1, 2] -> [tensor(1), tensor(2)]. If True, then [1, 2] -> tensor([1, 2]).
- monai.utils.type_conversion.dtype_numpy_to_torch(dtype)[source]¶
Convert a numpy dtype to its torch equivalent.
- monai.utils.type_conversion.dtype_torch_to_numpy(dtype)[source]¶
Convert a torch dtype to its numpy equivalent.