> ## 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 to configure Auto-Explain
> How to configure Auto-Explain in `application.yaml` for an Atoti Java project, covering per-cube hierarchy inclusion and exclusion, algorithm constants such as `max-depth`, `max-entropy`, contribution thresholds, and a worked example of the recursive tree search.
### Atoti Intelligence Essentials
This is part of the Atoti Intelligence Essentials offer.
Auto-Explain configuration controls which hierarchies are analyzed, the sensitivity to variations,
and the recursion depth.
Proper configuration avoids unnecessary query volume and keeps analysis results focused.
This page explains how to configure hierarchies to include or exclude, how to tune the algorithm
constants, and how the algorithm uses those constants to find root causes.
### Prerequisites
Auto-Explain must be enabled before adding configuration.
See [How to set up Auto-Explain](./setup) for setup instructions.
## Configuration file
Add Auto-Explain configuration to the application configuration file. The configuration block is
per-cube and can be repeated to configure multiple cubes.
The following example shows all available configuration options in `application.yaml`:
```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
atoti:
ai:
autoexplain:
cube-configs:
- cube-name: cube-name
auto-explain-configuration:
measure-naming-config:
parent: "Cube__PARENT"
sibling: "Cube__SIBLING"
marginal: "Cube__MARGINAL"
absolute-contribution: "Cube__ABSOLUTE_CONTRIBUTION"
relative-contribution: "Cube__RELATIVE_CONTRIBUTION"
excluded-hierarchies:
- hierarchy-name: hierarchyName1
dimension-name: dimensionName1
- hierarchy-name: hierarchyName2
dimension-name: dimensionName2
excluded-measure-hierarchies:
measureName1:
- hierarchy-name: hierarchyName3
dimension-name: dimensionName3
included-hierarchies:
- hierarchy-name: hierarchyName4
dimension-name: dimensionName4
included-measure-hierarchies:
measureName1:
- hierarchy-name: hierarchyName5
dimension-name: dimensionName5
constants-config:
max-depth: 15
max-distinct-hierarchies: 10
max-entropy: 0.4
min-percentage-absolute-contribution: 1
min-percentage-relative-contribution: 10
min-variation-threshold: 0.000001
include-opposite-contributors: false
max-members-per-level: -1
```
## Configuration parameters
The following table describes each configuration parameter:
| Parameter name | Description |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cube-name` | Name of the cube to configure Auto-Explain for. |
| `auto-explain-configuration` | Configuration of the parameters of Auto-Explain. |
| `auto-explain-configuration.measure-naming-config` | Lists the measures computed by Auto-Explain and their default names. Default names are shown in the configuration example in [Configuration file](#configuration-file). Specify only the measures whose names need to change. |
| `auto-explain-configuration.excluded-hierarchies` | List of hierarchies to exclude for all Auto-Explain analyses on all cube measures. |
| `auto-explain-configuration.excluded-measure-hierarchies` | For each measure, a list of hierarchies to exclude for all Auto-Explain analyses on that specific measure. |
| `auto-explain-configuration.included-hierarchies` | List of hierarchies to include for all Auto-Explain analyses on all cube measures. When declared, only these hierarchies will be used for analysis. |
| `auto-explain-configuration.included-measure-hierarchies` | For each measure, a list of hierarchies to include for all Auto-Explain analyses on that specific measure. When declared, only these hierarchies will be used for analysis. |
| `auto-explain-configuration.constants-config` | Set of constants that control how the algorithm explores the cube. See [How to tune the constants](#how-to-tune-the-constants) for the list of available parameters and tuning guidance. |
A hierarchy is identified by its hierarchy-name and its dimension-name, as usual in Atoti.
### Hierarchy exclusion priority
Auto-Explain removes any hierarchy listed in `excluded-hierarchies` or
`excluded-measure-hierarchies` from analysis.
Exclusion applies even if the same hierarchy also appears in `included-hierarchies` or
`included-measure-hierarchies`.
For example, if `Region / Country` appears in both `included-hierarchies` and
`excluded-hierarchies`, it is excluded.
## How to tune the constants
The following parameters are nested under `constants-config` and control how the algorithm explores
the cube to find root causes:
| Parameter | Description | Default |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `max-depth` | Maximum recursion depth: how many levels the algorithm can drill into along a single path before declaring it a root cause. | `15` |
| `max-distinct-hierarchies` | Maximum number of hierarchies evaluated at each recursion step. Only hierarchies with the fewest distinct member values in the current level are evaluated, up to this limit. | `10` |
| `max-entropy` | Maximum Shannon entropy for a level to qualify as an explanation. The value should be between 0 and 1. | `0.4` |
| `min-percentage-relative-contribution` | Minimum relative contribution (%) to consider a member as significant. | `10` |
| `min-percentage-absolute-contribution` | Minimum absolute contribution (%) to consider a member as significant. | `1` |
| `min-variation-threshold` | Minimum absolute variation value at a location for Auto-Explain to analyze it. | `1e-6` |
| `include-opposite-contributors` | Whether to include members contributing in the opposite direction of the overall variation. | `false` |
| `max-members-per-level` | Maximum number of members a hierarchy can have at the current location to be considered in the analysis. If set to -1, this limit is disabled. | `-1` |
### `max-depth`
**Default:** `15`
The maximum recursion depth along any single path. Each time the algorithm identifies a significant
member, it recurses into it and increments the depth by 1. When depth reaches `max-depth`, the
algorithm stops and records the current location as a root cause.
Each branch of the recursion tree independently tracks depth from the starting cell. For example,
the algorithm may find two significant members at depth 2 and recurse into both; each branch then
reaches depth 3 on its own.
**Tuning guidance:**
* **Increase** if the cube has many levels and Auto-Explain stops before reaching meaningful root
causes. This produces more detailed explanations at the cost of longer analysis time.
* **Decrease** if analyses take too long or return overly detailed results. A lower value produces
broader, higher-level explanations.
### `max-distinct-hierarchies`
**Default:** `10`
The maximum number of hierarchies the algorithm evaluates at each recursion step. Before computing
entropy, the algorithm ranks candidate hierarchies by their **member count** (the number of distinct
member values in the hierarchy level being evaluated at the current location). It then keeps only
the `max-distinct-hierarchies` hierarchies with the fewest members. Hierarchies with fewer members
are evaluated first because they require fewer queries.
**Tuning guidance:**
* **Increase** if the cube has many hierarchies and more of them should be considered at each step.
This improves accuracy but increases query volume.
* **Decrease** if analyses are slow due to a large number of hierarchies. The algorithm already
prioritizes hierarchies with fewer members, so reducing this value typically has limited impact on
result quality.
### `max-entropy`
**Default:** `0.4`
The maximum Shannon entropy value for a hierarchy level to be considered a valid explanation.
Entropy has a \[0, 1] range and measures how evenly the variation is distributed across members:
* **Entropy near 0**: Variation is concentrated in one or a few members, meaning the hierarchy
explains the variation well.
* **Entropy near 1**: Variation is evenly spread across all members, meaning the hierarchy does not
provide a useful explanation.
If all candidate hierarchies have entropy above this threshold, the algorithm stops recursing at the
current location.
**Tuning guidance:**
* **Increase toward 1** if no single member dominates at the locations being analyzed and root
causes need to be found in moderately distributed data. This makes the algorithm more permissive
but may produce less meaningful explanations.
* **Decrease toward 0** if only highly concentrated variations should be explained. This makes the
algorithm more selective and produces more precise explanations but may stop early if data is
moderately distributed.
### High root cause count
Increasing this value may result in a high number of root causes, which may significantly increase
analysis time.
### `min-percentage-relative-contribution`
**Default:** `10`
The minimum relative contribution percentage a member must have to be considered significant. The
relative contribution measures a member's share of its parent's variation:
```
relativeContribution = |memberVariation / parentVariation| × 100
```
If a member's relative contribution falls below this threshold, the algorithm skips it and does not
recurse into it.
**Tuning guidance:**
* **Increase** to focus on only the most dominant contributors at each level. This produces fewer,
more impactful root causes but may miss secondary contributors.
* **Decrease** to include smaller contributors in the analysis. This captures more nuance but can
produce noisier results with many minor root causes.
### `min-percentage-absolute-contribution`
**Default:** `1`
The minimum absolute contribution percentage a member must have to be considered significant. The
absolute contribution measures a member's share of the original top-level variation:
```
absoluteContribution = relativeContribution × parentAbsoluteContribution / 100
```
At the starting cell (depth 0), `parentAbsoluteContribution` is 100%.
This threshold prevents the algorithm from recursing deeply into branches that are locally
significant but globally negligible.
**Tuning guidance:**
* **Increase** to restrict results to members with a meaningful share of the overall variation.
Useful when only root causes that materially impact the total are relevant.
* **Decrease** to allow the algorithm to explore branches that represent a small fraction of the
total variation. Useful when all contributing factors need to be identified, even minor ones.
The two contribution thresholds work together. A member must exceed **both** thresholds to be
considered significant and trigger further recursion. The relative threshold ensures local
significance. The absolute threshold ensures global relevance.
### `min-variation-threshold`
**Default:** `1e-6`
The minimum absolute value of the variation at a location before the algorithm begins analysis. If
the variation is below this threshold, Auto-Explain considers it negligible and does not attempt to
explain it. This value must be strictly above 0. The unit matches the unit of the measure being
analyzed: for a measure in dollars, the threshold is in dollars; for a normalized measure with
values between 0 and 1, the threshold should be set accordingly.
**Tuning guidance:**
* **Increase** if measures have natural noise or floating-point imprecision and Auto-Explain is
trying to explain insignificant variations.
* **Decrease** if very small but meaningful variations need to be analyzed, for example when working
with normalized or ratio-based measures.
Ignoring variations below this threshold prevents division by zero when computing relative
contributions (`memberVariation / parentVariation`). This value must always be strictly above 0 to
ensure zero variation is always caught before contribution computation.
### `include-opposite-contributors`
**Default:** `false`
Whether to include members that contribute in the opposite direction of the overall variation. By
default, Auto-Explain only considers members that contribute in the same direction as the parent
variation (e.g., only positive contributors when the overall variation is positive). When enabled,
members contributing in the opposite direction are also considered as root causes.
When this parameter is enabled:
* Members are sorted by **absolute value** of their marginal variation, regardless of sign.
* The contribution threshold filter uses the **absolute value** of both the member's contribution
and the threshold, so members with large negative contributions are retained when the overall
variation is positive (and vice versa).
**Tuning guidance:**
* **Enable** (`true`) when opposite-direction members are meaningful for your analysis. For example,
if the overall variation is positive but a specific member has a large negative contribution, this
member may be important to understand the overall picture.
* **Disable** (`false`) when you only want to explain contributions that align with the overall
trend direction.
### `max-members-per-level`
**Default:** `-1`
The maximum number of members a hierarchy can have at the current location to be considered in the
analysis. Before entropy is computed, any hierarchy whose member count at the current location
exceeds this value is excluded from the candidate set. This exclusion is unconditional: the
hierarchy is removed regardless of its entropy or contribution potential.
When set to `-1`, the limit is disabled and all hierarchies remain eligible regardless of member
count.
**Tuning guidance:**
* **Set a positive value** to exclude hierarchies with a large number of members at the current
location. This reduces query volume and analysis time when some hierarchies are very wide at
certain locations.
* **Leave at `-1`** (the default) if member count should not restrict eligibility. In this case,
`max-distinct-hierarchies` alone controls how many hierarchies are evaluated.
### Combined effect of entropy and contribution thresholds
The `max-entropy` and contribution thresholds (`min-percentage-relative-contribution`,
`min-percentage-absolute-contribution`) act at different stages of the algorithm. Together, they
determine how many root causes Auto-Explain produces.
* **`max-entropy`** controls **which hierarchies** the algorithm considers worth exploring. A
hierarchy is only selected if its entropy is below this threshold, meaning the variation is
sufficiently concentrated.
* **Contribution thresholds** control **which members** within the selected hierarchy are pursued
further. A member is only recursed into if both its relative and absolute contributions exceed
their respective thresholds.
These two filters compound: relaxing both produces significantly more root causes than relaxing
either one alone.
If Auto-Explain returns too many root causes, decrease `max-entropy` first. This reduces the number
of hierarchies explored at every recursion step, which has a cascading effect on the total number of
results. If results are still too broad, increase the contribution thresholds.
| Entropy threshold | Contribution thresholds | Result |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Low (e.g. `0.2`) | High (e.g. `20%` relative) | Very few root causes. Only highly concentrated hierarchies are explored, and only dominant members are kept. |
| Low (e.g. `0.2`) | Low (e.g. `5%` relative) | Few root causes. Concentrated hierarchies only, but more members within them are explored. |
| High (e.g. `0.8`) | High (e.g. `20%` relative) | Moderate root causes. More hierarchies qualify, but only dominant members are kept at each step. |
| High (e.g. `0.8`) | Low (e.g. `5%` relative) | Many root causes. The algorithm explores broadly across hierarchies and deeply within each. |
## How does the algorithm work?
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.
### 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
To learn how to use Auto-Explain after configuring it,
see [How to use Auto-Explain](../../../../user-guide/auto-explain).
To define an AI disclaimer, see [AI disclaimer](../disclaimer).