---
title: "Use the DECUMULATE Function to Calculate Value Differences"
slug: "decumulate-function"
description: "Learn to use DECUMULATE to calculate differences between values and their previous item in Pigment for advanced time-based analysis."
updated: 2026-06-10T15:47:11Z
published: 2026-06-10T15:47:11Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.pigment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DECUMULATE function

## Description

Calculates the difference in a value between an item and the previous one

## Syntax

`DECUMULATE(Number, Decumulated Dimension [, Group Metric])`

- first parameter `Number` can be a Metric or a List Property
- `Decumulated Dimension`, list according to which decumulation is made, should be one of the Dimension of the first parameter
- `Group Dimension` is a list that resets the decumulation

## Return type

`Number`

## Examples

| **Case** | **Results** | **Return Type** |
| --- | --- | --- |
| `DECUMULATE('YTD Quantity Sold', month)` | returns the monthly `Quantity Sold` from a YTD data. | `number` |

## Use ON operator with DECUMULATE

You can use the ON operator to change the order of accumulation in the DECUMULATE function. The Metric in the example below is dimensioned by Vacuum Cleaner and represents inventory:

|  | `CD004_Cumulated Inventory (Input)` |
| --- | --- |
| Vacuum Cleaner A | 102 |
| Vacuum Cleaner B | 48 |
| Vacuum Cleaner C | 72 |

You want to decumulate this cumulated inventory to display the real inventory. It’s important to decumulate it in the correct order, as defined by the Priority Property in the Vacuum Cleaner Dimension List. You can see this below:

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/a2b7c14f-00d0-4be2-a753-e715c0ef9109.png)

If you want to decumulate in the order of the Priority property, you can use this formula: `DECUMULATE(‘CDO04_Cumulated Inventory (Input)’, ‘Vacuum Cleaner’ on ‘Vacuum Cleaner’.Priority)`

> [!WARNING]
> Remember to include the ON operator in the second argument of the function.

![](https://cdn.document360.io/e47cfe35-dc28-40c7-a083-6cf003073d8e/Images/Documentation/45d8ea90-cb1b-4269-bafb-2df16ed914c3.png)

You can prioritize Vacuum Cleaner B with a priority of 1, which is decumulated first, maintaining the original value. Next, Vacuum Cleaner C is processed, deducting the preceding Vacuum Cleaner B's decumulated value of 48 from the original value of 72. This leaves the resulting value of 24.

**Excel equivalent**: None

**See also**: [CUMULATE](/v1/docs/cumulate-function)