lir.algorithms package

Submodules

lir.algorithms.bayeserror module

Normalised Bayes error rate (NBE).

References

Vergeer, P., van Es, A., de Jongh, A., Alberink, I., & Stoel, R. (2016). Numerical likelihood ratios output by LR systems are often based on extrapolation: When to stop extrapolating? Science and Justice, 56, 482–491.

class lir.algorithms.bayeserror.ELUBBounder(lower_llr_bound: float | None = None, upper_llr_bound: float | None = None)[source]

Bases: LLRBounder

Calculate the Empirical Upper and Lower Bounds for a given LR system.

Class that, given an LR system, outputs the same LRs as the system but bounded by the Empirical Upper and Lower Bounds as described in P. Vergeer, A. van Es, A. de Jongh, I. Alberink, R.D. Stoel, Numerical likelihood ratios outputted by LR systems are often based on extrapolation: when to stop extrapolating? Sci. Justics 56 (2016) 482-491.

# MATLAB code from the authors:

# clear all; close all; # llrs_hp=csvread(’…’); # llrs_hd=csvread(’…’); # start=-7; finish=7; # rho=start:0.01:finish; theta=10.^rho; # nbe=[]; # for k=1:length(rho) # if rho(k)<0 # llrs_hp=[llrs_hp;rho(k)]; # nbe=[nbe;(theta(k)^(-1))*mean(llrs_hp<=rho(k))+… # mean(llrs_hd>rho(k))]; # else # llrs_hd=[llrs_hd;rho(k)]; # nbe=[nbe;theta(k)*mean(llrs_hd>=rho(k))+… # mean(llrs_hp<rho(k))]; # end # end # plot(rho,-log10(nbe)); hold on; # plot([start finish],[0 0]); # a=rho(-log10(nbe)>0); # empirical_bounds=[min(a) max(a)]

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

Calculate the LLR empirical upper and lower bounds (ELUB).

Parameters:

llrdata (LLRData) – An instance of LLRData containing LLRs and ground-truth labels.

Returns:

A tuple containing the lower and upper bounds. If the bounds cannot be calculated, returns (None, None).

Return type:

tuple[float | None, float | None]

lir.algorithms.bayeserror.calculate_expected_utility(lrs: ndarray, y: ndarray, threshold_lrs: ndarray, add_misleading: int = 0) → float[source]

Calculate the expected utility of a set of LRs for a given threshold.

Parameters:

  • lrs (np.ndarray) – Array of LRs.

  • y (np.ndarray) – Array of ground-truth labels (0 for Hd or 1 for Hp), with the same length as lrs.

  • threshold_lrs (np.ndarray) – Array of threshold LRs used as acceptance thresholds.

  • add_misleading (int, optional) – Number of consequential misleading LRs to add.

Returns:

Expected utility values, one element for each threshold LR.

Return type:

float

lir.algorithms.bayeserror.elub(llrdata: LLRData, add_misleading: int = 1, step_size: float = 0.01, substitute_extremes: tuple[float, float] = (-9, 9)) → tuple[float, float][source]

Calculate and return the empirical upper and lower bound log10-LRs (ELUB LLRs).

Parameters:

  • llrdata (LLRData) – An instance of LLRData containing LLRs and ground-truth labels.

  • add_misleading (int, optional) – The number of consequential misleading LLRs to be added to both sides (labels 0 and 1).

  • step_size (float, optional) – Required accuracy on a 10-base logarithmic scale.

  • substitute_extremes (tuple[float, float], optional) – The values to substitute for extreme LRs, i.e. LRs of 0 and inf are substituted by these values.

Returns:

A tuple containing the lower and upper ELUB log10-LRs.

Return type:

tuple[float, float]

lir.algorithms.bayeserror.plot_nbe(ax: Axes, llrdata: LLRData, log_lr_threshold_range: tuple[float, float] | None = None, add_misleading: int = 1, step_size: float = 0.01) → None[source]

Generate the visual NBE plot using matplotlib.

