lir.config package

class lir.config.ConfigParser[source]

Bases: ABC

Abstract base configuration parser class.

Each implementation should implement a custom parse() method which is dedicated to parsing a specific aspect, e.g. the configuration for setting up the numpy CSV writer.

static get_type_name(obj: Any) → str[source]

Return the fully qualified type name.

Parameters:

obj (Any) – Class or object with __module__ and __qualname__ attributes.

Returns:

Fully qualified name.

Return type:

str

abstractmethod parse(config: ConfigValue, output_dir: Path) → Any[source]

Parse a specific configuration section.

Parameters:

  • config (ConfigValue) – Configuration section to parse.

  • output_dir (Path) – Directory where produced outputs may be written.

Returns:

Object configured from config.

Return type:

Any

reference() → str[source]

Return the full class name that was used to initialize this parser.

By default, return the name of this class. In a subclass that was initialized with another class or function that does the actual work, the name of that class is returned.

Returns:

Fully qualified class name for this parser instance.

Return type:

str

class lir.config.ConfigValue(context: list[str], value: list[ConfigValue] | dict[str, ConfigValue] | int | float | bool | str | None)[source]

Bases: object

A wrapper for a configuration value and its context path.

A ConfigValue has two attributes: context contains the path in the original configuration that points to the current value, and value contains the actual configuration value. The value attribute may be one of the types allowed in YAML: dict, list, int, float, bool, str, or None.

This configuration value may be part of a bigger configuration tree. For example, consider:

level1:
  value1:
    a: 1
    b: 2
  value2:
    c: 3
    d: path/to/file
    e: message text

This YAML is parsed into a dictionary and the path level1.value1 leads to the value { "a": 1, "b": 2 }. In a ConfigValue object, this is represented as context path ["level1", "value1"] and value { "a": 1, "b": 2 }.

If the value is dictionary, its values are itself also ConfigValue objects. They can be obtained using the helper function pop_field(). When all is done, check_empty() will check that all values have been read.

Some examples for the use of ConfigValue:

from lir.config import ConfigValue, pop_field, check_is_empty

my_config_input = {
    'level1': {
        'value1': {
            'a': 1,
            'b': 2,
        },
        'value2': {
            'c': 3,
            'd': 'path/to/file',
            'e': 'message text',
        },
    },
}

root_config = ConfigValue.wrap([], my_config_input)
print(f'The context of root is: {root_config.context}')
print(f'The value of root is: {root_config.value}')
print(f'The unwrapped value of root is: {root_config.unwrap()}')

The context of root is: []
The value of root is: {'level1': ConfigValue(context=['level1'], value={'value1': ConfigValue(context=['level1', 'value1'], value={'a': ConfigValue(context=['level1', 'value1', 'a'], value=1), 'b': ConfigValue(context=['level1', 'value1', 'b'], value=2)}), 'value2': ConfigValue(context=['level1', 'value2'], value={'c': ConfigValue(context=['level1', 'value2', 'c'], value=3), 'd': ConfigValue(context=['level1', 'value2', 'd'], value='path/to/file'), 'e': ConfigValue(context=['level1', 'value2', 'e'], value='message text')})})}
The unwrapped value of root is: {'level1': {'value1': {'a': 1, 'b': 2}, 'value2': {'c': 3, 'd': 'path/to/file', 'e': 'message text'}}}

Example for the use of check_empty():

level1_config = pop_field(root_config, 'level1')
print(f'After "level1" is popped, the value of root is: {root_config.value}')

# We can call `check_is_empty()` to make sure that there are no values left.
check_is_empty(root_config)

print(f'The context of level1 is: {level1_config.context}')
print(f'The value of level1 is: {level1_config.value}')
print(f'The unwrapped value of level1 is: {level1_config.unwrap()}')

