lir.plotting package

class lir.plotting.Canvas(ax: Axes)[source]

Bases: object

Representation of an empty canvas, to be used in plotting multiple visualizations.

Parameters:

ax (Axes) – Matplotlib axes instance used by wrapped plotting methods.

ax

Matplotlib axes instance used by wrapped plotting methods.

Type:

Axes

ece

Method to plot expected calibration error (ECE) on this canvas.

Type:

Callable[…, Any]

lr_histogram

Method to plot a histogram of likelihood ratios on this canvas.

Type:

Callable[…, Any]

nbe

Method to plot the Bayes error rate (NBE) on this canvas.

Type:

Callable[…, Any]

pav

Method to plot the Pool Adjacent Violators (PAV) transformation on this canvas.

Type:

Callable[…, Any]

score_distribution

Method to plot the distribution of scores on this canvas.

Type:

Callable[…, Any]

tippett

Method to plot Tippett plots on this canvas.

Type:

Callable[…, Any]

llr_interval

Method to plot LLR intervals on this canvas.

Type:

Callable[…, Any]

title(label: str, **kwargs: Any) → Any[source]

Set the title of the axes (wrapper for set_title).

Parameters:

  • label (str) – Title text.

  • **kwargs (Any) – Additional keyword arguments forwarded to Axes.set_title.

Returns:

Return value from Axes.set_title.

Return type:

Any

lir.plotting.axes(savefig: PathLike | str | None = None, show: bool | None = None) → Iterator[Canvas][source]

Create a plotting context.

Parameters:

  • savefig (PathLike | str | None, optional) – File path to save the figure on context exit.

  • show (bool | None, optional) – Whether to display the figure on context exit.

Returns:

Iterator yielding a Canvas instance for plotting.

Return type:

Iterator[Canvas]

Examples

with axes() as ax:
    ax.pav(llrdata)
lir.plotting.histogram(ax: Axes, x: ndarray, labels: ndarray | None, bins: int = 20, weighted: bool = True, x_label: str = '') → None[source]

Plot x as a histogram, optionally separated by class labels.

This class is mainly used as a helper for plotting LLR or score histograms.

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • x (np.ndarray) – The array of values to plot.

  • labels (np.ndarray | None) – The array of class labels for each value in x.

  • bins (int) – Number of bins to divide scores into (default: 20).

  • weighted (bool) – If y-axis should be weighted for frequency within each class (default: True).

  • x_label (str) – Label for the x-axis (default: ‘’).

lir.plotting.llr_interval(ax: Axes, llrdata: LLRData) → None[source]

Plot the LRs on the x-axis, with the relative interval score on the y-axis.

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • llrdata (LLRData) – The LLRData object containing the likelihood ratios and interval scores.

lir.plotting.lr_histogram(ax: Axes, llrdata: LLRData, bins: int = 20, weighted: bool = True) → None[source]

Plot the 10log LRs.

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • llrdata (LLRData) – The LLRData object containing likelihood ratios and labels.

  • bins (int) – Number of bins to divide scores into (default: 20).

  • weighted (bool) – If y-axis should be weighted for frequency within each class (default: True).

lir.plotting.pav(ax: Axes, llrdata: LLRData, add_misleading: int = 0, show_scatter: bool = True) → None[source]

Generate a plot of pre-calibrated versus post-calibrated LRs using Pool Adjacent Violators (PAV).

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • llrdata (LLRData) – The LLRData object containing likelihood ratios and labels.

  • add_misleading (int, optional) – Number of misleading evidence points to add on both sides (default: 0).

  • show_scatter (bool, optional) – If True, show individual LRs (default: True).

lir.plotting.savefig(path: str) → _GeneratorContextManager[Canvas][source]

Create a plotting context and write the figure to a file when the context exits.

Parameters:

path (str) – Path to the output file. The figure is written as a PNG image.

Returns:

Context manager yielding a Canvas and saving on exit.

Return type:

_GeneratorContextManager[Canvas]

Examples

with savefig(path) as ax:
    ax.pav(llrdata)

A call to savefig() is equivalent to calling axes() with savefig=path.

lir.plotting.score_distribution(ax: Axes, llrdata: LLRData, bins: int = 20, weighted: bool = True) → None[source]

Plot the distributions of scores calculated by the (fitted) LR system.

