Results and exports

Model Auditor keeps exact metric values in nested dataclasses and builds presentation-oriented pandas objects on demand.

Ordinary result hierarchy

evaluate_metrics() returns one ScoreEvaluation.

ScoreEvaluation
  name
  label
  metadata
  features: dict[str, FeatureEvaluation]

FeatureEvaluation
  name
  label
  excluded_n
  total_n
  levels: dict[str, LevelEvaluation]

LevelEvaluation
  name
  metrics: dict[str, LevelMetric]
  support

LevelMetric
  name
  label
  score
  interval
  status and interval diagnostics
  denominator, direction, and parameters

The features dictionary begins with the synthetic overall feature. Its one level is named Overall.

Registered features follow insertion order. For ordinary metric and error evaluation, non-categorical levels are string-normalized and normally follow pandas’ default lexicographic group order. Pandas categorical declarations provide the strongest explicit ordering contract. Score-distribution plots use a separate first-appearance rule for non-categorical levels.

Raw numeric access

The score and interval bounds are numeric values:

metric = (
    results.features["region"]
    .levels["North"]
    .metrics["auroc"]
)

point = metric.score
interval = metric.interval

Use this layer for calculations and validation, or call results.to_numeric_dataframe() for an unrounded long-form DataFrame containing these fields, support counts, exclusions, and provenance metadata.

Performance DataFrame exports

to_dataframe() at the score, feature, or level scope calls the level formatter.

A floating metric without CI becomes a decimal string. A metric with CI becomes one string containing the point and bounds. Integer counts use grouped integer formatting.

This makes the table concise for display but not directly numeric.

At score scope, the default row index is:

feature label
  → level name

At feature scope, rows are level names. At level scope, the result has one row.

metric_labels=True replaces machine names with human labels.

Categorical placeholders

For a categorical feature, every declared category appears even when it has no rows.

The placeholder:

• has one LevelMetric per selected metric;
• stores score=NaN; and
• has no interval.

This supports stable report layouts across cohorts. It also means table presence does not prove sample presence.

Notebook styling

style_dataframe() returns a pandas Styler over a display-formatted table.

Ordinary styling is neutral by default. With rank=True, it:

• ranks non-null values within each metric column;
• divides ranks into low, medium, and high tiers;
• omits count metrics by default;
• follows each metric’s declared higher/lower/none direction; and
• uses configurable background colors.

The calculation is relative to the current table’s rows. Changing feature scope can change tiers without changing any metric value.

Interval plots reuse result metadata

ScoreEvaluation.plot_metric_intervals() reads:

• metric labels;
• level insertion order;
• point estimates and intervals;
• overall comparator data; and
• support counts when selected.

The plot is therefore a view of the existing result object, not a new evaluation.

Error result hierarchy

evaluate_errors() returns ErrorEvaluation:

ErrorEvaluation
  name
  label
  threshold
  global_total_n
  groups
    tp → ScoreEvaluation
    tn → ScoreEvaluation
    fp → ScoreEvaluation
    fn → ScoreEvaluation
  support_data

Its to_dataframe() takes a different path and returns a numeric wide table. Do not generalize ordinary display-table behavior to this type.

Serialization choices

For a durable machine-readable record, extract a long-form table containing:

• score name;
• feature name and label;
• level;
• metric name and label;
• numeric point estimate;
• numeric lower bound;
• numeric upper bound; and
• package/source version.

Avoid using a formatted CSV as the sole analytical artifact. It is optimized for reading rather than lossless numerical round trips.