Parameters:

  • ax (plt.Axes) – The matplotlib axis to plot on.

  • llrdata (LLRData) – An instance of LLRData containing LLRs and ground-truth labels.

  • log_lr_threshold_range (tuple[float, float] | None, optional) – The range of log LR threshold values to consider for the plot. If None, it will be determined based on the minimum and maximum LLRs in the data, with a margin of 0.5 added to both ends. Default is None.

  • add_misleading (int, optional) – The number of consequential misleading LLRs to be added to both sides (labels 0 and 1). Default is 1.

  • step_size (float, optional) – The step size for the log LR threshold range, determining the resolution of the plot. Default is 0.01.

lir.algorithms.bootstraps module

class lir.algorithms.bootstraps.Bootstrap(steps: list[tuple[str, Any]], n_bootstraps: int = 400, interval: tuple[float, float] = (0.05, 0.95), seed: int | None = None)[source]

Bases: Pipeline, ABC

Bootstrap system that estimates confidence intervals around the best estimate of a pipeline.

This bootstrap system creates bootstrap samples from the training data, fits the pipeline on each sample, and then computes confidence intervals for the pipeline outputs based on the variability across the bootstrap samples.

Computing these intervals is done by creating interpolation functions that map the best estimate to the difference between the best estimate and the lower and upper bounds of the confidence interval. To achieve this, two subclasses are provided that differ in how the data points for interval estimation are obtained.

  • BootstrapAtData: Uses the original training data points for interval estimation.

  • BootstrapEquidistant: Uses equidistant points within the range of the training data for interval estimation.

The AtData variant allows for more complex data types, while the Equidistant variant is only suitable for continuous features.

Parameters:

  • steps (list[tuple[str, Any]]) – The pipeline steps to bootstrap.

  • n_bootstraps (int, optional) – Number of bootstrap samples to generate.

  • interval (tuple[float, float], optional) – Lower and upper quantiles for the confidence interval.

  • seed (int | None, optional) – Random seed for reproducibility.

apply(instances: InstanceData) → LLRData[source]

Transform the provided instances to include the best estimate and confidence intervals.

Parameters:

instances (InstanceData) – The feature data to transform.

Returns:

The transformed feature data with best estimate and confidence intervals.

Return type:

LLRData

fit(instances: InstanceData) → Self[source]

Fit the bootstrap system to the provided instances.

Parameters:

instances (InstanceData) – The feature data to fit the bootstrap system on.

Returns:

The fitted bootstrap system.

Return type:

Self

fit_apply(instances: InstanceData) → LLRData[source]

Combine fitting and transforming in one step.

Parameters:

instances (InstanceData) – The feature data to fit and transform.

Returns:

The transformed feature data with best estimate and confidence intervals.

Return type:

LLRData

abstractmethod get_bootstrap_data(instances: InstanceData) → InstanceData[source]

Get the data points to use for interval estimation.

This method should be implemented by subclasses to specify how the data points for interval estimation are obtained.

Parameters:

instances (InstanceData) – The feature data to fit the bootstrap system on.

Returns:

The feature data to use for interval estimation.

Return type:

InstanceData

class lir.algorithms.bootstraps.BootstrapAtData(steps: list[tuple[str, Any]], n_bootstraps: int = 400, interval: tuple[float, float] = (0.05, 0.95), seed: int | None = None)[source]

Bases: Bootstrap

Bootstrap system that uses the original training data points for interval estimation.

See the Bootstrap class for more details.

get_bootstrap_data(instances: InstanceData) → InstanceData[source]

Get the data points to use for interval estimation.

The original training data points are used.

Parameters:

instances (InstanceData) – The feature data to fit the bootstrap system on.

Returns:

The feature data to use for interval estimation.

Return type:

InstanceData

class lir.algorithms.bootstraps.BootstrapEquidistant(steps: list[tuple[str, Any]], n_bootstraps: int = 400, interval: tuple[float, float] = (0.05, 0.95), seed: int | None = None, n_points: int | None = 1000)[source]

Bases: Bootstrap

Bootstrap system that uses equidistant points within the range of the training data for interval estimation.

See the Bootstrap class for more details.

Parameters:

  • steps (list[tuple[str, Any]]) – The pipeline steps to bootstrap.

  • n_bootstraps (int, optional) – Number of bootstrap samples to generate.

  • interval (tuple[float, float], optional) – Lower and upper quantiles for the confidence interval.

  • seed (int | None, optional) – Random seed for reproducibility.

  • n_points (int | None, optional) – Number of equidistant points to use for interval estimation.

