lir package

LiR - Toolkit for developing, optimising and evaluating Likelihood Ratio (LR) systems.

This allows benchmarking of LR systems on different datasets, investigating impact of different sampling schemes or techniques, and doing case-based validation and computation of case LRs.

class lir.DataProvider[source]

Bases: ABC

Base class for data providers.

Each data provider should provide access to instance data by implementing the get_instances() method.

abstractmethod get_instances() → InstanceData[source]

Return an InstanceData object, containing data for a set of instances.

Returns:: Instance data object produced by this operation.
Return type:: InstanceData

class lir.DataStrategy[source]

Bases: ABC

Base class for data (splitting) strategies.

abstractmethod apply(instances: DataType) → Iterable[tuple[DataType, DataType]][source]

Provide iterator to access training and test set.

Returns an iterator over tuples of a training set and a test set. Both the training set and the test is represented by an InstanceData object.

Parameters:: instances (DataType) – Input instances to be processed by this method.
Returns:: Iterable of (train_set, test_set) splits for the provided data.
Return type:: Iterable[tuple[DataType, DataType]]

class lir.FeatureData(*, hypothesis: Annotated[ndarray | None, AfterValidator(func=_validate_hypothesis)] = None, source_ids: Annotated[ndarray | None, AfterValidator(func=_validate_source_ids)] = None, features: Annotated[ndarray, AfterValidator(func=_validate_features)], **extra_data: Any)[source]

Bases: InstanceData

Data class for feature data.

Feature data can be any type of numeric data that is associated with the instances, such as measurements on a single instance or similarity scores between a pair of instances.

If the object describes single instance data, the features attribute is generally 2-dimensional, with one row per instance and one or more feature columns.

More than 2 dimensions may be used for paired data, see PairedFeatureData.

- features

Type:: an array of instance features, with one row per instance

check_features() → Self[source]

Validate the features.

Returns:: This feature-data object after numeric type validation.
Return type:: Self

check_matching_shapes() → Self[source]

Validate the shape of the features and the labels are matching.

Returns:: This feature-data object after shape consistency checks.
Return type:: Self

features: Annotated[ndarray, AfterValidator(func=_validate_features)]

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class lir.InstanceData(*, hypothesis: Annotated[ndarray | None, AfterValidator(func=_validate_hypothesis)] = None, source_ids: Annotated[ndarray | None, AfterValidator(func=_validate_source_ids)] = None, **extra_data: Any)[source]

Bases: BaseModel, ABC

Base class for data on instances.

An InstanceData object may be labeled or unlabeled with ground-truth data. If it is labeled, the label values correspond to the hypotheses and have values 0 or 1. In literature, the labels may have different names for values 1 and 0 respectively, such as:

hypothesis 1 and hypothesis 2 (or H1 and H2)
prosecutor’s hypothesis and defense hypothesis (or Hp and Hd)
same-source and different-source (or Hss and Hds)

The instances may optionally be associated with sources by means of the source_ids attribute. If available, each instance will generally have one source id if the object holds single instances, or two source ids if the object holds pairs of instances.

This class imposes no restrictions on the actual instance data. Sub class implementations will specialize in particular data types.

- `labels`

either 0 or 1.

Type:: The hypothesis labels of the instances, as a 1-dimensional array with one value per instance, can be

- `source_ids`

except if it is a pair, in which case it has two sources. The source ids is either a 1-dimensional array or a 2-dimensional array with two columns.

Type:: The ids of all sources that contributed to the instances. Each instance is from a single source,

property all_fields: list[str]

Return all available field names for this data object.

Returns:: Names of all standard and extra fields available on the instance.
Return type:: list[str]

apply(fn: Callable, *args: Any, **kwargs: Any) → Self[source]

Apply a custom function to this InstanceData object.

The function fn is applied to all Numpy fields. Other fields are copied as-is.

Parameters:

fn (Callable) – Value passed via fn.
*args (Any) – Additional positional arguments forwarded to the underlying call.
**kwargs (Any) – Additional keyword arguments forwarded to the underlying call.

Returns:

New instance data object after applying the function to numpy fields.

Return type:

Self

check_both_hypotheses() → ndarray[source]