After "level1" is popped, the value of root is: {}
The context of level1 is: ['level1']
The value of level1 is: {'value1': ConfigValue(context=['level1', 'value1'], value={'a': ConfigValue(context=['level1', 'value1', 'a'], value=1), 'b': ConfigValue(context=['level1', 'value1', 'b'], value=2)}), 'value2': ConfigValue(context=['level1', 'value2'], value={'c': ConfigValue(context=['level1', 'value2', 'c'], value=3), 'd': ConfigValue(context=['level1', 'value2', 'd'], value='path/to/file'), 'e': ConfigValue(context=['level1', 'value2', 'e'], value='message text')})}
The unwrapped value of level1 is: {'value1': {'a': 1, 'b': 2}, 'value2': {'c': 3, 'd': 'path/to/file', 'e': 'message text'}}

Example for the use of with:

# use the `with` statement to automatically check that all fields are used
try:
    with pop_field(level1_config, 'value1') as value1_config:
        pop_field(value1_config, 'a')
except Exception as e:
    print(f'Exception thrown: {e}')

Exception thrown: level1.value1: unrecognized argument: b

More examples:

value2_config = pop_field(level1_config, 'value2')
print(f'The context of level1.value2 is: {value2_config.context}')
print(f'The value of level1.value2 is: {value2_config.value}')
print(f'The unwrapped value of level1.value2 is: {value2_config.unwrap()}')

The context of level1.value2 is: ['level1', 'value2']
The value of level1.value2 is: {'c': ConfigValue(context=['level1', 'value2', 'c'], value=3), 'd': ConfigValue(context=['level1', 'value2', 'd'], value='path/to/file'), 'e': ConfigValue(context=['level1', 'value2', 'e'], value='message text')}
The unwrapped value of level1.value2 is: {'c': 3, 'd': 'path/to/file', 'e': 'message text'}

Examples for the use of pop_field():

from pathlib import Path

# use `validate_type` to check that the type is as expected
c = pop_field(value2_config, 'c', validate_type=int)
print(f'The value of level1.value2.c is: {c}')

# use `validate` to cast types or call a function to otherwise process the value
d = pop_field(value2_config, 'd', validate=Path)
print(f'The value of level1.value2.d is: {d}')

# use `unwrap` to control whether the result should be unwrapped or not
e = pop_field(value2_config, 'e', unwrap=False)
print(f'The value of level1.value2.e is: {e}')

The value of level1.value2.c is: 3
The value of level1.value2.d is: path/to/file
The value of level1.value2.e is: ConfigValue(context=['level1', 'value2', 'e'], value='message text')
as_dict(message: str | None = None) → dict[source]

Return unwrapped dictionary or raise an error.

If this ConfigValue is a dictionary, unwrap it and return the result. Otherwise, raise an error.

Parameters:

message (str | None) – A custom error message.

clone(context: list[str] | None = None) → ConfigValue[source]

Create a cloned list with expanded nested context.

Parameters:

context (list[str] | None, optional) – Replacement context. If omitted, the current context is reused.

Returns:

Cloned and context-aware list.

Return type:

ConfigValue

context: list[str]

YAML path used for contextual error messages.

pop(field: str, default: Any = None, required: bool | None = None, validate: Callable[[Any], Any] | None = None, validate_type: type[Any] | None = None) → ConfigValue | None[source]

Validate and retrieve the value for a given field, after which it is removed from this configuration.

If the value of this ConfigValue is not a dict, an error is raised.

If the field exists, it is returned as a ConfigValue object.

If the field does not exist, and a default is provided, the default is returned, wrapped in a ConfigValue object.

If the field does not exist, it is optional, and no default is provided, None is returned.

Otherwise, the field does not exist, and it is required: an error is raised.

This method behaves similarly to pop_field(), except that its return value is wrapped in ConfigValue.

Parameters:

  • field (str) – Field name to retrieve.

  • default (Any, optional) – Value to return when field is absent.

  • required (bool | None, optional) – Whether to raise when the field is absent. Defaults to True when default is None.

  • validate (Callable[[Any], Any] | None, optional) – Validator function applied to the popped value. The output from the validation function is returned, in place of the original value.

  • validate_type (type[Any] | None, optional) – Check that the popped value is of this type, or raise a ValueError.