get_bootstrap_data(instances: InstanceData) → FeatureData[source]

Get the data points to use for interval estimation.

This is done by creating equidistant points within the range of the training data.

Parameters:

instances (InstanceData) – The feature data to fit the bootstrap system on.

Returns:

The feature data to use for interval estimation, consisting of equidistant points within the range of the training data.

Return type:

FeatureData

lir.algorithms.devpav module

lir.algorithms.devpav.devpav(llrs: LLRData) → float[source]

Calculate devPAV for LR data under H1 and H2.

Parameters:

llrs (LLRData) – LLRs and their metadata, wrapped in an LLRData object.

Returns:

DevPAV score.

Return type:

float

lir.algorithms.invariance_bounds module

Extrapolation bounds on LRs using the Invariance Verification method by Alberink et al. (2025).

References

Alberink, I., Leegwater, J., Malmborg, J., Nordgaard, A., Sjerps, M., & van der Ham, L. (2025). A transparent method to determine limit values for likelihood ratio systems. Submitted for publication.

class lir.algorithms.invariance_bounds.IVBounder(lower_llr_bound: float | None = None, upper_llr_bound: float | None = None)[source]

Bases: LLRBounder

Calculate Invariance Verification bounds for a given LR system.

Class that, given an LR system, outputs the same LRs as the system but bounded by the Invariance Verification bounds as described in: A transparent method to determine limit values for Likelihood Ratio systems, by Ivo Alberink, Jeannette Leegwater, Jonas Malmborg, Anders Nordgaard, Marjan Sjerps, Leen van der Ham In: Submitted for publication in 2025.

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

Calculate the Invariance Verification bounds.

Parameters:

llrdata (LLRData) – LLR data used to derive invariance bounds.

Returns:

Lower and upper LLR bounds.

Return type:

tuple[float | None, float | None]

lir.algorithms.invariance_bounds.calculate_invariance_bounds(llrdata: LLRData, llr_threshold: ndarray | None = None, step_size: float = 0.001, substitute_extremes: tuple[float, float] = (-20, 20)) → tuple[float, float, ndarray, ndarray][source]

Return the upper and lower Invariance Verification bounds of the LRs.

Parameters:

  • llrdata (LLRData) – LLR data containing LLRs and ground-truth labels.

  • llr_threshold (np.ndarray | None, optional) – Predefined LLR thresholds as candidate bounds.

  • step_size (float, optional) – Required accuracy on a base-10 logarithmic scale.

  • substitute_extremes (tuple[float, float], optional) – Substitute values for extreme LLRs; smaller and larger LLRs are clipped.

Returns:

Lower bound, upper bound, lower delta function values, and upper delta function values.

Return type:

tuple[float, float, np.ndarray, np.ndarray]

lir.algorithms.invariance_bounds.calculate_invariance_delta_functions(llrdata: LLRData, llr_threshold: ndarray) → tuple[ndarray, ndarray][source]

Calculate Invariance Verification delta functions for LRs at given thresholds.

Parameters:

  • llrdata (LLRData) – LLR data containing LLRs and ground-truth labels.

  • llr_threshold (np.ndarray) – Threshold LLR values.

Returns:

Lower and upper delta values evaluated for all thresholds.

Return type:

tuple[np.ndarray, np.ndarray]

lir.algorithms.invariance_bounds.plot_invariance_delta_functions(llrdata: LLRData, llr_threshold_range: tuple[float, float] | None = None, step_size: float = 0.001, ax: Axes | None = None) → None[source]

Plot Invariance Verification delta functions and LR bounds.

Parameters:

  • llrdata (LLRData) – LLR data containing LLRs and ground-truth labels.

  • llr_threshold_range (tuple[float, float] | None, optional) – Lower and upper limits for LLR thresholds to include in the figure.

  • step_size (float, optional) – Required accuracy on a base-10 logarithmic scale.

  • ax (plt.Axes | None, optional) – Matplotlib axes to plot into.

lir.algorithms.isotonic_regression module

class lir.algorithms.isotonic_regression.IsotonicCalibrator(add_misleading: int = 0)[source]

Bases: Transformer

Calculate LR from a score belonging to one of two distributions using isotonic regression.

