Skip to main content

​
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.

​
Prerequisites

Auto-Explain must be enabled before adding configuration. See Set up Auto-Explain in Java or Set up Auto-Explain in 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:
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:

​
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:
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:
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.