Skip to main content

​
Atoti Intelligence Essentials

This is part of the Atoti Intelligence Essentials offer.
Auto-Explain uses a recursive tree search algorithm. Understanding how it works clarifies the effect of each configuration parameter. Starting from the selected cell, the algorithm identifies the best hierarchy to explain the current variation. It then recurses into the most significant members of that hierarchy.
To follow along, first enable Auto-Explain: see Set up Auto-Explain in Java or Set up Auto-Explain in Python, then Configure Auto-Explain to tune the constants used below.

​
Key terms

​
Algorithm steps

At each recursion step, starting from the selected cell:
  1. Check depth: if depth = max-depth, record this location as a root cause and stop this branch.
  2. Check variation: if |variation| < min-variation-threshold, record this location as a root cause and stop this branch. The variation is now negligible.
  3. Filter candidate hierarchies: if max-members-per-level != -1, exclude any hierarchy whose member count at the current location exceeds this value. Then keep only the hierarchies with the smallest member counts, up to max-distinct-hierarchies. This limits query volume without losing quality (hierarchies with fewer members are less expensive to evaluate).
  4. Compute entropy: for each candidate hierarchy, compute the Shannon entropy of variation across its members at this location.
  5. Select the best hierarchy: the one with the lowest entropy.
  6. Check entropy: if the best entropy exceeds max-entropy, the variation is too spread out to explain further. Record the current location as a root cause and stop this branch.
  7. Evaluate members: for each member of the selected hierarchy, compute relative and absolute contributions.
    • Skip any member below either threshold.
    • If no member meets both thresholds, record the current location as a root cause and stop this branch.
  8. Recurse: for each significant member, go back to step 1 with this member as the new context and depth incremented by 1.

​
Worked example

Values in this example are illustrative and have been rounded for clarity.
Cube setup: Measure: Sales Revenue. Observed variation: −1000. Parameters for this example:

​
Depth 0: starting cell (variation = −1000)

Variation check: |−1000| exceeds min-variation-threshold (1e-6). Analysis proceeds. Hierarchy selection (max-distinct-hierarchies = 10, both qualify): Member distribution, Product / Category (not selected, shown to illustrate why entropy is high): Variation is spread roughly evenly across all 5 categories. This produces high entropy (0.70). Product / Category does not explain the drop well at this level. Member evaluation, Region (selected): Variation is concentrated almost entirely in East. This produces low entropy (0.15). Region is a much better explanation. The algorithm recurses into East (depth 0 to 1).

​
Depth 1: East (variation = −820)

Region has only 1 level and is at its leaf. Only Product / Category is available. Hierarchy selection: Member evaluation, Product / Category within East: The algorithm recurses into Electronics (Branch A) and Clothing (Branch B), each at depth 2 independently.

​
Depth 2, Branch A: East → Electronics (variation = −570)

Product / Sub-category is now available (deeper level of the Product hierarchy). Hierarchy selection: Member evaluation, Product / Sub-category within East / Electronics:

​
Depth 2, Branch B: East → Clothing (variation = −123)

Hierarchy selection: The drop in Clothing is distributed across all sub-categories with no dominant contributor. No hierarchy passes the entropy threshold. East / Clothing is recorded as a root cause. This branch stops here. Root causes identified:
Branch A members (Smartphones, Laptops) are significant at depth 2 and are recursed into. The max-depth check fires at the start of depth 3 and records them as root causes. Branch B stops at depth 2 because max-entropy is exceeded. Each branch follows its own path and can stop for different reasons.