Configuration

OTX configurable parameters and helper utilities.

This module contains base elements that make up OTX ConfigurableParameters, as well as a collection of helper functions to interact with them.

The configuration helper module can be imported as otx_config_helper and implements the following:

This module contains the configuration helper functions.

These can be used to create, convert or interact with OTX configuration objects or dictionaries, yaml strings or yaml files representing those objects.

otx.api.configuration.helper.config_to_bytes(config: ConfigurableParameters) → bytes

Converts ConfigurableParameters to bytes.

Args:

config: configurable parameters

Retruns:

JSON in bytes

otx.api.configuration.helper.convert(config: ConfigurableParameters, target: Type[ConvertTypeVar], enum_to_str: bool = False, id_to_str: bool = False, values_only: bool = False) → ConvertTypeVar

Convert a configuration object to either a yaml string, a dictionary or an OmegaConf DictConfig object.

Args:

config (ConfigurableParameters): ConfigurableParameters object to convert target (Type[ConvertTypeVar]): target type to convert to. Options are [str, dict, DictConfig] enum_to_str (bool) : Boolean specifying whether to convert enums within the config

to their string representation. For conversion to yaml, enums are automatically converted and this option is disregarded.

id_to_str (bool): True to convert the id of the configurable parameters to a string

representation, False to leave it as an ID object

values_only (bool): True to keep only the parameter values, and remove all meta

data from the target output

Raises:

ValueError: if an unsupported conversion target is supplied

Returns:

ConvertTypeVar: Result of the conversion, the configuration specified in config in the

representation specified in target

otx.api.configuration.helper.create(input_config: Union[str, DictConfig, dict]) → ConfigurableParameters

Create a configuration object from a yaml string, yaml file path, dictionary or OmegaConf DictConfig object.

Args:

input_config: yaml string, dictionary, DictConfig or filepath

describing a configuration.

Returns:

ConfigurableParameters object

otx.api.configuration.helper.substitute_values(config: ConfigurableParameters, value_input: Union[str, DictConfig, dict, ConfigurableParameters], allow_missing_values: bool = False)

Substitutes values from value_input into the config object.

The structures of value_input and config have to match in order for the values to be substituted correctly.

Values are substituted in place.

Args:

config (ConfigurableParameters): ConfigurableParameter object to substitute values into. value_input (Union[str, DictConfig, dict, ConfigurableParameters]): ConfigurableParameters (either in object,

dict, yaml or DictConfig representation) to take the values to be substituted from.

allow_missing_values (bool): True to allow missing values in the configuration,

i.e. if a value is found in value_input, but not in config, it will silently be ignored. If set to False, an AttributeError will be raised. Defaults to False.

otx.api.configuration.helper.substitute_values_for_lifecycle(config: ConfigurableParameters, value_input: ConfigurableParameters, model_lifecycle: Union[ModelLifecycle, Sequence[ModelLifecycle]], allow_missing_values: bool = True)

Substitutes values from value_input into the config object.

The structures of value_input and config have to match in order for the values to be substituted correctly. If the argument model_lifecycle is provided, only parameters that affect the specified phase in the model lifecycle will be substituted.

Values are substituted in place.

Args:

config (ConfigurableParameters): ConfigurableParameter object to substitute values into value_input (ConfigurableParameters): ConfigurableParameters to take the values to be substituted

from.

model_lifecycle (Union[ModelLifecycle, Sequence[ModelLifecycle]]): Phase or list of phases in the

model lifecycle to carry out the substitution for. For example, if model_lifecycle = ModelLifecycle.INFERENCE is passed, only parameters that affect inference will be updated, and the rest of the parameters will remain untouched.

allow_missing_values (bool): True to allow missing values in the configuration,

i.e. if a value is found in value_input, but not in config, it will silently be ignored. If set to False, an AttributeError will be raised. Defaults to True.

otx.api.configuration.helper.validate(config: ParameterGroup) → bool

Validate a configuration object.

Args:

config: Configuration to validate

Returns:

True if config is valid

class otx.api.configuration.Action(value)

Bases: Enum

This Enum represents the allowed actions that UI rules can dictate on configuration parameters.

DISABLE_EDITING = 4

ENABLE_EDITING = 3

HIDE = 1

SHOW = 2

class otx.api.configuration.ConfigurableEnum(value)

Bases: Enum

This class is used as the basis for defining selectable configurable parameters in the OTX API.

Enums reflecting selectable options should inherit from thisclass.

classmethod get_class_info() → dict

Creates a dictionary representation of the ConfigurableEnum.

This includes the name of the enum and the (name, value) pairs representing its members.

Returns:

dict: Dictionary representation of the ConfigurableEnum.

classmethod get_names() → List[str]

Returns a list of names that can be used to index the Enum.

classmethod get_values() → List[str]

Returns a list of values that can be used to index the Enum.

class otx.api.configuration.ConfigurableParameters(header: str, description: str = 'Default parameter group description', visible_in_ui: bool = True, *, id: Optional[Union[str, ID]] = ID())