Calculates a likelihood ratio of a score value, provided it is from one of two distributions. Uses isotonic regression for interpolation.

In contrast to IsotonicRegression, this class:

  • has an initialization argument that provides the option of adding misleading data points

  • outputs logodds instead of probabilities

Parameters:

add_misleading (int, optional) – Number of synthetic misleading points to add to reduce extreme LRs.

apply(instances: InstanceData) → LLRData[source]

Transform instances using the fitted isotonic regression model.

Parameters:

instances (InstanceData) – Instances to transform.

Returns:

Calibrated log-likelihood-ratio data.

Return type:

LLRData

fit(instances: InstanceData) → Self[source]

Fit the estimator on the given data.

Parameters:

instances (InstanceData) – Training instances.

Returns:

Fitted calibrator.

Return type:

Self

fit_apply(instances: InstanceData) → LLRData[source]

Fit and apply the calibrator to the given data.

Parameters:

instances (InstanceData) – Instances to fit and transform.

Returns:

Calibrated log-likelihood-ratio data.

Return type:

LLRData

class lir.algorithms.isotonic_regression.IsotonicRegression(*, y_min=None, y_max=None, increasing=True, out_of_bounds='nan')[source]

Bases: IsotonicRegression

Wrap SKlearn implementation to support infinite values.

Sklearn implementation IsotonicRegression throws an error when values are Inf or -Inf when in fact IsotonicRegression can handle infinite values. This wrapper around the sklearn implementation of IsotonicRegression prevents the error being thrown when Inf or -Inf values are provided.

fit(X: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], y: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], sample_weight: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | tuple | None = None) → IsotonicRegression[source]

Fit the model using X, y as training data.

X is stored for future use, as transform() needs X to interpolate new input data.

Parameters:

  • X (ArrayLike) – Training data with shape (n_samples,).

  • y (ArrayLike) – Training target with shape (n_samples,).

  • sample_weight (ArrayLike | tuple | None, optional) – Sample weights. If None, equal weights are used.

Returns:

Fitted estimator.

Return type:

IsotonicRegression

set_fit_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → IsotonicRegression

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → IsotonicRegression

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to score.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.

Returns:

self – The updated object.

Return type:

object

transform(T: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) → ndarray[source]

Transform new data by linear interpolation.

Parameters:

T (ArrayLike) – Data to transform.

Returns:

The transformed data.

Return type:

np.ndarray

lir.algorithms.kde module

class lir.algorithms.kde.KDECalibrator(bandwidth: Callable | str | float | tuple[float, float] | None = None)[source]

Bases: Transformer

Calculate LR from a score, belonging to one of two distributions using KDE.

Calculates a likelihood ratio of a score value, provided it is from one of two distributions. Uses kernel density estimation (KDE) for interpolation.

Parameters:

bandwidth (Callable | str | float | tuple[float, float] | None, optional) – Bandwidth specification for KDE.

apply(instances: InstanceData) → LLRData[source]

Provide calibrated LLRs as output.

Parameters:

instances (InstanceData) – Instances to calibrate.

Returns:

Calibrated log-likelihood-ratio data.

Return type:

LLRData

static bandwidth_silverman(X: ndarray, y: ndarray) → tuple[float, float][source]

Estimate bandwidths using Silverman’s rule of thumb.

Parameters:

  • X (np.ndarray) – Score array.

  • y (np.ndarray) – Label array.

Returns:

Bandwidth for class 0 and class 1.

Return type:

tuple[float, float]

fit(instances: InstanceData) → Self[source]

Fit the KDE model on the data.

Parameters:

instances (InstanceData) – Training instances.

Returns:

Fitted calibrator.

Return type:

Self

lir.algorithms.kde.compensate_and_remove_neginf_inf(log_odds: ndarray, y: ndarray) → tuple[ndarray, ndarray, float, float][source]

Remove infinite log-odds values and compute compensation factors.

Parameters:

  • log_odds (np.ndarray) – Array of log-odds.

  • y (np.ndarray) – Array of labels.

Returns:

Finite log-odds, corresponding labels, numerator compensator, and denominator compensator.

Return type:

tuple[np.ndarray, np.ndarray, float, float]