Return hypothesis labels or raise an error if they are missing or if they do not represent both hypotheses.

Raise:: ValueError if hypothesis labels are missing or either label is not represented.
Returns:: Hypothesis array containing both classes 0 and 1.
Return type:: np.ndarray

check_sourceids_labels_match() → Self[source]

Validate the source_ids and labels have matching shapes.

Returns:: This instance data object after post-init validation.
Return type:: Self

combine(others: list[InstanceData] | InstanceData, fn: Callable, *args: Any, **kwargs: Any) → Self[source]

Apply a custom combination function to InstanceData objects.

All objects must have the same types and fields, and the same values for all non-numpy array fields, or an error is raised. Numpy fields are concatenated using fn. Other fields are copied as-is.

Parameters:

others ('list[InstanceData] | InstanceData') – Value passed via others.
fn (Callable) – Value passed via fn.
*args (Any) – Additional positional arguments forwarded to the underlying call.
**kwargs (Any) – Additional keyword arguments forwarded to the underlying call.

Returns:

New instance data object after applying the combination function.

Return type:

Self

concatenate(*others: InstanceData) → Self[source]

Concatenate instances from different datasets in InstanceData objects.

All concatenated objects must have the same types and fields. How fields are concatenated may depend on the subclass. By default, the behavior is as follows, in order of priority (the first takes priority):

if a field has different types, an error is raised;
if a field is a numpy array, it is assumed to describe instances, and they are concatenated along the first axis;
if a field has the same value for all InstanceData objects, the field also gets that value in the concatenated output;
if a field has the same type but different values, the field is dropped in the concatenated output.

Returns a new InstanceData object with the dataset concatenated.

Parameters:: *others ('InstanceData') – Value passed via others.
Returns:: New instance data object with concatenated rows.
Return type:: Self

property has_labels: bool

Indicate whether label values are available.

Returns:: True when label information is present.
Return type:: bool

has_same_type(other: Any) → bool[source]

Compare these instance data to another class.

Returns True iff: - other has the same class - other has the same fields - all fields have the same type

Parameters:: other (Any) – Value passed via other.
Returns:: True when type, fields, and field value types all match.
Return type:: bool

hypothesis: Annotated[ndarray | None, AfterValidator(func=_validate_hypothesis)]

property labels: ndarray | None

Legacy way to access hypothesis. Also warns that labels is deprecated and will be removed in the future.

Returns:: Label array guaranteed to contain values for both hypotheses.
Return type:: np.ndarray

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

replace(**kwargs: Any) → Self[source]

Return a modified copy with updated values.

Parameters:: **kwargs (Any) – Additional keyword arguments forwarded to the underlying call.
Returns:: Copy of this object with the provided fields replaced.
Return type:: Self

replace_as(datatype: type[InstanceDataType], **kwargs: Any) → InstanceDataType[source]

Return a modified copy with updated data type and values.

Parameters:

datatype (type['InstanceDataType']) – Value passed via datatype.
**kwargs (Any) – Additional keyword arguments forwarded to the underlying call.

Returns:

Instance data object produced by this operation.

Return type:

‘InstanceDataType’

property require_labels: ndarray

Return labels and guarantee that it is not None (or raise an error).

Returns:: Label array guaranteed to contain values for both hypotheses.
Return type:: np.ndarray

source_ids: Annotated[ndarray | None, AfterValidator(func=_validate_source_ids)]

property source_ids_1d: ndarray

Return source identifiers as a one-dimensional array.

Returns:: One-dimensional source-id array with one source per instance.
Return type:: np.ndarray

class lir.LLRData(*, hypothesis: Annotated[ndarray | None, AfterValidator(func=_validate_hypothesis)] = None, source_ids: Annotated[ndarray | None, AfterValidator(func=_validate_source_ids)] = None, features: Annotated[ndarray, AfterValidator(func=_validate_features)], llr_upper_bound: float | None = None, llr_lower_bound: float | None = None, **extra_data: Any)[source]

Bases: FeatureData

Representation of calculated LLR values.

An object of LLRData adds a specific interpretation to the features attribute.