Returns:

Popped field value or default.

Return type:

ConfigValue

pop_field(field: str, default: Any = None, required: bool | None = None, validate: Callable[[Any], Any] | None = None, validate_type: type[Any] | None = None) → Any[source]

Validate and retrieve the value for a given field, after which it is removed from the configuration.

This method behaves similarly to pop(), except that it returns an unwrapped value.

Parameters:

  • field (str) – Field name to retrieve.

  • default (Any, optional) – Value to return when field is absent.

  • required (bool | None, optional) – Whether to raise when the field is absent. Defaults to True when default is None.

  • validate (Callable[[Any], Any] | None, optional) – Validator function applied to the popped value.

  • validate_type (type[Any] | None, optional) – Check that the popped value is of this type, or raise a ValueError.

Returns:

Popped field value or default.

Return type:

Any

unwrap() → list | dict | int | float | bool | str | None[source]

Obtain the value of this object.

If the value is a container, its contents are also stripped of its ConfigValue wrapper recursively.

Returns:

The value of this object.

Return type:

list | dict | int | float | bool | str | None

value: list[ConfigValue] | dict[str, ConfigValue] | int | float | bool | str | None

The actual configuration value.

static wrap(context: list[str], value: Sequence | Mapping | int | float | bool | str | None) → ConfigValue[source]

Wrap a value and all its nested values into ConfigValue objects, recursively.

Parameters:

  • context (list[str]) – Current YAML path.

  • value (Sequence | Mapping | float | int | str | None) – Value to expand recursively.

Returns:

The value wrapped into ConfigValue objects recursively.

Return type:

ConfigValue

class lir.config.GenericConfigParser(component_class: type[Any])[source]

Bases: ConfigParser

Return an instantiation of a class, initialized with the specified arguments.

Parameters:

component_class (type[Any]) – Class to instantiate from configuration values.

parse(config: ConfigValue, output_dir: Path) → Any[source]

Instantiate the configured component class.

Parameters:

  • config (ConfigValue) – Keyword arguments for class initialisation.

  • output_dir (Path) – Unused output directory argument required by the parser API.

Returns:

Instantiated object.

Return type:

Any

reference() → str[source]

Return the fully qualified name of the wrapped class.

Returns:

Fully qualified class name.

Return type:

str

class lir.config.GenericFunctionConfigParser(component_class: Callable)[source]

Bases: ConfigParser

Parser for callable functions or component classes.

Parameters:

component_class (Callable) – Callable that should be exposed by this parser.

parse(config: ConfigValue, output_dir: Path) → Callable[source]

Parse configuration into a callable.

Parameters:

  • config (ConfigValue) – Configuration section for validation context.

  • output_dir (Path) – Unused output directory argument required by the parser API.

Returns:

Resolved callable object.

Return type:

Callable

reference() → str[source]

Return the fully qualified name of the wrapped callable.

Returns:

Fully qualified callable name.

Return type:

str

exception lir.config.YamlParseError(config_context_path: list[str], message: str)[source]

Bases: ValueError

Error raised when parsing YAML configuration fails, mentioning specific YAML path.

Parameters:

  • config_context_path (list[str]) – Dot-path to the failing configuration node.

  • message (str) – Human-readable validation or parsing message.

lir.config.check_is_empty(config: ConfigValue, accept_keys: Sequence[str] | None = None) → None[source]

Ensure all defined expected arguments are parsed and warn about ignored arguments.

If any unexpected arguments remain, a YamlParseError is raised indicating the argument was unexpected and not taken into account (i.e. not parsed). This methodology ensures the user does not assume arguments are parsed that are in fact not recognized.

Parameters:

  • config (ConfigValue) – Configuration to validate for remaining keys.

  • accept_keys (Sequence[str] | None, optional) – Keys that may remain without raising an error.

Returns:

This function raises on invalid input and otherwise returns None.