lir.algorithms.kde.parse_bandwidth(bandwidth: Callable | str | float | tuple[float, float] | None) → Callable[[Any, Any], tuple[float, float]][source]

Parse and return the corresponding bandwidth strategy based on input type.

Returns bandwidth as a tuple of two (optional) floats. Extrapolates a single bandwidth.

Parameters:

bandwidth (Callable | str | float | tuple[float, float] | None) – Bandwidth specification.

Returns:

Callable that computes bandwidths for class 0 and class 1.

Return type:

Callable[[Any, Any], tuple[float, float]]

lir.algorithms.llr_overestimation module

lir.algorithms.llr_overestimation.calc_fiducial_density_functions(data: ndarray, grid: ndarray, df_type: str = 'pdf', num_fids: int = 1000, smoothing_grid_fraction: float = 0.1, smoothing_sample_size_correction: float = 1, seed: None | int = None) → ndarray[source]

Calculate smoothed density functions of fiducial distributions for a dataset.

Parameters:

  • data (np.ndarray) – One-dimensional array of data points.

  • grid (np.ndarray) – One-dimensional array of equally spaced grid points.

  • df_type (str, optional) – Density function type: ‘pdf’ or ‘cdf’.

  • num_fids (int, optional) – Number of fiducial distributions to generate.

  • smoothing_grid_fraction (float, optional) – Fraction of grid points used as half window for smoothing.

  • smoothing_sample_size_correction (float, optional) – Sample-size correction factor for smoothing window size.

  • seed (int | None, optional) – Random seed for fiducial sampling.

Returns:

Density-function values evaluated on grid.

Return type:

np.ndarray

lir.algorithms.llr_overestimation.calc_llr_overestimation(llrs: ndarray, y: ndarray, num_fids: int = 1000, bw: tuple[str | float, str | float] = ('silverman', 'silverman'), num_grid_points: int = 100, alpha: float = 0.05, **kwargs: Any) → tuple[ndarray | None, ndarray | None, ndarray | None][source]

Calculate LLR-overestimation as a function of the system LLR.

The LLR-overestimation is defined as the log-10 of the ratio between

  1. the system LRs; the outputs of the LR-system, and

  2. the empirical LRs; the ratio’s between the relative frequencies of the H1-LLRs and H2-LLRs.

  • It quantifies the deviation from the requirement that ‘the LR of the LR is the LR’: the ‘LR-consistency’.

  • For a perfect LR-system, the LLR-overestimation is 0: the system and empirical LRs are the same.

  • A positive LLR-overestimation indicates that the system LRs are too high, compared to the empirical LRs.

  • An LLR-overestimation of +1 indicates that the system LRs are too high by a factor of 10.

  • An LLR-overestimation of -1 indicates that the system LRs are too low by a factor of 10.

  • The relative frequencies are estimated with KDE using Silverman’s rule-of-thumb for the bandwidths.

  • An interval around the LLR-overestimation can be calculated using fiducial distributions.

Parameters:

  • llrs (np.ndarray) – Log10 likelihood ratios as calculated by the LR system.

  • y (np.ndarray) – Corresponding labels (0 for H2/Hd, 1 for H1/Hp).

  • num_fids (int, optional) – Number of fiducial distributions used for intervals.

  • bw (tuple[str | float, str | float], optional) – Bandwidth specifications for KDEs of H1 and H2.

  • num_grid_points (int, optional) – Number of grid points used for calculating overestimation.

  • alpha (float, optional) – Confidence level used for the interval.

  • **kwargs (Any) – Additional arguments passed to calc_fiducial_density_functions.

Returns:

Tuple of LLR grid, overestimation best estimate, and overestimation interval.

Return type:

tuple[np.ndarray | None, np.ndarray | None, np.ndarray | None]

lir.algorithms.llr_overestimation.plot_llr_overestimation(llrdata: LLRData, num_fids: int = 1000, ax: Axes = <module 'matplotlib.pyplot' from '/home/runner/work/lir/lir/.venv/lib/python3.12/site-packages/matplotlib/pyplot.py'>, **kwargs: Any) → None[source]

Plot LLR-overestimation as a function of the system LLR.

The LLR-overestimation is defined as the log-10 of the ratio between

  1. the system LRs; the outputs of the LR-system, and

  2. the empirical LRs; the ratio’s between the relative frequencies of the H1-LLRs and H2-LLRs.