If the features attribute has a single column (i.e. dimensions (n, 1)), the values are LLRs.
If the features attribute has three columns (i.e. dimensions (n, 3)), the values are LLRs and their confidence intervals.

The values are also accessible by the attributes llrs and llr_intervals.

- llrs

Type:: 1-dimensional numpy array of LLR values

- has_intervals

Type:: indicate whether the LLR’s have intervals

- llr_intervals

Type:: numpy array of LLR values of dimensions (n, 2), or None if the LLR’s have no intervals

- llr_upper_bound

Type:: upper bound applied to the LLRs, or None if no upper bound was applied

- llr_lower_bound

Type:: lower bound applied to the LLRs, or None if no lower bound was applied

check_features_are_llrs() → Self[source]

Validate the feature data.

Returns:: This LLR object after validating LLR-specific feature constraints.
Return type:: Self

check_misleading_finite() → None[source]: Check whether all values are either finite or not misleading.

feature_for_plot(source_key: str) → ndarray | None[source]

Return the feature values for a given source key, or None if not available.

The return value has to be saved during the LR system execution by using the save_features_after_step configuration option. If the feature values for the given source key are not available, this method returns None. Use the require_feature_for_plots if you want to raise an error instead of returning None when the feature values are not available.

Parameters:: source_key (str) – Key identifying the source of the feature values to be returned.
Returns:: Feature values for the specified source key, or None if not available.
Return type:: np.ndarray | None

property has_intervals: bool

Indicate whether interval bounds are present for each LLR.

Returns:: True when lower and upper interval bounds are included.
Return type:: bool

property llr_bounds: tuple[float | None, float | None]

Return global lower and upper bounds applied to LLR values.

Returns:: Tuple containing global lower and upper LLR clipping bounds.
Return type:: tuple[float | None, float | None]

property llr_intervals: ndarray | None

Return interval bounds for each LLR when available.

Returns:: Two-column array with lower and upper LLR bounds, if available.
Return type:: np.ndarray | None

llr_lower_bound: float | None

llr_upper_bound: float | None

property llrs: ndarray

Return the core LLR values.

Returns:: One-dimensional array containing the central LLR values.
Return type:: np.ndarray

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

require_feature_for_plots(source_key: str) → ndarray[source]

Return the feature values for a given source key, raising an error if not available.

If the feature values for the given source key are not available, this method raises a ValueError with an informative error message. Use the feature_for_plot method if you want to return None instead of raising an error when the feature values for the given source key are not available.

Parameters:: source_key (str) – Key identifying the source of the feature values to be returned.
Returns:: Feature values for the specified source key.
Return type:: np.ndarray
Raises:: ValueError – If the feature values for the given source key are not available.

class lir.PairedFeatureData(*, hypothesis: Annotated[ndarray | None, AfterValidator(func=_validate_hypothesis)] = None, source_ids: Annotated[ndarray | None, AfterValidator(func=_validate_source_ids)] = None, features: Annotated[ndarray, AfterValidator(func=_validate_features)], n_trace_instances: int, n_ref_instances: int, **extra_data: Any)[source]

Bases: FeatureData

Data class for instance pair data.

Each item in this data set represents instances from the “trace” source and from the “reference” source. The number of instances from either source must be at least one.

The features attribute has at least 3 dimensions:

the pairs are along the first dimension;
the instances are along the second dimension (e.g. in a comparison of 1 trace instance and 1 reference instance, the length of this dimension is 2);
the features are along the third dimension onward.

The source_ids, if available, must have two values for each item, i.e. 2 columns.

- n_trace_instances

Type:: the number of trace instances in each pair

- n_ref_instances

Type:: the number of reference instances in each pair

- features

second

Type:: the features of all instances in the pair, with pairs along the first dimension, and instances along the

- source_ids

columns

Type:: the source ids of the trace and reference instances of each pair, a 2-dimensional array with two

- features_trace

Type:: the features of the trace instances

- features_ref

Type:: the features of the reference instances

- source_ids_trace

Type:: the source ids of the trace instances

- source_ids_ref

Type:: the source ids of the reference instances

check_features_dimensions() → Self[source]

Validate feature dimensions.

Returns:: This paired-feature object after feature-dimension validation.
Return type:: Self

