> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How Auto-Explain works
> How the Auto-Explain recursive tree-search algorithm finds root causes, the key terms (variation, contribution, entropy, depth), the algorithm steps, and a worked example.
### 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](./configuration#how-to-tune-the-constants).
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](./setup-java) or
[Set up Auto-Explain in Python](./setup-python), then [Configure Auto-Explain](./configuration) to
tune the constants used below.
## Key terms
| Term | Meaning |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Variation | The numeric change at the selected cell that Auto-Explain is trying to explain |
| Relative contribution | The contribution of a member to its parent's variation, expressed as a percentage |
| Absolute contribution | The contribution of a member to the original top-level variation that Auto-Explain is trying to explain, expressed as a percentage |
| Recursion step | One iteration of the algorithm at a given location: filter hierarchies, pick the best one, evaluate its members, and recurse into the significant ones |
| Depth | The 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 member | A member whose relative contribution and absolute contribution both meet or exceed their respective thresholds |
| Root cause | A 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 |
| Entropy | A 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 count | The 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:**
| Hierarchy | Levels | Members |
| --------- | ------------------------- | -------------------------------------------------------------------------------- |
| Region | 1: Region | North, South, East, West, Central |
| Product | 2: Category, Sub-category | Category: Electronics, Clothing, Food, Furniture, Sports (5 sub-categories each) |
**Measure:** Sales Revenue. **Observed variation: −1000.**
**Parameters for this example:**
| Parameter | Value | Note |
| -------------------------------------- | ----- | ------------------------------------------------------- |
| `max-depth` | 3 | Reduced here to show the depth-limit stopping behavior. |
| `max-distinct-hierarchies` | 10 | Default |
| `max-entropy` | 0.4 | Default |
| `min-percentage-relative-contribution` | 10% | Default |
| `min-percentage-absolute-contribution` | 1% | Default |
| `include-opposite-contributors` | false | Default |
| `max-members-per-level` | -1 | Default (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):
| Hierarchy | Member count | Entropy | Outcome |
| ------------------ | ------------ | -------- | ---------------------------------------------------- |
| Region | 5 | **0.15** | ✓ Selected. Lowest entropy, below `max-entropy` 0.4. |
| Product / Category | 5 | 0.70 | ✗ Not selected. Higher entropy. |
**Member distribution, Product / Category** (not selected, shown to illustrate why entropy is high):
| Member | Relative | Absolute |
| ----------- | -------- | -------- |
| Electronics | 24% | 24% |
| Clothing | 20% | 20% |
| Food | 19% | 19% |
| Furniture | 18% | 18% |
| Sports | 19% | 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):
| Member | Relative | Absolute | Outcome |
| ------- | -------- | -------- | ----------------------------------------------------------- |
| East | 82% | 82% | ✓ Significant, recurse |
| North | 8% | 8% | ✗ Below `min-percentage-relative-contribution` 10%, skipped |
| South | 5% | 5% | ✗ Skipped |
| West | 4% | 4% | ✗ Skipped |
| Central | 1% | 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:**
| Hierarchy | Member count | Entropy | Outcome |
| ------------------ | ------------ | -------- | ------------------------------------ |
| Product / Category | 5 | **0.20** | ✓ Selected. Below `max-entropy` 0.4. |
**Member evaluation, Product / Category within East:**
| Member | Relative | Absolute | Outcome |
| ----------- | -------- | -------- | ----------------------------------------------------------- |
| Electronics | 70% | 57% | ✓ Significant, recurse |
| Clothing | 15% | 12% | ✓ Significant, recurse |
| Food | 8% | 7% | ✗ Below `min-percentage-relative-contribution` 10%, skipped |
| Furniture | 5% | 4% | ✗ Skipped |
| Sports | 2% | 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:**
| Hierarchy | Member count | Entropy | Outcome |
| ---------------------- | ----------------------------- | -------- | ------------------------------------ |
| Product / Sub-category | 5 (in scope at this location) | **0.12** | ✓ Selected. Below `max-entropy` 0.4. |
**Member evaluation, Product / Sub-category within East / Electronics:**
| Member | Relative | Absolute | Outcome |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Smartphones | 80% | 46% | ✓ Significant, recurse to depth 3. At depth 3, the depth check fires (`depth = max-depth`) and records this as a root cause. |
| Laptops | 12% | 7% | ✓ Significant, recurse to depth 3. At depth 3, the depth check fires (`depth = max-depth`) and records this as a root cause. |
| Tablets | 5% | 3% | ✗ Skipped |
| Accessories | 2% | 1% | ✗ Skipped |
| Other | 1% | 1% | ✗ Skipped |
### Depth 2, Branch B: East → Clothing (variation = −123)
**Hierarchy selection:**
| Hierarchy | Member count | Entropy | Outcome |
| ---------------------- | ----------------------------- | -------- | ---------------------------------------------------- |
| Product / Sub-category | 5 (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 cause | Path | Stopped by |
| --------------- | -------------------------------- | ------------------------------------------------------------------ |
| Smartphones | East → Electronics → Smartphones | `max-depth` reached |
| Laptops | East → Electronics → Laptops | `max-depth` reached |
| East / Clothing | East → Clothing | `max-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.
## Related reading
* [Configure Auto-Explain](./configuration) to tune the constants used above
* [How to use Auto-Explain](../../../user-guide/auto-explain) in the Atoti UI