Return type:

None

lir.config.config_parser(func: Callable[[ConfigValue, Path], Any] | None = None, /, reference: str | type[Any] | None = None) → Callable[source]

Wrap a parsing function in a ConfigParser object using a decorator.

The resulting ConfigParser instance exposes a parse() method, as required by the API. The body of the decorated function is executed when the parse() method is called.

This decorator can be used as follows:

@config_parser
def foo(config, config_context_path, output_dir):
    if "some_argument" not in config or "another_argument" not in config:
        raise YamlParseError(
            config_context_path,
            "a required argument is missing",
        )
    return Bar(config["some_argument"], config["another_argument"])

After decoration, foo is replaced by a ConfigParser instance whose parse() method executes the original function body. See the documentation of ConfigParser for the meaning of the arguments.

The annotated function will be the reference object that users will be referred to for documentation. If the annotation has a reference argument, that value will be used instead. The reference value may be a str or a Python object. Example of use:

@config_parser(reference=Bar)
def foo(config, config_context_path, output_dir):
    if "some_argument" not in config or "another_argument" not in config:
        raise YamlParseError(
            config_context_path,
            "a required argument is missing",
        )
    return Bar(config["some_argument"], config["another_argument"])
Parameters:

  • func (Callable[[ConfigValue, Path], Any] | None, optional) – Function to wrap as a config parser.

  • reference (str | Any | None, optional) – Explicit reference name or object used in generated metadata.

Returns:

Decorator result or wrapped ConfigParser implementation.

Return type:

Callable

lir.config.get_full_name(obj: type[Any] | Callable) → str[source]

Return the full name of an importable object.

from lir import FeatureData
print(get_full_name(FeatureData))
'lir.data.models.FeatureData'

This function does not yet handle type aliases.

Parameters:

obj (Any) – Importable object.

Returns:

Fully qualified object name.

Return type:

str

lir.config.pop_field(config: ConfigValue, field: str, default: Any = None, required: bool | None = None, validate: Callable[[Any], Any] | None = None, validate_type: type[Any] | None = None, unwrap: bool | None = None) → Any[source]

Validate and retrieve the value for a given field, after which it is removed from the configuration.

This is a legacy alternative for ConfigValue.pop() and ConfigValue.pop_field(), and may be deprecated in the future.

Parameters:

  • config (ConfigValue) – Configuration object to pop from.

  • field (str) – Field name to retrieve.

  • default (Any, optional) – Value to return when field is absent.

  • required (bool | None, optional) – Whether to raise when the field is absent. Defaults to True when default is None.

  • validate (Callable[[Any], Any] | None, optional) – Validator function applied to the popped value.

  • validate_type (type[Any] | None, optional) – Check that the popped value is of this type, or raise a ValueError.

  • unwrap (bool | None, optional) – Strip the popped value of its ConfigValue wrapper before returning it. Defaults to True if either validate or validate_type or default is provided, except if the default is a Config|Value. Defaults to False otherwise.

Returns:

Popped field value or default.

Return type:

Any

Submodules

lir.config.aggregation module

lir.config.aggregation.parse_aggregation(config: ConfigValue, output_dir: Path, context: list[str] | None = None) → Aggregation[source]

Parse a configuration section for output aggregation.

If config is a dictionary, the method property is the aggregation method that is looked up in the registry. Other properties are passed as parameters. If config is a str, then its value is the aggregation method, and it has no parameters.

Parameters:

  • config (ConfigValue) – The configuration as a dictionary or string.

  • output_dir (Path) – Output directory where derived artefacts are written.

  • context (list[str] | None, optional) – Context for error reporting when config is provided as a string.

Returns:

Parsed aggregation instance.

Return type:

Aggregation

lir.config.aggregation.parse_aggregations(config: ConfigValue, output_dir: Path) → list[Aggregation][source]

Parse a list of configurations for aggregation.

Parameters:

  • config (ConfigValue) – Configuration for a single aggregation or a list of aggregation configurations.

  • output_dir (Path) – Output directory for the aggregation instances.

