> ## 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.
# Configure Auto-Explain
> The Auto-Explain algorithm constants (`max-depth`, `max-entropy`, the contribution thresholds, and more), what each one does, and how to tune them from the Atoti Java SDK and the Atoti Python SDK.
### Atoti Intelligence Essentials
This is part of the Atoti Intelligence Essentials offer.
Auto-Explain exploration is controlled by a set of constants governing the sensitivity to variations
and the recursion depth. Proper tuning avoids unnecessary query volume and keeps analysis results
focused. This page describes each constant and how to tune it. To understand how the algorithm uses
them, see [How Auto-Explain works](./how-it-works).
### Prerequisites
Auto-Explain must be enabled before adding configuration.
See [Set up Auto-Explain in Java](./setup-java) or [Set up Auto-Explain in Python](./setup-python)
for setup instructions.
## Hierarchy inclusion and exclusion
By default, Auto-Explain explores all of a cube's hierarchies. You can restrict analysis to specific
hierarchies, or exclude some — globally or per measure. These settings apply to both SDKs:
* **Atoti Java SDK** — under `auto-explain-configuration` in `application.yaml`. See [Set up Auto-Explain in Java](./setup-java).
* **Atoti Python SDK** — as attributes of [`Cube.auto_explain`](https://docs.activeviam.com/products/atoti/python-sdk/latest/api/atoti.Cube.auto_explain.html). See [Set up Auto-Explain in Python](./setup-python).
| Java (`application.yaml`) | Python (`Cube.auto_explain`) | Description |
| ------------------------------ | ---------------------------------- | ---------------------------------------------------------------- |
| `excluded-hierarchies` | `excluded_hierarchies` | Hierarchies excluded from all analyses on all measures. |
| `excluded-measure-hierarchies` | `excluded_hierarchies_per_measure` | Per-measure hierarchy exclusions. |
| `included-hierarchies` | `included_hierarchies` | When set, only these hierarchies are analyzed, for all measures. |
| `included-measure-hierarchies` | `included_hierarchies_per_measure` | Per-measure hierarchy inclusions. |
A hierarchy is identified by its hierarchy name and its dimension name, as usual in Atoti.
### Exclusion priority
Auto-Explain removes any excluded hierarchy from analysis, even if the same hierarchy also appears in
the included list. For example, if `Region / Country` is both included and excluded, it is excluded.
## How to tune the constants
Set these constants in the SDK you use:
* **Atoti Java SDK** — under `constants-config` in `application.yaml`. See [Set up Auto-Explain in Java](./setup-java), which also covers per-cube hierarchy inclusion and exclusion.
* **Atoti Python SDK** — as attributes of [`Cube.auto_explain`](https://docs.activeviam.com/products/atoti/python-sdk/latest/api/atoti.Cube.auto_explain.html), using the same names in snake\_case (for example, `max-depth` becomes `max_depth`). See [Set up Auto-Explain in Python](./setup-python).
The constants 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.
## Related reading
* [How Auto-Explain works](./how-it-works) — the algorithm and a worked example
* [Set up Auto-Explain in Java](./setup-java)
* [Set up Auto-Explain in Python](./setup-python)
* [Set up an LLM](../configure-and-start/set-up-an-llm) to enable the optional AI summary