Atoti Intelligence Essentials
This is part of the Atoti Intelligence Essentials offer.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:
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:
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
- 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
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.