Returns:

Parsed aggregation instances.

Return type:

list[Aggregation]

lir.config.data module

class lir.config.data.DataSetup(provider: DataProvider, strategy: DataStrategy, data_filter: Transformer | None)[source]

Bases: object

Data setup, consisting of three components: a data provider, a filter, and a strategy.

The filter is a Transformer that supports calling the apply() method without priorly calling fit(). Unlike in LR system pipelines, this transformer may change the number of instances in the dataset.

Parameters:
get_splits() → Iterable[tuple[InstanceData, InstanceData]][source]

Return the data in the form of one or more train/test splits.

This method follows three steps: - retrieve instances from the data provider; - pass them through the filter by calling its apply() method; - apply the data strategy to arrange them into one or more train/test splits.

Returns:

An iterator over tuples of train/test splits.

Return type:

Iterable[tuple[InstanceData, InstanceData]]

lir.config.data.data_provider(func: Callable[[ConfigValue, Path], ReturnType]) → Callable[source]

Wrap a parsing function in a ConfigParser object using a decorator.

The parse() method of the resulting ConfigParser instance returns a DataProvider object that is invoked when needed.

This decorator can be used as follows:

@data_provider
def foo(path: str, some_argument: int) -> InstanceData:
    with open(path) as f:
        ...
        return FeatureData(...)
Parameters:

func (Callable[[ContextAwareDict, Path], Any]) – Function to wrap as a config parser.

Returns:

Decorator result or wrapped ConfigParser implementation.

Return type:

Callable

lir.config.data.parse_data_provider(cfg: ConfigValue, output_path: Path) → DataProvider[source]

Instantiate specific implementation of DataProvider as configured.

The method field is parsed, which is expected to refer to a name in the registry. See for example lir.config.data_sources.synthesized_normal_binary or lir.config.data_sources.synthesized_normal_multiclass.

Data sources are provided under the data_sources key.

Parameters:

  • cfg (ConfigValue) – Data provider configuration.

  • output_path (Path) – Output path for created objects.

Returns:

Parsed data provider instance.

Return type:

DataProvider

lir.config.data.parse_data_setup(cfg: ConfigValue, output_path: Path) → DataSetup[source]

Parse data provider and data strategy from configuration.

The fields provider, filter and splits are parsed, which are expected to refer to specific implementations of DataProvider, Transformer and DataStrategy, respectively. See parse_data_provider, parse_module and parse_data_strategy for more information.

Parameters:

  • cfg (ConfigValue) – Configuration section containing provider and split strategy.

  • output_path (Path) – Output path for created objects.

Returns:

Parsed data provider, filter and strategy.

Return type:

DataSetup

lir.config.data.parse_data_strategy(cfg: ConfigValue, output_path: Path) → DataStrategy[source]

Instantiate specific implementation of DataStrategy as configured.

The strategy field is parsed, which is expected to refer to a name in the registry. See for example lir.data_setup.binary_cross_validation or lir.data_setup.binary_train_test_split.

Data setup configuration is provided under the data_setup key.

Parameters:

  • cfg (ConfigValue) – Data strategy configuration.

  • output_path (Path) – Output path for created objects.

Returns:

Parsed data strategy instance.

Return type:

DataStrategy

lir.config.experiment_strategies module

lir.config.experiment_strategies.parse_experiment_strategy(config: ConfigValue, output_path: Path) → Experiment[source]

Instantiate the corresponding experiment strategy class, e.g. for a single or grid run.

A corresponding Experiment class is returned.

Parameters:

  • config (ConfigValue) – Experiment strategy configuration.

  • output_path (Path) – Output path for experiment artefacts.

Returns:

Parsed experiment strategy instance.

Return type:

Experiment

lir.config.experiment_strategies.parse_experiments(cfg: ConfigValue, output_path: Path) → Mapping[str, Experiment][source]

Extract which Experiment to run as dictated in the configuration.