check_sourceid_shape() → Self[source]

Override the InstanceData implementation.

Returns:: This paired-feature object after source-id shape validation.
Return type:: Self

property features_ref: ndarray

Get the features of the reference instances.

Returns:: Feature tensor slice containing reference-instance features.
Return type:: np.ndarray

property features_trace: ndarray

Get the features of the trace instances.

Returns:: Feature tensor slice containing trace-instance features.
Return type:: np.ndarray

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_ref_instances: int

n_trace_instances: int

property source_ids_ref: ndarray | None

Get the source ids of the reference instances.

Returns:: Reference source IDs when available, otherwise None.
Return type:: np.ndarray | None

property source_ids_trace: ndarray | None

Get the source ids of the trace instances.

Returns:: Trace source IDs when available, otherwise None.
Return type:: np.ndarray | None

class lir.Transformer[source]

Bases: ABC

Transformer module which is compatible with the scikit-learn Pipeline.

The transformer should provide a transform() method. Since transformers are not fitted to the data, the fit() simply returns the object it was called upon without side effects.

abstractmethod apply(instances: InstanceData) → InstanceData[source]

Convert the instance data based on the (optionally fitted) model.

Parameters:: instances (InstanceData) – Input instances to be processed by this method.
Returns:: Instance data object produced by this operation.
Return type:: InstanceData

fit(instances: InstanceData) → Self[source]

Perform (optional) fitting of the instance data.

Parameters:: instances (InstanceData) – Input instances to be processed by this method.
Returns:: This transformer instance after fitting.
Return type:: Self

fit_apply(instances: InstanceData) → InstanceData[source]

Combine call to fit() with directly following call to apply().

Parameters:: instances (InstanceData) – Input instances to be processed by this method.
Returns:: Instance data object produced by this operation.
Return type:: InstanceData

lir.is_interactive() → bool[source]

Determine if the LiR tool is running from the CLI and should be interactive.

This method is used, for example, to determine if a progress bar should be shown.

Returns:: True when standard output is connected to a terminal, otherwise False.
Return type:: bool

Subpackages

Submodules

lir.bounding module

class lir.bounding.LLRBounder(lower_llr_bound: float | None = None, upper_llr_bound: float | None = None)[source]

Bases: Transformer, ABC

Base class for LLR bounders.

A bounder updates any LLRs that are out of bounds. Any LLR values within bounds remain unchanged. LLR values that are out-of-bounds are updated to the nearest bound.

Parameters:

lower_llr_bound (float | None) – The lower bound for the LLRs. If None, no lower bound is applied.
upper_llr_bound (float | None) – The upper bound for the LLRs. If None, no upper bound is applied.

apply(instances: InstanceData) → LLRData[source]

Recalculate the LLR data using the first step calibrator and applying the bounds.

Parameters:: instances (InstanceData) – The data to apply the bounder to. This should include the LLRs and their corresponding labels.
Returns:: The LLR data with the LLRs bounded according to the calculated bounds.
Return type:: LLRData

abstractmethod calculate_bounds(llrdata: LLRData) → tuple[float | None, float | None][source]

Calculate and return appropriate bounds for a set of LLRs and their labels.

Parameters:: llrdata (LLRData) – The LLR data for which to calculate the bounds. This includes the LLRs, their labels, and any other relevant information.

fit(instances: InstanceData) → Self[source]

Configure this bounder by calculating bounds.

assuming that y=1 corresponds to Hp, y=0 to Hd

Parameters:: instances (InstanceData) – The data to fit the bounder on. This should include the LLRs and their corresponding labels.
Returns:: The fitted bounder instance.
Return type:: Self

class lir.bounding.NSourceBounder(lower_llr_bound: float | None = None, upper_llr_bound: float | None = None)[source]

Bases: LLRBounder

Bound LLRs based on the number of sources.

This bounder sets the lower LLR bound to -log(N) and the upper bound to log(N), where N is the number of sources.

In non-log space, this corresponds to bounding likelihood ratios to [1/N, N]. This is a logical consequence of having N sources: no source can provide more than N support for one hypothesis over the other.

calculate_bounds(llrdata: LLRData) → tuple[float | None, float | None][source]

