Scoping is a technical optimization that the Pigment engine uses to ensure your model is executing formulas and computing values as efficiently as possible. It ensures that your calculation path is streamlined, and it minimizes unnecessary recalculations in your Application. It forms part of Pigment’s optimization toolbox. 

In Pigment, changes you make to your model are recorded as Updates in your Application’s History. You can analyze each Update line in History using a tool called Profiling. This is where you can view the scope of your calculations. For more information, see Use Profiling to Optimize Calculation Paths in your Application.

Before you begin

Why is scoping beneficial to your model?

The best practice for performance management is to reduce unnecessary calculations, which is the goal of scoped calculations. When a formula is scoped, any recalculations in your model only occur on the Dimension Items that are impacted by the formula of the Metric or List Property, and not on every cell downstream of the Metric/List Property. By fully scoping your formulas, you’re ensuring minimal recalculations downstream and reducing the amount of data you’re computing. 

Recommended reading

For a comprehensive understanding of performance management in Pigment, we recommend these articles to get you started:

• How Pigment Handles Blank Cells in Formulas
• Use Performance Insights to Optimize your Application
• Top Tips for modeling in Pigment - Part 2: Performance Optimization

View scoped calculations

Scoping is assessed for each formula computation of a Metric or List Property. When you profile an update and its respective calculation path from a specific Block, or from your Application History, the Scope column displays the number of Dimensions that are scoped within the formula calculation. See an example below:

The number is displayed as a fraction. So, if you are looking at a Metric, you see the number of Dimensions in which a formula calculation is scoped over the total number of Dimensions available from the Metric structure.

If a calculation is scoped, hovering over the fraction brings up the calculation scope tooltip, showing the details of what has been scoped within the calculation:

• The number of Items of the Dimensions that were scoped within that calculation
• The scoping on Dimensions that are passed on to the next dependent calculation

The below image shows the calculation scope tooltip for a Metric. It shows that for the Budget Data (EUR) object, one Item on Dimensions Type, Client Type, Country and Subteams is currently scoped, whilst Month Dimension is not scoped. It also states that 1 more Dimension is scoped on the next dependent calculation. This refers to the Month Dimension, as it is the only Dimension not scoped:

In some cases, it could be that a calculation happened, but there was no change in values, which did not result in any dependent calculation. In this case, you will see a note that the “Calculation didn’t change any value.” 

Where no scoping is applicable (for example, on Tables), there is no value in the Scope column.

Calculation scope compared to the scope passed to the dependent calculation

When reviewing the Scope column, you may notice that in some cases, the number of Dimensions scoped is in bold, and other times it is plain roman. The bold indicates that there is a difference between scoped Dimensions for the given calculation compared to that passed to the next dependent calculation. This difference results from one of the following two situations applying:

1. There are more Dimensions scoped in the dependent calculation.
2. There are fewer Dimensions scoped in the dependent calculation (which means scope has been ‘lost’. See How scope can be lost during computations below for more information on losing scope).
   
   For example, a formula might have two Dimensions out of two being scoped, but uses the ADD function to include a third Dimension in the Metric structure. The ADD results in a loss of scope for dependent calculations (see more details about how scopes can be lost below). The fraction displays a bold 2 in this case.

Use scoping for highly efficient calculations

To achieve highly efficient calculations:

• Ensure that the calculation on a Dimension is scoped throughout all objects in the entire calculation path being profiled. This means that:
  • a Dimension should be part of the list of Dimensions in the calculation scope tooltip from the beginning to the end of a given update that is being profiled. If a Dimension is part of the calculation scope, it means that within that calculation, only the cells on that Dimension impacted by the change are calculated.
  • if a Dimension is featured in one object’s calculation and not in the subsequent ones, it means that the calculation is no longer scoped on that Dimension (the scope has been “lost”). So unnecessary cells are being calculated within downstream Metrics or List Properties on that calculation path. See How scope can be lost during computations below for more details.
• Ensure that within the calculation scope, your formula is written to preserve the scope for subsequent formulas. In the most efficient case, you would be ensuring that the formula is written in a way that all Dimensions within the Metric are scoped. In this way, subsequent calculations using that Metric keep the scope on those Dimensions. 
  • You can see what scope is passed on to the next dependent calculation by hovering over the scope for each calculation. Details of whether scope was passed to the next calculation or otherwise are shown here.

How scope can be lost during computations

There are instances where a formula scope can be lost. This can happen when: 

• A formula is assigning values based on a constant value.
• A Dimension is added to a Metric structure, but wasn’t included in the previous calculation.
• You use functions that functionally have an output scope of None, for example: 
  • PREVIOUS
  • CUMULATE
  • PRORATA
  • MOVINGAVERAGE
  • MOVINGSUM
  • iBY CONSTANT: ]
  • ADD 

Scoped calculation example

Let’s say you have a Metric with the Dimensions City and Month, and the revenue is aggregated per City and per Month. You have a second Metric, based on the above, but this one has a Country and Month Dimension. In this Metric, you’re calculating revenue by Country and by Month, where you’re using an aggregator to sum the data from city to country.

If you update the revenue for a few cities for the month of March 2022, you only want to perform a recalculation for March 2022. You don’t want to recompute the sum for any other months. Also, if you update data for cities that are only in Germany in your Country Dimension, you only want to perform a recalculation for Germany, and no other countries. 

When a formula is scoped, a calculation is only performed on Items that are impacted in the calculation. In the example above, a formula is scoped if the only calculations that occur are:

• cities in Germany for the City Dimension, and only for the Germany Item in Country Dimension
• the March 2022 item in the Month Dimension

No other Items in the City, Country or Month Dimensions should be recalculated as a result of the scoped formula.

Learn more​​​​​​​