Parameters:

  • cfg (ConfigValue) – Configuration section describing experiments.

  • output_path (Path) – Filesystem path to the results directory.

Returns:

Mapping from experiment name to parsed experiment.

Return type:

Mapping[str, Experiment]

lir.config.lrsystem_architectures module

class lir.config.lrsystem_architectures.ParsedLRSystem(lrsystem: LRSystem, config: ConfigValue)[source]

Bases: LRSystem

Represent a given initialized LR system based on the provided configuration.

Parameters:

  • lrsystem (LRSystem) – Underlying LR system implementation.

  • config (ConfigValue) – Original LR system configuration.

apply(instances: InstanceData) → LLRData[source]

Apply the fitted LR system.

Parameters:

instances (InstanceData) – Instances to score.

Returns:

Computed likelihood-ratio data.

Return type:

LLRData

fit(instances: InstanceData) → Self[source]

Fit the LR system on instance data.

Parameters:

instances (InstanceData) – Training instances.

Returns:

This wrapper instance.

Return type:

Self

lir.config.lrsystem_architectures.augment_config(baseline_config: ConfigValue, hyperparameters: dict[str, HyperparameterOption]) → ConfigValue[source]

Parse an augmented LR system.

The LR system is parsed from a base configuration and a set of parameter substitutions that override parts of the base configuration. Results are written to a subdirectory of output_dir that is named by its parameter substitutions and prefixed by dirname_prefix.

Parameters:

  • baseline_config (ConfigValue) – Base LR system configuration.

  • hyperparameters (dict[str, HyperparameterOption]) – Hyperparameter substitutions overriding parts of the base configuration.

Returns:

Augmented LR system configuration.

Return type:

ConfigValue

lir.config.lrsystem_architectures.parse_default_pipeline(config: ConfigValue) → str[source]

Parse the intermediate output flag to determine the default pipeline method.

Parameters:

config (ConfigValue) – Configuration dictionary.

Returns:

Default method name ('logging_pipeline' or 'pipeline').

Return type:

str

lir.config.lrsystem_architectures.parse_lrsystem(config: ConfigValue, output_dir: Path) → ParsedLRSystem[source]

Determine and initialise corresponding LR system from configuration values.

LR systems are provided under the architectures key.

Parameters:

  • config (ConfigValue) – LR system configuration.

  • output_dir (Path) – Output directory for nested parser calls.

Returns:

Wrapper containing parsed LR system and source configuration.

Return type:

ParsedLRSystem

lir.config.metrics module

lir.config.metrics.parse_individual_metric(name: str, output_path: Path, context: list[str]) → Callable[[LLRData], float][source]

Parse one metric from the registry.

Parameters:

  • name (str) – Registered metric name.

  • output_path (Path) – Output path passed to the metric parser.

  • context (list[str]) – YAML context used for error reporting.

Returns:

Metric callable.

Return type:

Callable

lir.config.substitution module

Substitution module.

This module provides utility functions for replacing or modifying components of an LR Benchmark pipeline at runtime. Typical use cases include comparing different modelling approaches (e.g. logistic regression versus support vector machines) or optimising system lrsystem_parameters.

For example, the parameters section of the model_selection_run benchmark can define a path (comparing.clf) to be modified using the options listed in the values field. Each option updates the comparing component in the LR system configuration used by the pipeline.

experiments:
  - name: model_selection_run
    lrsystem: ...
    ...
    lrsystem_parameters:
      - path: comparing.clf
        options:
          - name: logit
            method: logistic_regression
            C: 1
          - name: svm
            method: svm
            probability: True
class lir.config.substitution.CategoricalHyperparameter(name: str, options: list[HyperparameterOption])[source]

Bases: Hyperparameter

A categorical hyperparameter.

A categorical hyperparameter has the following fields in a YAML configuration: - path: the path of this hyperparameter in the LR system configuration - options: a list of options

Parameters:
options() → list[HyperparameterOption][source]

Provide API access to the options for the hyperparameter.