If weighted is True, the y-axis represents the probability density within the class. Otherwise, they-axis shows the number of instances.

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • llrdata (LLRData) – The LLRData object containing the scores and labels. Must have scores available.

  • bins (int) – Number of bins to divide scores into (default: 20).

  • weighted (bool) – If y-axis should be the probability density within each class, instead of counts (default: True).

lir.plotting.score_to_llr(ax: Axes, llrdata: LLRData) → None[source]

Plot intermediate scores vs final LLRs, colored by hypothesis.

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • llrdata (LLRData) – The LLRData object containing likelihood ratios and labels. Must have scores available. If labels are present, use them in the plots to color the points by hypothesis. If not, plot all points in the same color.

lir.plotting.show() → _GeneratorContextManager[Canvas][source]

Create a plotting context and show the figure when the context exits.

Returns:

Context manager yielding a Canvas and showing the figure on exit.

Return type:

_GeneratorContextManager[Canvas]

Examples

with show() as ax:
    ax.pav(llrdata)

A call to show() is equivalent to calling axes() with show=True.

lir.plotting.tippett(ax: Axes, llrdata: LLRData, plot_type: int = 1) → None[source]

Plot empirical cumulative distribution functions of same-source and different-sources LRs.

Parameters:

  • ax (Axes) – The matplotlib axes object to plot on.

  • llrdata (LLRData) – The LLRData object containing likelihood ratios and labels.

  • plot_type (int) – Must be either 1 or 2 (default: 1). In type 1 both curves show proportion of lrs greater than or equal to the x-axis value, while in type 2 the curve for same-source shows the proportion of lrs smaller than or equal to the x-axis value.

Submodules

lir.plotting.expected_calibration_error module

Empirical cross-entropy (ECE).

The discrimination and calibration of the LRs reported by some systems can also be measured separately. The empirical cross entropy (ECE) plot is a graphical way of doing this.

ECE is computed as the average of:

  • -P(Hp) * log2(P(Hp | LR_i)) over all LR_i for which Hp is true, and

  • -P(Hd) * log2(P(Hd | LR_i)) over all LR_i for which Hd is true.

References

Ramos, D. Forensic Evidence Evaluation Using Automatic Speaker Recognition Systems. Ph.D. thesis, Universidad Autónoma de Madrid.

Robertson, B., Vignaux, G. A., & Berger, C. (2016). Interpreting Evidence: Evaluating Forensic Science in the Courtroom (2nd ed.), pp. 96–97.

lir.plotting.expected_calibration_error.calculate_ece(lrs: ndarray, y: ndarray, priors: ndarray) → ndarray[source]

Calculate empirical cross-entropy (ECE) of a set of LRs and corresponding ground-truth labels.

An entropy is calculated for each element of priors.

Parameters:

  • lrs (np.ndarray) – Array of likelihood ratios.

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

  • priors (np.ndarray) – Array of prior probabilities for class 1 (values in the range [0, 1]).

Returns:

Array of entropy values with the same length as priors.

Return type:

np.ndarray

lir.plotting.expected_calibration_error.plot_ece(ax: Any, llrdata: LLRData, log_prior_odds_range: tuple[float, float] = (-3, 3), show_pav: bool = True, ylim: str = 'neutral') → None[source]

Generate an ECE plot for a set of LRs and corresponding ground-truth labels.

The x-axis shows the log prior odds of a sample being drawn from class 1. The y-axis shows the expected cost (cross-entropy) for:

  1. A non-informative system (dotted line),

  2. The provided LR values (solid line), and

  3. The LR values after PAV transformation (Pool Adjacent Violators; dashed line).

Parameters:

  • ax (matplotlib.axes.Axes) – Matplotlib axes to plot into.

  • llrdata (LLRData) – LLR data containing LLR values and corresponding labels.

  • log_prior_odds_range (tuple[float, float], optional) – Range of log prior odds shown on the x-axis, given as (min, max).

  • show_pav (bool, optional) – Whether to include the PAV-transformed LRs in the plot.

  • ylim ({"neutral", "zoomed"}, optional) –

    Y-axis scaling mode:

    • "neutral": Lower limit is 0; upper limit is set slightly above the maximum of the non-informative reference.

    • "zoomed": Lower limit is 0; upper limit is set to approximately 10% above the maximum ECE value of the LRs (this may clip part of the non-informative reference line).