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

TermMeaning
VariationThe numeric change at the selected cell that Auto-Explain is trying to explain
Relative contributionThe contribution of a member to its parent’s variation, expressed as a percentage
Absolute contributionThe contribution of a member to the original top-level variation that Auto-Explain is trying to explain, expressed as a percentage
Recursion stepOne iteration of the algorithm at a given location: filter hierarchies, pick the best one, evaluate its members, and recurse into the significant ones
DepthThe number of recursion steps from the starting cell along the current path. Increments by 1 each time the algorithm drills into a significant member. Each branch of the recursion tree tracks depth independently
Significant memberA member whose relative contribution and absolute contribution both meet or exceed their respective thresholds
Root causeA location in the cube where the algorithm stops drilling. The algorithm stops when a parameter limit is reached, when the variation is too small (below min-variation-threshold), or when the variation is too spread out to explain further
EntropyA value between 0 and 1 measuring how evenly variation is distributed across members of a hierarchy level. 0 = concentrated in one member. 1 = evenly spread. Low entropy means the hierarchy is a useful explanation
Member countThe number of distinct member values in a hierarchy level (not the number of levels). Used to filter candidate hierarchies: those with fewer members are evaluated first

​
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:
HierarchyLevelsMembers
Region1: RegionNorth, South, East, West, Central
Product2: Category, Sub-categoryCategory: Electronics, Clothing, Food, Furniture, Sports (5 sub-categories each)
Measure: Sales Revenue. Observed variation: −1000. Parameters for this example:
ParameterValueNote
max-depth3Reduced here to show the depth-limit stopping behavior.
max-distinct-hierarchies10Default
max-entropy0.4Default
min-percentage-relative-contribution10%Default
min-percentage-absolute-contribution1%Default
include-opposite-contributorsfalseDefault
max-members-per-level-1Default (disabled)

​
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):
HierarchyMember countEntropyOutcome
Region50.15✓ Selected. Lowest entropy, below max-entropy 0.4.
Product / Category50.70✗ Not selected. Higher entropy.
Member distribution, Product / Category (not selected, shown to illustrate why entropy is high):
MemberRelativeAbsolute
Electronics24%24%
Clothing20%20%
Food19%19%
Furniture18%18%
Sports19%19%
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):
MemberRelativeAbsoluteOutcome
East82%82%✓ Significant, recurse
North8%8%✗ Below min-percentage-relative-contribution 10%, skipped
South5%5%✗ Skipped
West4%4%✗ Skipped
Central1%1%✗ Skipped
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:
HierarchyMember countEntropyOutcome
Product / Category50.20✓ Selected. Below max-entropy 0.4.
Member evaluation, Product / Category within East:
MemberRelativeAbsoluteOutcome
Electronics70%57%✓ Significant, recurse
Clothing15%12%✓ Significant, recurse
Food8%7%✗ Below min-percentage-relative-contribution 10%, skipped
Furniture5%4%✗ Skipped
Sports2%2%✗ Skipped
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:
HierarchyMember countEntropyOutcome
Product / Sub-category5 (in scope at this location)0.12✓ Selected. Below max-entropy 0.4.
Member evaluation, Product / Sub-category within East / Electronics:
MemberRelativeAbsoluteOutcome
Smartphones80%46%✓ Significant, recurse to depth 3. At depth 3, the depth check fires (depth = max-depth) and records this as a root cause.
Laptops12%7%✓ Significant, recurse to depth 3. At depth 3, the depth check fires (depth = max-depth) and records this as a root cause.
Tablets5%3%✗ Skipped
Accessories2%1%✗ Skipped
Other1%1%✗ Skipped

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

Hierarchy selection:
HierarchyMember countEntropyOutcome
Product / Sub-category5 (in scope at this location)0.65✗ Above max-entropy 0.4. Variation too spread out.
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:
Root causePathStopped by
SmartphonesEast → Electronics → Smartphonesmax-depth reached
LaptopsEast → Electronics → Laptopsmax-depth reached
East / ClothingEast → Clothingmax-entropy exceeded. Variation too spread out to drill further.
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.