Returns:

Configured categorical options.

Return type:

list[HyperparameterOption]

class lir.config.substitution.FloatHyperparameter(path: str, low: float, high: float, step: float | None, log: bool)[source]

Bases: Hyperparameter

Floating-point hyperparameter.

In a YAML configuration, this hyperparameter supports the following fields:

  • path: Path to the hyperparameter in the LR system configuration.

  • low: Lower bound of the search range.

  • high: Upper bound of the search range.

  • step (optional): Step size for a linear grid search.

  • log (optional): If True, search in logarithmic space instead of linear space. Cannot be combined with step. Defaults to False.

Parameters:

  • path (str) – Configuration path to substitute.

  • low (float) – Lower bound.

  • high (float) – Upper bound.

  • step (float | None) – Optional step size for grid options.

  • log (bool) – Whether to sample in log space.

options() → list[HyperparameterOption][source]

Provide API access to the options for the hyperparameter.

Returns:

Enumerated hyperparameter options.

Return type:

list[HyperparameterOption]

class lir.config.substitution.FolderHyperparameter(path: str, folder: str, ignore_files: list[str] | None = None)[source]

Bases: Hyperparameter

Hyperparameter that enumerates all files in a given folder as options.

This hyperparameter reads the contents of a specified folder and generates one option per file. Each option uses the file’s full path as both its name and its value.

In a YAML configuration, a folder hyperparameter supports the following fields:

  • folder: Path to the folder containing the candidate files.

  • ignore_files: Optional list of file patterns to ignore.

Example configuration:

lrsystem_parameters:
- path: data.provider.path
  type: folder
  folder: project_files/my_dataset/
  ignore_files:  # Optional list of file patterns to ignore.
   - '*.tmp'
   - 'ignore_this_file.csv'
Parameters:

  • path (str) – Configuration path to substitute.

  • folder (str) – Folder containing candidate files.

  • ignore_files (list[str] | None, optional) – Filename patterns to exclude.

Raises:

  • ValueError – If the specified folder does not exist (during initialisation).

  • ValueError – If no valid files are found in the folder after applying the ignore patterns (when calling options()).

options() → list[HyperparameterOption][source]

Generate options by walking over the folder.

Returns:

File-based options discovered in the folder.

Return type:

list[HyperparameterOption]

class lir.config.substitution.Hyperparameter(name: str)[source]

Bases: ABC

Base class for all lrsystem_parameters.

Parameters:

name (str) – Hyperparameter name.

abstractmethod options() → list[HyperparameterOption][source]

Get a list of values that a hyperparameter can take in the context of a particular experiment.

Returns:

List of options for this hyperparameter.

Return type:

list[HyperparameterOption]

class lir.config.substitution.HyperparameterOption(name: str, substitutions: Mapping[str, Any])[source]

Bases: NamedTuple

An option for a value of a hyperparameter.

A HyperparameterOption is a named tuple with two fields: - name: a descriptive name of this option - substitutions: a mapping of configuration paths to values

name: str

Alias for field number 0

substitutions: Mapping[str, Any]

Alias for field number 1

lir.config.substitution.parse_config_with_parameters(config: ConfigValue, output_dir: Path, config_field: str, parameters_field: str) → tuple[ConfigValue, list[Hyperparameter]][source]

Extract a configuration section and its associated parameters.

Parameters:

  • config (ConfigValue) – The configuration.

  • output_dir (Path) – The output directory.

  • config_field (str) – Field containing the baseline configuration.

  • parameters_field (str) – Field containing parameters to vary.

Returns:

Baseline configuration and parsed hyperparameters.

Return type:

tuple[ConfigValue, list[Hyperparameter]]

lir.config.substitution.parse_parameter(spec: ConfigValue, output_dir: Path) → Hyperparameter[source]

Parse one parameter specification into a hyperparameter object.

Parameters:

  • spec (ConfigValue) – Parameter specification.

  • output_dir (Path) – Output directory used by nested parser calls.