Calculate and return the lower and upper LLR bounds.

Parameters:: llrdata (LLRData) – The LLR data for which to calculate the bounds. This should include the source IDs.
Returns:: The lower and upper LLR bounds, calculated based on the number of sources.
Return type:: tuple[float | None, float | None]

class lir.bounding.StaticBounder(lower_llr_bound: float | None, upper_llr_bound: float | None)[source]

Bases: LLRBounder

Bound LLRs to constant values.

This bounder takes arguments for a lower and upper bound, which may take None in which case no bounds are applied.

Parameters:

lower_llr_bound (float | None) – The lower bound for the LLRs. If None, no lower bound is applied.
upper_llr_bound (float | None) – The upper bound for the LLRs. If None, no upper bound is applied.

calculate_bounds(llrdata: LLRData) → tuple[float | None, float | None][source]

Calculate and return the lower and upper LLR bounds.

Parameters:: llrdata (LLRData) – Not used, but included for compatibility with the base class.
Returns:: The lower and upper LLR bounds, as specified in the constructor.
Return type:: tuple[float | None, float | None]

lir.main module

lir.main.copy_yaml_definition(output_dir: Path, config_yaml_path: Path) → None[source]

Copy the YAML definition for a given LR system experiment to persist the used configuration.

Parameters:

output_dir (Path) – The directory where the YAML definition should be copied.
config_yaml_path (Path) – The path to the YAML file describing the experiment configuration.

lir.main.error(msg: str, e: Exception | None = None) → None[source]

Stop execution with given error message or raise exception.

Parameters:

msg (str) – The error message to be printed to stderr.
e (Exception | None) – The exception to be raised, or None to not raise an exception.

lir.main.initialize_experiments(cfg: Configuration) → tuple[Mapping[str, Experiment], Path][source]

Extract which Experiment to run as dictated in the configuration.

The following pre-defined variables are injected to the configuration:

timestamp: a formatted timestamp of the current date/time

Parameters:: cfg (confidence.Configuration) – A Configuration object describing the experiments.
Returns:: A tuple with two elements: (1) mapping of names to experiments; (2) path to output directory.
Return type:: tuple[Mapping[str, Experiment], Path]

lir.main.initialize_logfile(output_dir: Path) → None[source]

Set up logfile for debugging purposes when running experiment.

Parameters:: output_dir (Path) – The directory where the logfile should be created.

lir.main.main(input_args: list[str] | None = None) → None[source]

Run all or some of the parts of project.

Parameters:: input_args (list[str] | None) – The command-line arguments to parse, or None to parse the actual command-line arguments.

lir.main.setup_logging(level_increase: int) → None[source]

Set up logging to stderr and to a file.

Parameters:: level_increase (int) – Log level for stderr, relative to the default log level.

lir.persistence module

class lir.persistence.SaveModel(filename: PathLike | str = 'model.pkl')[source]

Bases: Aggregation

Write the model to a file.

The model is saved as a pickle file, in a file named filename, that is written to a subdirectory of output_dir, that is created for each run.

If filename is an absolute path, or if filename is relative to output_dir, then the model is saved to this file as-is, instead of to a file in a newly created subdirectory.

Once a model is saved, it can be loaded again using the load_model() function.

Parameters:: filename (PathLike | str) – The filename to be created for the model.

report(data: AggregationData) → None[source]

Create a directory for the run and write the trained LR system model to file.

Parameters:: data (AggregationData) – The data to be aggregated, containing the trained LR system model and the run name.

lir.persistence.load_model(path: Path) → LRSystem[source]

Load previously cached model.

The model is expected to be stored as a pickle file, and is assumed to exclusively contain an LRSystem instance.

Parameters:: path (Path) – The path to the .pkl file containing the model.
Returns:: The loaded model.
Return type:: LRSystem

Examples

from lir.persistence import load_model
from lir import FeatureData

model = load_model(Path('path/to/model.pkl'))
data = FeatureData(...) # some data to apply the model to

model.apply(data)

lir.persistence.save_model(path: Path, model: LRSystem) → None[source]

Save a model to disk.

This method is intended for use with the Python API. For yaml-based configuration of model saving, see the SaveModel aggregation.

