Metric Comparison

The metric comparison helpers reconcile the per-cycle metrics reported by source files with the values recomputed via the formula engine. They align cycles, apply configurable absolute and relative tolerances, and return structured diagnostics ready for CLI and notebook consumption.

Overview

from batteryproc import (
    ComparisonConfig,
    MetricTolerance,
    compare_metric_frames,
)

result = compare_metric_frames(
    file_df=file_metrics_df,
    recomp_df=recomputed_df,
    config=ComparisonConfig(
        metrics=("charge_mAh", "discharge_mWh"),
        tolerances={
            "charge_mAh": MetricTolerance(absolute=0.05, relative=0.01),
            "discharge_mWh": MetricTolerance(absolute=0.1, relative=0.02),
        },
    ),
)

compare_metric_frames performs the following steps:

• normalises the cycle column (cycle_index by default) and creates an inner join of cycles present in both frames;
• records cycles missing on either side;
• computes diffs, tolerance flags, and per-metric aggregates;
• returns a CompareResult containing per-metric tables and high-level summaries.

Inputs

The helper expects two DataFrames:

1. file_df: per-cycle metrics derived from the source instrument file.
2. recomp_df: per-cycle metrics recomputed via batteryproc.formulas.

Both must expose:

• a common cycle column (default name cycle_index, override with ComparisonConfig.cycle_column);
• the metric columns listed in the configuration.

Configuration

ComparisonConfig controls which metrics are compared, how tolerances are applied, and how null values are handled.

Field	Description
metrics	Ordered tuple of metric column names to compare.
tolerances	Mapping of metric name to MetricTolerance (absolute + relative bounds).
default_tolerance	Optional fallback MetricTolerance when a metric is not in the mapping.
cycle_column	Column name used to align cycles (default: "cycle_index").
null_policy	Controls NaN handling: SKIP_ROW (ignore rows with nulls) or FAIL_ON_ANY_NULL (treat as failing comparisons).

When both absolute and relative tolerances are provided, the comparison applies the absolute rule first. Relative tolerances only activate when the magnitude of the values exceeds the absolute tolerance threshold to avoid divide-by-zero artefacts around zero.

Outputs

CompareResult contains:

• per_metric: dictionary mapping metric names to tidy per-cycle tables with columns [cycle_index, file_value, recomputed_value, diff, within_tolerance].
• summaries: dictionary mapping metric names to CompareSummary, capturing compared/flagged counts, missing cycle counts, and the size of the intersection before null filtering.
• missing_cycles_in_file / missing_cycles_in_recomputed: sorted lists of cycle indices that exist on only one side of the comparison.

Use this information to flag mismatches, drive CLI warnings, or feed reporting dashboards. For additional diagnostics on the formula outputs themselves, see the Formulas Engine reference.