Plotting API

Model Auditor exposes two Matplotlib surfaces and one renderer-independent hierarchy compiler.

Optional dependencies

Install Matplotlib for the first two APIs:

python -m pip install matplotlib

Install a renderer such as Plotly separately for hierarchy output:

python -m pip install plotly

ScoreEvaluation.plot_metric_intervals

plot_metric_intervals(
    metric: str,
    feature_names: list[str] | None = None,
    include_overall: bool = True,
    rotate_plots: bool = False,
    include_sample_size: bool = True,
    include_class_balance: bool = True,
) -> dict[str, tuple[Figure, Axes]]

Metric selection

Resolution order:

1. exact internal metric-name match;
2. display-label match across selected features.

An unknown selector raises ValueError listing available names and labels.

Interval feature selection

• None: every result feature except synthetic overall.
• explicit list: validates names and preserves list order.
• explicit overall: filtered out as a standalone figure.
• no remaining non-overall feature: ValueError.

Plottable levels

A level is plottable when:

• score is not NaN;
• interval is not None; and
• both bounds are not NaN.

Infinite bounds are not explicitly filtered.

A selected feature with no plottable level raises ValueError.

Overall comparator

When enabled and available, overall / Overall is prepended to each feature’s levels. It is skipped when its metric or interval is unavailable.

Orientation

Default:

metric value on x-axis
levels on y-axis

With rotate_plots=True:

levels on x-axis
metric value on y-axis

Annotations

Support extraction checks direct metric keys:

n
n_pos
n_neg

It can derive truth-class counts and total N from:

n_tp
n_tn
n_fp
n_fn

Missing values produce NA annotation fragments.

Figure size

Width is fixed at 8 inches. Height is:

max(2.5, number of plotted levels × 0.55)

Auditor.plot_score_distributions

plot_score_distributions(
    score_name: str,
    feature_names: list[str] | None = None,
    bins: int | str = 30,
    density: bool = True,
    split_classes: bool = False,
) -> dict[str, tuple[Figure, np.ndarray]]

Data requirements

• internal data exists;
• at least one feature is registered;
• score is registered;
• selected feature and score columns contain at least one jointly non-null row.

An outcome is required only for split_classes=True; metrics are not required.

Distribution feature selection

• None: every registered feature in registration order.
• explicit list: validates names and preserves caller order.
• an explicit empty list performs no feature loop and returns an empty dictionary.

Level order

• categorical: declared order, observed levels only;
• non-categorical: first-appearance order after string conversion.

This non-categorical order intentionally differs from ordinary metric and error evaluation, which use pandas’ default sorted group order.

Histograms

• one vertical axis per level;
• shared x-axis;
• shared bin edges within the feature;
• bin edges computed from the complete non-null feature slice;
• integer and string bin specifications are type-annotated, while the implementation also forwards precomputed edge arrays to NumPy;
• density or raw counts according to density;
• bottom axis labeled with score label or name;
• figure title combines feature and score labels.

The returned axes are normalized with np.atleast_1d.

With split_classes=True, each level overlays negative and positive truth-class histograms. The outcome must already be registered, binary, and complete. With density=True, each nonempty class is normalized separately.

HierarchyPlotter

Import:

from model_auditor.plotting import HierarchyPlotter

Constructor

HierarchyPlotter() -> None

Initial state:

Attribute	Initial value
features	None
data	None
aggregator	"median"
score	None

set_data

set_data(
    data: pd.DataFrame,
) -> None

Stores the supplied DataFrame reference. compile() later obtains a copy through its preparation helper.

set_features

set_features(
    features: Hierarchy | list[str],
) -> None

A list produces one HLevel([HItem(name=...)]) per column.

Any other type raises ValueError.

An empty list or empty Hierarchy does not produce a usable compile tree.

set_aggregator

set_aggregator(
    method: str | Callable,
) -> None

String methods are forwarded to pandas aggregation on the score Series.

Callable methods receive a DataFrame branch and must return one scalar.

Validation occurs during compile().

set_score

set_score(
    name: str,
    label: str | None = None,
    threshold: ThresholdSpec | None = None,
) -> None

Stores an AuditorScore. The threshold is retained but not used by v0.1.16 hierarchy compilation.

compile

compile(
    container: str,
) -> PlotterData

Requires features and data.

When a score exists:

• root color is the root aggregate;
• child colors are branch aggregates.

Without a score:

• emits a warning;
• colors are None.

Returns PlotterData.

Hierarchy schemas

The dataclass signatures below use field(default_factory=...) from dataclasses.

Import:

from model_auditor.plotting.schemas import (
    HItem,
    HLevel,
    Hierarchy,
    PlotterData,
)

PlotterData

@dataclass
class PlotterData:
    labels: list = field(default_factory=list)
    ids: list = field(default_factory=list)
    parents: list = field(default_factory=list)
    values: list = field(default_factory=list)
    colors: list = field(default_factory=list)

add(label, node_id, parent, value, color=None) appends one node to every array.

HItem

@dataclass
class HItem:
    name: str
    query: str | None = None

The query is a pandas expression used as an all-rows branch predicate.

HLevel

@dataclass
class HLevel:
    items: list[HItem] = field(default_factory=list)

Multiple valid items at one level are concatenated into a temporary composite feature.

Hierarchy

@dataclass
class Hierarchy:
    levels: list[HLevel] = field(default_factory=list)

Levels are traversed from root to leaf.