Parameters:

path (Path) – The path to the .pkl file where the model should be saved.
model (LRSystem) – The model to be saved.

lir.registry module

class lir.registry.ClassLoader[source]

Bases: ConfigParserLoader

A configuration parser loader that uses reflection to resolve class names.

get(key: str, default_config_parser: Callable[[Any], ConfigParser] | None = None, search_path: list[str] | None = None) → ConfigParser[source]

Get the accompanying config parser class from the registry.

Parameters:

key (str) – The key name to resolve, expected to be a full class name (for example: ‘lir.transform.base.BaseTransform’).
default_config_parser (Callable[[Any], ConfigParser] | None, optional) – A function that returns a ConfigParser if the key does not resolve to a ConfigParser, by default None.
search_path (list[str] | None, optional) – The domain of the search query, by default None.

Returns:

A ConfigParser object.

Return type:

ConfigParser

exception lir.registry.ComponentNotFoundError[source]

Bases: ValueError

Representation of an error when a component class cannot be found.

class lir.registry.ConfigParserLoader[source]

Bases: ABC, Iterable

Base class for a configuration parser loader.

A configuration parser is able to interpret a dictionary-style configuration loaded from a YAML. Sub classes are expected to implement the get() method.

abstractmethod get(key: str, default_config_parser: Callable[[Any], ConfigParser] | None = None, search_path: list[str] | None = None) → ConfigParser[source]

Retrieve a value for a given key name.

The key may resolve to a ConfigParser class, or it is passed as an argument to default_config_parser, which in turn returns a ConfigParser class.

Parameters:

key (str) – The key name to resolve.
default_config_parser (Callable[[Any], ConfigParser] | None, optional) – A function that returns a ConfigParser if the key does not resolve to a ConfigParser, by default None.
search_path (list[str] | None, optional) – The domain of the search query, by default None.

Returns:

A ConfigParser object.

Return type:

ConfigParser

class lir.registry.FederatedLoader(registries: list[ConfigParserLoader])[source]

Bases: ConfigParserLoader

A configuration parser loader that delegates resolution to other loaders.

Parameters:: registries (list[ConfigParserLoader]) – A list of configuration parser loaders to delegate to, in order of priority.

get(key: str, default_config_parser: ~collections.abc.Callable[[~typing.Any], ~lir.config.base.ConfigParser] | None = <class 'lir.config.base.GenericConfigParser'>, search_path: list[str] | None = None) → ConfigParser[source]

Get the accompanying config parser class from the registry.

Parameters:

key (str) – The key name to resolve.
default_config_parser (Callable[[Any], ConfigParser] | None, optional) – A function that returns a ConfigParser if the key does not resolve to a ConfigParser.
search_path (list[str] | None, optional) – The domain of the search query, by default None.

Returns:

A ConfigParser object.

Return type:

ConfigParser

exception lir.registry.InvalidRegistryEntryError[source]

Bases: ValueError

Representation of an invalid registry entry.

class lir.registry.YamlRegistry(cfg: Configuration)[source]

Bases: ConfigParserLoader

Representation of a YAML-based registry.

The YAML registry is organized into sections as the lop=level key names. Each section can have registry entries. A registry entry is a configuration parser. It can be used in an experiment setup to materialize a component and initialize it with its configuration.

This registry parses this YAML mapping and provides access to registry antries through a get() method.

A registry entry can take the following arguments:

class: a str that can be resolved to a ConfigParser
args: the arguments passed to the config parser

Example:

section:
  entry:
    class: package.ClassName
    args:
      foo: some init argument
      bar: another init argument

If the configuration parser only has a class argument, the alternative notation can be used where the class is passed as a string value to the entry directly. Example:

section:
  entry: package.ClassName

The class of each entry may be a ConfigParser. If it is not, the registry parser will attempt to use a default configuration parser, depending on the context, and the default configuration parser will be initialized with the object of the registry entry.

Parameters:: cfg (confidence.Configuration) – The configuration object containing the registry entries.

get(key: str, default_config_parser: Callable[[Any], ConfigParser] | None = None, search_path: list[str] | None = None) → ConfigParser[source]

Retrieve a value for a given key name from the YAML-based registry.

