Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-10-04

Variance decomposition

Explains, with arithmetic that adds up, how much each segment of a dimension contributed to a metric's variance between the current period and the previous one — with no LLM.

On this page (9)

Engine: Deterministic (no LLM)


1. What it does

Takes a metric's variance between the current period and the previous one (the same pair the KPIs' Δ% uses) and decomposes it by dimension: how much each category, branch, channel or product contributed to the number going up or down — including the segments that appeared and the ones that left between one period and the other. The sum of the contributions adds up to the total variance; whatever doesn't add up shows as an explicit residual, it is never hidden.

2. Deterministic or LLM?

Deterministic. It is arithmetic (compensated summation so cents aren't lost in large figures, safe division, alphabetical tie-break). No language model decides what contributed. When the narrative in Dashboard insights or in a report uses this evidence, the LLM receives the finished arithmetic and only writes it up — it does not calculate.

3. Data sent and egress

None. The calculation runs on the product's server over the dashboard snapshot. If the evidence is later narrated by a capability that uses an LLM, the egress rules of that capability apply (Privacy, external sending and AI budget).

4. Privacy and retention

It operates on the dashboard's snapshot already filtered by RLS — whoever can't see a branch in the visual can't see it in the decomposition either. It works with categorical dimensions and numeric metrics; text never becomes a metric. It stores nothing beyond what the snapshot already keeps.

5. Tokens, cost and budget

Not applicable: zero cost, it does not consume the AI budget.

6. How to turn it on, who can use it and how to turn it off

In this version, there is no button in the interface. The engine is implemented and proven by tests, but the product surface — "explain the variance" inside the dashboard insights and the report narrative — is still under construction. There is nothing to turn on or off; when the surface arrives, it will follow the kill switch and the roles of the capability that displays it.

7. Refusals

  • No previous period (first snapshot): there is no variance to decompose; the capability does not invent a baseline.
  • Zero base: the percentage variance comes out empty and flagged, never Infinity or NaN; the absolute contribution remains valid.
  • Non-numeric values in the metric count as zero in both periods — the rule is symmetrical, so the reconciliation doesn't break.

8. Limitations and absence of causality

Contribution is not cause. Saying that "the SP branch accounted for 60% of the drop" is arithmetic over the data; it does not say why SP fell. The decomposition does not detect seasonality, does not compare against a target and does not cross dimensions (one dimension at a time). For metrics that are ratios (average ticket = revenue ÷ orders) there is a decomposition of its own, because adding up the contributions of a ratio as if they were absolute values would give the wrong result.

9. How to validate

  • Reference test set: reconciliation Σ contributions == total Δ within an explicit tolerance, tested in property-based style (many random inputs with a fixed seed); new segments and segments that left; zero base; determinism (same input → same output, byte for byte).
  • When the surface is available: add up the listed contributions by hand and compare with the Δ of the dashboard's KPI — it has to match, and the residual reported has to be what is missing.

Related links