Hierarchical plot data

HierarchyPlotter is separate from Auditor metric evaluation. It summarizes nested group counts and optional continuous-score aggregates into five parallel arrays.

Output schema

PlotterData contains:

Field	Meaning
labels	Display text for every node
ids	Unique node identifiers
parents	Parent node ID, or an empty string for the root
values	Row count for each node
colors	Optional score aggregate for each node

All arrays grow together through PlotterData.add().

The root node uses the container string as both label and ID. Descendant IDs concatenate parent ID and level value with $.

Flat hierarchy

Passing:

plotter.set_features(
    [
        "region",
        "age_group",
        "device_type",
    ]
)

creates one hierarchy level per column.

Each branch groups the current DataFrame slice by the current column, records a node, and recurses into the next column’s slice.

This is a joint nested hierarchy, unlike ordinary Auditor features, which are evaluated as separate marginal dimensions.

Custom hierarchy

A Hierarchy contains ordered HLevel objects. Each level contains one or more HItem objects.

An item has:

• a column name; and
• an optional pandas expression query.

At a current branch, an item is valid when:

• it has no query; or
• its query evaluates true for every row in the branch.

This enables branch-specific next columns after an earlier level has made the branch homogeneous.

When several items are valid at one level, their column values are concatenated with & into a temporary composite feature.

When no item is valid, recursion stops for that branch.

Values and colors

values always contain node row counts.

If a score is configured:

• a string aggregator is applied to the score column;
• a callable aggregator receives the full branch DataFrame; and
• its scalar result is stored in colors.

The default aggregator is "median".

If no score is configured, the compiler warns and appends None colors.

Threshold independence

Although set_score() accepts a threshold specification, v0.1.16 never uses it during hierarchy compilation.

The output therefore does not represent:

• positive prediction counts;
• thresholded rates;
• sensitivity or specificity;
• confusion groups; or
• conditional-threshold policy.

It represents counts plus an aggregate of the continuous score.

Pandas grouping behavior

The compiler groups with observed=False. Categorical columns can include unused categories. Remove unused categories when zero-count hierarchy nodes are undesirable.

Null group values are omitted by default groupby behavior.

Rendering boundary

Model Auditor does not depend on Plotly and does not return a Plotly figure. This boundary keeps the data compiler renderer-agnostic, but it also means the caller owns:

• branch-value semantics;
• color scales;
• hover text;
• missing colors;
• zero-count nodes;
• chart accessibility; and
• output export.