An entry can take the following forms, available under the keys path.to.key1 and path.to.key2 respectively:

path.to.key1: ObjectName
path.to.key2:
    class: ObjectName

In the example, ObjectName refers to a Python object available in the current runtime.

Parameters:

key (str) – The key name to resolve.
default_config_parser (Callable[[Any], ConfigParser] | None, optional) – A function that returns a ConfigParser if the key does not resolve to a ConfigParser, by default None.
search_path (list[str] | None, optional) – The domain of the search query, by default None.

Returns:

A ConfigParser object.

Return type:

ConfigParser

lir.registry.get(name: str, default_config_parser: Callable[[Any], ConfigParser] | None = None, search_path: list[str] | None = None) → ConfigParser[source]

Retrieve corresponding value for a given key name from the central registry.

Parameters:

name (str) – The key name to resolve.
default_config_parser (Callable[[Any], ConfigParser] | None, optional) – A function that returns a ConfigParser if the key does not resolve to a ConfigParser, by default None.
search_path (list[str] | None, optional) – The domain of the search query, by default None.

Returns:

A ConfigParser object.

Return type:

ConfigParser

lir.registry.registry() → ConfigParserLoader[source]

Provide access to a centralized registry of available configuration options.

Returns:: A configuration parser loader that can be used to retrieve configuration parsers for various components.
Return type:: ConfigParserLoader

lir.util module

class lir.util.Bind[source]

Bases: partial

Wrap partial to support the ellipsis (…) as a placeholder.

Can be used to fix parameters not at the end of the list of parameters (which is a limitation of partial).

class lir.util.LR(lr, p0, p1)

Bases: tuple

lr: Alias for field number 0

p0: Alias for field number 1

p1: Alias for field number 2

lir.util.Xn_to_Xy(*Xn: ndarray) → tuple[ndarray, ndarray][source]

Convert Xn to Xy format.

Parameters:: *Xn (np.ndarray) – Variable number of arrays, where each array corresponds to a class and contains the samples for that class.
Returns:: A tuple containing: - X: A 2D array where all samples from the input arrays are concatenated together. - y: A 1D array of the same length as the number of samples in X, where each element indicates the class label.
Return type:: tuple[np.ndarray, np.ndarray]

lir.util.Xy_to_Xn(X: ndarray, y: ndarray, classes: list[int] | None = None) → list[ndarray][source]

Convert Xy to Xn format.

Parameters:

X (np.ndarray) – A 2D array where rows correspond to samples and columns correspond to features.
y (np.ndarray) – A 1D array of the same length as the number of samples in X, where each element indicates the class label.
classes (list[int] | None, optional) – An optional list of class labels to be used for splitting the data. If not provided, the unique values in y will be used as class labels.

Returns:

A list of arrays, where each array corresponds to a class and contains the samples for that class.

Return type:

list[np.ndarray]

lir.util.check_is_enum_option(enum_type: type[Enum], value: ValueType) → ValueType[source]

Check if an input value is one of the options of an Enum type.

Otherwise, a ValueError is raised.

Parameters:

enum_type (Enum) – The expected type of the input value.
value (ValueType) – The value to validate.

Returns:

The input value if it is of the expected type.

Return type:

ValueType

lir.util.check_not_none(v: AnyType | None, message: str | None = None) → AnyType[source]

Check if a given input is not None. If so, return the input value. Otherwise, raise a ValueError.

Parameters:

v (AnyType | None) – The input value to be checked.
message (str, optional) – An optional message to be included in the error if the check fails. If not provided, a default message will be used.

Returns:

The input value v if it is not None.

Return type:

AnyType

lir.util.check_type(type_class: type[AnyType] | tuple, v: Any, message: str | None = None) → AnyType[source]

Check if a given input is of the expected, specified type. If so, return the input value.

Parameters:

type_class (type) – The expected type of the input value.
v (Any) – The input value to be checked against the expected type.
message (str, optional) – An optional message to be included in the error if the type check fails. If not provided, a default message indicating the expected type will be used.

Returns:

The input value v if it is of the expected type.

Return type:

AnyType

lir.util.get_classes_from_Xy(X: ndarray, y: ndarray, classes: list[Any] | None = None) → ndarray[source]