Bases: ParameterGroup

Base class representing a generic set of configurable parameters.

A ConfigurableParameters instance is essentially a parameter group with an id attached to it, so that it can be uniquely identified in the repositories.

Attributes:

id (ID): ID that uniquely identifies the ConfigurableParameters type (ConfigElementType): Type of the ConfigurableParameters

id: ID

type: ConfigElementType

class otx.api.configuration.DefaultModelParameters(visible_in_ui: bool = True, header: str = 'Default model hyper parameters', learning_parameters: _LearningParameters = _Nothing.NOTHING, *, id: Optional[Union[str, ID]] = ID(), description: str = 'Default model hyper parameter section description')

Bases: ConfigurableParameters

Configuration element representing a the default set of hyper parameters for a model.

Attributes:

header (str): Name of parameter group description (str): User friendly string describing what the ModelConfig represents, that will be displayed in

the UI.

description: str

header: str

class otx.api.configuration.ModelLifecycle(value)

Bases: Enum

This Enum represents the different stages in the ModelLifecycle.

It is used by configuration parameters to indicate in which stage of the model lifecycle the parameter takes effect. Selecting a stage early in the lifecycle implies that all downstream stages are affected as well (e.g. if this is set to ModelLifecycle.TRAINING, it is assumed that inference and testing are also impacted).

Currently the following stages are possible: ARCHITECTURE - Select this stage if the parameter modifies the model architecture, such that the most recently

trained weights cannot directly by used for the next training round due to a model topology mismatch. For example, a parameter model_depth that controls the number of downsampling steps in a UNet model should have this stage set.

TRAINING - Select this stage if the parameter is likely to change the outcome of the training process. For example,

the parameter learning_rate should have this stage set.

INFERENCE - Select this stage if the parameter changes the result of inference. For example, a parameter

probability_threshold that controls the threshold for binary classification should have this stage set.

TESTING - Select this stage if the parameter changes the outcome of the evaluation process. For example, a parameter

‘test_metric` that controls which metric to use for testing does not change training or inference results, but does affect the final evaluation of the model. Therefore, it should have this stage set.

NONE - Select this stage if the parameter is non-functional, for example if it only impacts training speed but

should not change the training outcome. For example, a parameter num_workers that controls the number of threads used in a dataloader should have this stage set.

ARCHITECTURE = 2

INFERENCE = 4

NONE = 1

TESTING = 5

TRAINING = 3

class otx.api.configuration.NullUIRules(operator: Union[str, Operator] = Operator.AND, action: Union[str, Action] = Action.DISABLE_EDITING, type: ConfigElementType = ConfigElementType.UI_RULES, rules: List[Union[Rule, UIRules]] = _Nothing.NOTHING)

Bases: UIRules

This class represents an empty, unset UIRules element.

rules: List[Union[Rule, UIRules]]

class otx.api.configuration.Operator(value)

Bases: Enum

This Enum represents the allowed operators for use in constructing UI rules for configuration parameters.

These operators can be used to disable a configuration parameter, conditional on the value of another parameter.

AND = 5

EQUAL_TO = 2

GREATER_THAN = 4

LESS_THAN = 3

NOT = 1

OR = 6

XOR = 7

class otx.api.configuration.Rule(parameter: Union[str, List[str]], value: Union[int, str, float, bool], operator: Union[str, Operator] = Operator.EQUAL_TO, type: ConfigElementType = ConfigElementType.RULE)

Bases: object

This class represents a operator applied to the value of the configurable parameter parameter.

The parameter for which the rule should be evaluated is identified by name, or by a list of names representing the attribute path to the parameter in case of a nested configuration.

operator: Operator

parameter: Union[str, List[str]]

to_dict(enum_to_str: bool = True) → dict

Method to serialize a Rule instance to its dictionary representation.

Args:

enum_to_str (bool): Set to True to convert Enum instances to their string representation

Returns:

dict: dictionary representation of the Rule object for which this method is called

type: ConfigElementType

value: Union[int, str, float, bool]

class otx.api.configuration.UIRules(operator: Union[str, Operator] = Operator.AND, action: Union[str, Action] = Action.DISABLE_EDITING, type: ConfigElementType = ConfigElementType.UI_RULES, *, rules: List[Union[Rule, UIRules]])

Bases: object

This class allows the combination of ExposureRules using boolean logic.

The class can be set as an attribute of a configurable parameter. If the rules (combined according to the operator) evaluate to True, the corresponding`action` will be taken in the UI.

If UIRules are nested, only the action of the outermost UIRule will be considered.

action: Action

add_rule(rule: Union[Rule, UIRules])

Adds rule.

operator: Operator

rules: List[Union[Rule, UIRules]]

to_dict(enum_to_str: bool = True) → dict

Method to serialize an UIRules instance to its dictionary representation.

Applies recursion to convert nested rules, if applicable.

Args:

enum_to_str: Set to True to convert Enum instances to their

string representation

Returns:

dictionary representation of the UIRules object for which this method is called

type: ConfigElementType