See documentation on calc_llr_overestimation() for more details on the LLR-overestimation.

An interval around the LLR-overestimation can be calculated using fiducial distributions. The average absolute LLR-overestimation can be used as single metric.

Parameters:

  • llrdata (LLRData) – LLR data containing LLRs and ground-truth labels.

  • num_fids (int, optional) – Number of fiducial distributions to base the interval on; use 0 for no interval.

  • ax (plt.Axes, optional) – Matplotlib axes to plot into.

  • **kwargs (Any) – Additional arguments passed to calc_llr_overestimation and/or calc_fiducial_density_functions.

lir.algorithms.logistic_regression module

class lir.algorithms.logistic_regression.FourParameterLogisticCalibrator[source]

Bases: Transformer

Calculate LR of a score, belonging to one of two distributions, using a logistic model.

Calculates a likelihood ratio of a score value, provided it is from one of two distributions. Depending on the training data, a 2-, 3- or 4-parameter logistic model is used.

apply(instances: InstanceData) → LLRData[source]

Apply the fitted calibrator to new data.

Parameters:

instances (InstanceData) – Instances to calibrate.

Returns:

Calibrated log-likelihood-ratio data.

Return type:

LLRData

fit(instances: InstanceData) → Self[source]

Fit the calibrator to data.

Parameters:

instances (InstanceData) – Training instances.

Returns:

Fitted calibrator.

Return type:

Self

class lir.algorithms.logistic_regression.LogisticRegression(output_model_parameters: bool = False, **kwargs: dict)[source]

Bases: BinaryClassifierTransformer

Apply LogisticRegression and output coefficients.

When not using the optional init parameters, the effect is equivalent to directly applying LogisticRegression.

The input should be FeatureData. The input for the model will be the features and the hypothesis labels. The output of apply() is a FeatureData object whose features are the probabilities of H1.

Parameters:

  • output_model_parameters (bool, optional) – Store the attributes logit_intercept and logit_coef in the output of apply(), and also send the values to the log.

  • **kwargs (dict) – Keyword arguments forwarded to LogisticRegression.

apply(instances: InstanceData) → FeatureData[source]

Apply the fitted model on the data.

class lir.algorithms.logistic_regression.LogitCalibrator(**kwargs: dict)[source]

Bases: Transformer

Calculate LR from a score, belonging to one of two distributions using logistic regression.

Calculates a likelihood ratio of a score value, provided it is from one of two distributions. Uses logistic regression for interpolation.

Infinite values in the input are ignored, except if they are misleading, which is an error.

Parameters:

**kwargs (dict) – Keyword arguments forwarded to sklearn.linear_model.LogisticRegression.

apply(instances: InstanceData) → LLRData[source]

Calculate LLR data from the fitted model.

Parameters:

instances (InstanceData) – Instances to calibrate.

Returns:

Calibrated log-likelihood-ratio data.

Return type:

LLRData

fit(instances: InstanceData) → Self[source]

Fit the model on the data.

Parameters:

instances (InstanceData) – Training instances.

Returns:

Fitted calibrator.

Return type:

Self

lir.algorithms.mcmc module

class lir.algorithms.mcmc.McmcLLRModel(distribution_h1: str, parameters_h1: dict[str, dict[str, float | int | str]] | None, distribution_h2: str, parameters_h2: dict[str, dict[str, float | int | str]] | None, bounding: Callable[[], ~lir.bounding.LLRBounder] | None=<class 'lir.algorithms.bayeserror.ELUBBounder'>, interval: tuple[float, float]=(0.05, 0.95), plot_path: Path | None = None, **mcmc_kwargs: Any)[source]

Bases: Transformer

Use Markov Chain Monte Carlo simulations to fit a statistical distribution for each of the two hypotheses.

Using samples from the posterior distributions of the model parameters, a posterior distribution of the LR is obtained. The median of this distribution is used as best estimate for the LR; a credible interval is also determined.