Get the classification classes from labeled data.

Parameters:

X (np.ndarray) – The input data array, where rows correspond to samples and columns correspond to features.
y (np.ndarray) – The target labels corresponding to each sample in X. This should be a 1-dimensional array.
classes (list[Any] | None, optional) – An optional list of classes to be used. If not provided, the unique values in y will be used.

Returns:

An array of unique classes found in y if classes is None; otherwise, an array of the provided classes.

Return type:

np.ndarray

lir.util.ln_to_log10(ln_data: FloatOrArray) → FloatOrArray[source]

Convert natural logarithm to 10-base logarithm.

Parameters:: ln_data (FloatOrArray) – Data in natural logarithm form to be converted to 10-base logarithm.
Returns:: The input data converted from natural logarithm to 10-base logarithm.
Return type:: FloatOrArray

lir.util.logodds_to_odds(log_odds: FloatOrArray) → FloatOrArray[source]

Convert 10-base logarithm odds to odds.

Parameters:: log_odds (FloatOrArray) – The 10-base logarithm of odds to be converted to odds.
Returns:: The input 10-base logarithm of odds converted to odds.
Return type:: FloatOrArray

lir.util.logodds_to_probability(log_odds: FloatOrArray) → FloatOrArray[source]

Convert 10-base logarithm of odds to probability.

Parameters:: log_odds (FloatOrArray) – The 10-base logarithm of odds to be converted to probability.
Returns:: The input 10-base logarithm of odds converted to probability.
Return type:: FloatOrArray

lir.util.odds_to_logodds(odds: FloatOrArray) → FloatOrArray[source]

Convert odds to 10-base logarithm odds.

Parameters:: odds (FloatOrArray) – The odds to be converted to 10-base logarithm odds.
Returns:: The input odds converted to 10-base logarithm odds.
Return type:: FloatOrArray

lir.util.odds_to_probability(odds: FloatOrArray) → FloatOrArray[source]

Convert odds to a probability.

Parameters:: odds (FloatOrArray) – The odds to be converted to probability.
Returns:: The input odds converted to probability. This is 1 if the input odds is infinity, and otherwise calculated as odds / (1 + odds).
Return type:: FloatOrArray

lir.util.parse_float(s: str, none_for_empty: bool = False) → float | None[source]

Convert a string to a float.

Parameters:

s (str) – The string to convert to a float.
none_for_empty (bool) – If True, return None if the string is empty. Otherwise, raise a ValueError.

Returns:

The converted value.

Return type:

float

lir.util.probability_to_logodds(p: FloatOrArray) → FloatOrArray[source]

Convert probability values to their log odds with base 10.

Parameters:: p (FloatOrArray) – The probability values to be converted to log odds.
Returns:: The input probability values converted to log odds with base 10.
Return type:: FloatOrArray

lir.util.probability_to_odds(p: FloatOrArray) → FloatOrArray[source]

Convert a probability to odds.

Parameters:: p (FloatOrArray) – The probability to be converted to odds.
Returns:: The input probability converted to odds. This is infinity if the input probability is 1, and otherwise calculated as p / (1 - p).
Return type:: FloatOrArray

lir.util.to_native_dict(cfg: Any) → Any[source]

Recursively convert confidence Configuration objects to native Python dicts/lists.

Accesses each value through cfg[key] to trigger reference resolution. The confidence library doesn’t have a built-in method for this, so we manually traverse and resolve.

Similar to ConfigValue().

Parameters:: cfg (Any) – The input configuration object, which can be a confidence Configuration, ConfigurationSequence, dict, list, or any other type.
Returns:: The input Configuration object converted to a native Python dict or list.
Return type:: Any

lir.util.validate_yaml(yaml_path: Path) → None[source]

Validate a YAML file against the schema.

Parameters:

yaml_path (Path) – The path to the YAML file to be validated.

Raises:

FileNotFoundError – If the YAML file or the schema file does not exist.
yaml.YAMLError – If the YAML file is not valid YAML.
ValidationError – If the YAML file does not conform to the schema.

lir.util.warn_deprecated() → None[source]: Provide template message for deprecated functions.