How to make your formulas easier to understand

  • 5 September 2022
  • 6 replies

Userlevel 7
Badge +14

When modeling in Pigment, it's easy to be focused on your output and not thinking about others trying to read your formula. This guide will give you a few tips on how you can make your formulas easier for others to understand.  


Table of Contents



Even though Pigment uses all kinds of functionality to make your formulas more understandable, like having the opportunity to name your dimensions and metrics with user friendly names, but if you like to use Pigment at its full potential you'll get complex formulas quite soon. Chaining modifiers, crossing different sources, and adding conditions will all make your formula more difficult to read.


Here are a few tricks to make it easier for you to read your own formulas, for your colleagues, and for us Pigment teams to help you build meaningful calculations for your business.


Tip 1 - Use line breaks and tabulations


I think the best way to write a formula in Pigment is to structure it in a tabular way: keep the main content on the left, and as you look further right you get finer details.

The first piece of advice is to use line breaks and give some air to your formula. If you don't use line breaks, you can't really see the different meaningful parts of your data transformation. Also, Pigment conveniently places a keyword first when you read either a function or a modifier.

Line breaks also offer you the possibility to use a double slash to comment on what this part of the formula does.

Here is an example of an indented formula with the original at the top.

No line breaks, no comments
Line breaks, tabulations and comments make for larger formulas though they are easier to understand

As you can see, a good combination of tabulations, line breaks and comments already increases the legibility of the formula. If you move your eyes from left to right, you'll read first Revenue - minus - OPEX which is the main takeaway, and then given the tabulations you can have a better understanding of how each is transformed.

You can read the modifiers in a tabular way - you can read BY and FILTER for the Revenue, and BY, BY SPLIT for the OPEX.  If you continue reading on the right, you can see the detailed rules for allocation and aggregation and you have enough space on each line to comment and justify why you went with this specific modifier or rule.


Tip 2 - End your parenthesis at the beginning of the line


If you have parenthesis in your calculation, feel free to indent the content of your sub-calculation and then end the parenthesis at the beginning of the line. The counter-argument is that at the end of the line, it becomes very difficult to locate where your sub-calculation ends, thus making it more difficult to get the whole idea of how a formula works.

Let's look at this example

A compact formula - can you guess where are the functional blocks?
A much sparser formula - though it’s easier to identify what happens at first glance

In that second version, the first information you read is that there are two blocks, and that they interact with each other with a multiplication. It's also much easier to identify the contents of those two main blocks (Revenue-minus-Opex and Growth Rate).


Tip 3 - Factor your multiplications, additions and modifiers


Did you know you can factor modifiers? Most of the time, it’s both more efficient and more legible. Let’s take this example, in which both formulas behave exactly the same.

The same aggregation is repeated and could be factored
It’s both more compact and easier to read

If it makes sense in your formula, trying to group modifiers together can really make it easier to read.


Keeping a good formula hygiene


By using these simple rules and making them your own, you’ll decrease the time it will take you to understand existing formulas in the applications you’re building. This will help you identify potential errors in the reasoning or data alignment. By making your formula clearer to read, you’ll be able to pack more efficient, more complex calculations while keeping everything easy to upgrade and to share.

Do you have other tips on how to make formulas easier to understand? I’d love to read from them and enhance this small guide!

6 replies

Userlevel 3
Badge +4

Hi @Lyes Ouadi thought this might be interesting! 🙂

Userlevel 2
Badge +13

Strangely, i’m not able to add line breaks (on a mac). Tab works.

Userlevel 7
Badge +14

@CamilleMomo Hitting Enter will execute the formula (just like leaving the formula bar).

To add a line break, you’ll have to use cmd+Enter.

Hope this helps!

Userlevel 2
Badge +13

@francois Thanks, I understand why I thought it did not work : if you do that on pre-existing text you cursor goes to next line but without the text

Userlevel 2
Badge +7

I want to add a comment with double slash in a blank formula, but it seems impossible, is it normal or not?

Userlevel 7
Badge +14


The formula has to contain something so if you decide to comment the whole formula you can type 

BLANK // 'Old Metric'[BY : Something]

This will be considered as a formula though so if you want to keep the manual inputs, make sure you enable metric Override.
Hope this helps!