Returns:

Parsed hyperparameter object.

Return type:

Hyperparameter

lir.config.substitution.substitute_parameters(base_config: ConfigValue, lrsystem_parameters: Mapping[str, Any], context: list[str]) → ConfigValue[source]

Substitute parameters in an LR system configuration and return the updated configuration.

Parameters:

  • base_config (ConfigValue) – Original LR system configuration.

  • lrsystem_parameters (Mapping[str, Any]) – LR system parameters to vary and their replacement values.

  • context (list[str]) – Context path of the augmented configuration.

Returns:

Augmented LR system configuration.

Return type:

ConfigValue

lir.config.transform module

class lir.config.transform.GenericTransformerConfigParser(component_class: object)[source]

Bases: ConfigParser

Parser class to help parse the defined component into its corresponding Transformer object.

Since the scikit-learn Pipeline expects a fit() and transform() method on each of the pipeline steps, the configured components should adhere to this contract and implement these methods.

The parse() function offered in this helper class, implements a branching strategy to determine which strategy is best suited to make the component compatible with the scikit-learn pipeline.

Parameters:

component_class (object) – Component class or callable to adapt to the transformer interface.

parse(config: ConfigValue, output_dir: Path) → Transformer[source]

Prepare a configured component for use in a scikit-learn pipeline.

Parameters:

  • config (ConfigValue) – Constructor arguments for the component class.

  • output_dir (Path) – Unused output directory argument required by parser API.

Returns:

Component adapted to the Transformer interface.

Return type:

Transformer

lir.config.transform.parse_module(module_config: ConfigValue | None, output_dir: Path, default_method: str | None = None) → Transformer[source]

Construct a Transformer from a string or configuration section.

If module_config is None, an Identity transformer is returned.

If module_config is a dictionary, it must contain a method field whose value is the name of an object looked up in the registry. All remaining fields are passed as initialisation arguments. If no arguments are required, the input may be given directly as the object name.

The resolved object is handled as follows:

  • If it is a subclass of ConfigParser, the class is instantiated and the result of its parse() method is returned.

  • If it defines a transform method, or is a subclass of Transformer, it is instantiated and returned.

  • If it defines a predict_proba method, it is instantiated, wrapped in EstimatorTransformer, and returned.

  • Any other callable is wrapped in FunctionTransformer and returned.

If module_config is a string, this function behaves as if a dictionary with a single field method set to that string had been provided.

Parameters:

  • module_config (ConfigValue) – Specification of the module.

  • output_dir (Path) – Directory where any output produced by the module is written.

  • default_method (str | None, optional) – Default value for the method field if it is not provided.

Returns:

The constructed transformer instance.

Return type:

Transformer

lir.config.transform.parse_pairing_config(module_config: ConfigValue, output_dir: Path) → PairingMethod[source]

Parse and delegate pairing to the corresponding function for the defined pairing method.

The argument module_config defines the pairing method. If its value is a str, the registry is queried and the corresponding pairing method is returned. If its value is a dict, the pairing method is defined by the value module_config[“method”], and the registry is queried for the config parser of the corresponding pairing method. The remaining values in module_config are passed as arguments to the configuration parser of the pairing method.

If the registry cannot resolve the pairing method, an exception is raised.

Parameters:

  • module_config (ConfigValue) – Pairing method configuration.

  • output_dir (Path) – Output directory for parser calls.

Returns:

Parsed pairing method.

Return type:

PairingMethod

lir.config.util module

class lir.config.util.TeeParser[source]

Bases: ConfigParser

Parse configuration for allowing multiple tasks for given input.

parse(config: ConfigValue, output_dir: Path) → Any[source]

Read configuration for modules section and provide wrapped corresponding transformers.

Parameters:

  • config (ConfigValue) – Configuration for the Tee transformer, containing a modules field with a list of module configurations.

  • output_dir (Path) – Output directory for the parsed modules.

Returns:

A Tee transformer wrapping the parsed modules.

Return type:

Any