Parameters:

  • distribution_h1 (str) – Statistical distribution used to model H1.

  • parameters_h1 (dict[str, dict[str, float | int | str]] | None) – Parameter definitions and priors for the H1 distribution.

  • distribution_h2 (str) – Statistical distribution used to model H2.

  • parameters_h2 (dict[str, dict[str, float | int | str]] | None) – Parameter definitions and priors for the H2 distribution.

  • bounding (Callable[[], LLRBounder] | None, optional) – Bounding method factory to prevent over-extrapolation.

  • interval (tuple[float, float], optional) – Lower and upper bounds of the credible interval in range [0, 1].

  • plot_path (Path | None, optional) – If specified, path where distribution plots of the sampled distribution parameters are saved.

  • **mcmc_kwargs (Any) – Additional MCMC simulation settings passed to McmcModel.

apply(instances: InstanceData) → LLRData[source]

Apply the fitted model to the supplied instances.

Parameters:

instances (InstanceData) – Instances to transform.

Returns:

LLR estimates with median and credible interval columns.

Return type:

LLRData

fit(instances: InstanceData) → Self[source]

Fit the defined model to the supplied instances.

Parameters:

instances (InstanceData) – Training instances.

Returns:

Fitted model.

Return type:

Self

class lir.algorithms.mcmc.McmcModel(distribution: str, parameters: dict[str, dict[str, float | int | str]] | None, chain_count: int = 4, tune_count: int = 1000, draw_count: int = 1000, random_seed: int | None = None)[source]

Bases: object

Use Markov Chain Monte Carlo simulations to fit a statistical distribution.

Parameters:

  • distribution (str) – Statistical distribution used, for example ‘normal’ or ‘binomial’.

  • parameters (dict[str, dict[str, float | int | str]] | None) – Definitions of distribution parameters and their prior distributions.

  • chain_count (int, optional) – Number of parallel MCMC chains.

  • tune_count (int, optional) – Number of tune/warm-up/burn-in samples per chain.

  • draw_count (int, optional) – Number of posterior draws per chain.

  • random_seed (int | None, optional) – Random seed.

Notes

Supported distributions are betabinomial, binomial, and normal. Parameter names follow the PyMC naming conventions. The parameters dictionary maps each model parameter to a prior specification containing a prior key and the corresponding prior parameters.

fit(features: ndarray) → Self[source]

Draw samples from the posterior distributions of the parameters of a specified statistical distribution.

The posteriors are based on the specified prior distributions of these parameters and observed feature values.

Parameters:

features (np.ndarray) – Observed feature values used to update parameter priors.

Returns:

Fitted model with posterior samples.

Return type:

Self

transform(features: ndarray) → ndarray[source]

Get samples of the posterior distribution of the (log10) probability.

Use the samples of the posterior distributions of the parameters, in combination with the selected statistical distribution, to get samples of the posterior distribution of the (log10) probability, evaluated for specified feature values.

Parameters:

features (np.ndarray) – Feature values for which probabilities are calculated.

Returns:

Samples of log10 probabilities.

Return type:

np.ndarray

lir.algorithms.percentile_rank module

class lir.algorithms.percentile_rank.PercentileRankTransformer[source]

Bases: TransformerMixin

Compute the percentile rankings of a dataset, relative to another dataset.

Rankings are in range [0, 1]. Handling ties: the maximum of the ranks that would have been assigned to all the tied values is assigned to each value.

To compute the ranks of dataset Z relative to dataset X, fit() will create a ranking function for each feature using X. transform() then applies those per-feature ranking functions to Z.

Both fit() and transform() accept an array X with one row per instance, i.e. shape (n_samples, n_features). The number of features must match between fit() and transform().

If X contains paired measurements per instance (shape (n_samples, n_features, 2)), ranking is fitted and applied independently to the first and second measurement in the pair.

fit(X: ndarray, y: ndarray | None = None) → PercentileRankTransformer[source]

Fit the transformer model on the data.

Parameters:

  • X (np.ndarray) – Input array with shape (n_samples, n_features) or (n_samples, n_features, 2).

  • y (np.ndarray | None, optional) – Ignored; present for scikit-learn API compatibility.

Returns:

Fitted transformer.

Return type:

PercentileRankTransformer

transform(X: ndarray) → ndarray[source]

Use the fitted model to transform input data.

Parameters:

X (np.ndarray) – Input array with shape (n_samples, n_features) or (n_samples, n_features, 2).

Returns:

Percentile ranks with the same shape as input.

Return type:

np.ndarray