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