atoti.scope.cumulative_scope module#

class atoti.CumulativeScope#

Scope to perform a cumulative aggregation.

Cumulative aggregations include cumulative sums (also called running sum or prefix sum), mean, min, max, etc.

Example

>>> df = pd.DataFrame(
...     columns=["Year", "Month", "Day", "Quantity"],
...     data=[
...         (2019, 7, 1, 15),
...         (2019, 7, 2, 20),
...         (2019, 6, 1, 25),
...         (2019, 6, 2, 15),
...         (2018, 7, 1, 5),
...         (2018, 7, 2, 10),
...         (2018, 6, 1, 15),
...         (2018, 6, 2, 5),
...     ],
... )
>>> table = session.read_pandas(
...     df,
...     table_name="Cumulative",
...     default_values={"Year": 0, "Month": 0, "Day": 0},
... )
>>> cube = session.create_cube(table)
>>> h, l, m = cube.hierarchies, cube.levels, cube.measures
>>> h["Date"] = [table["Year"], table["Month"], table["Day"]]
>>> m["Quantity.SUM"] = tt.agg.sum(table["Quantity"])
>>> m["Cumulative quantity"] = tt.agg.sum(
...     m["Quantity.SUM"], scope=tt.CumulativeScope(level=l["Day"])
... )
>>> m["Cumulative quantity partitioned by month"] = tt.agg.sum(
...     m["Quantity.SUM"],
...     scope=tt.CumulativeScope(level=l["Day"], partitioning=l["Month"]),
... )
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Cumulative quantity"],
...     m["Cumulative quantity partitioned by month"],
...     levels=[l["Day"]],
...     include_totals=True,
... )
                Quantity.SUM Cumulative quantity Cumulative quantity partitioned by month
Year  Month Day
Total                    110                 110
2018                      35                  35
      6                   20                  20                                       20
            1             15                  15                                       15
            2              5                  20                                       20
      7                   15                  35                                       15
            1              5                  25                                        5
            2             10                  35                                       15
2019                      75                 110
      6                   40                  75                                       40
            1             25                  60                                       25
            2             15                  75                                       40
      7                   35                 110                                       35
            1             15                  90                                       15
            2             20                 110                                       35

__init__(*, level, dense=False, partitioning=None, window=None)#

Parameters

level (Level) – The level along which the aggregation is performed.
dense (bool) – When True, all members of the level, even those with no value for the underlying measure, will be taken into account for the cumulative aggregation (resulting in repeating values).
partitioning (Optional[Level]) – The level in the hierarchy at which to start the aggregation over.

window (Union[range, None, Tuple[str, str], Tuple[Optional[str], str], Tuple[str, Optional[str]]]) –

The custom aggregation window. The window defines the set of members before and after a given member (using the level order) to be considered in the computation of the cumulative aggregation.

The window can be a:

range starting with a <=0 value and ending with a >=0 value.

By default the window is range(-∞, 0), meaning that the value for a given member is computed using all of the members before it and none after it.

For instance, to compute the sliding mean on the 5 previous members of a level:
```
m2 = atoti.agg.mean(m1, scope=tt.CumulativeScope(level=l["date"], window=range(-5, 0)))
```

time period window as a two-element tuple of either None or a period as specified by Java’s Period.parse().

Example:

>>> from datetime import date
>>> df = pd.DataFrame(
...     columns=["Date", "Quantity"],
...     data=[
...         (date(2019, 7, 2), 15),
...         (date(2019, 7, 1), 20),
...         (date(2019, 6, 1), 25),
...         (date(2019, 6, 2), 15),
...         (date(2019, 6, 30), 5),
...     ],
... )
>>> table = session.read_pandas(
...     df, table_name="CumulativeTimePeriod"
... )
>>> cube = session.create_cube(table, mode="manual")
>>> h, l, m = cube.hierarchies, cube.levels, cube.measures
>>> cube.create_date_hierarchy("Date", column=table["Date"])
>>> h["Date"] = {
...     **h["Date"].levels,
...     "Date": table["Date"],
... }
>>> m["Quantity.SUM"] = tt.agg.sum(table["Quantity"])
>>> m["Cumulative quantity"] = tt.agg.sum(
...     m["Quantity.SUM"], scope=tt.CumulativeScope(level=l["Date"])
... )
>>> m["Cumulative quantity with 2 days window"] = tt.agg.sum(
...     m["Quantity.SUM"],
...     scope=tt.CumulativeScope(
...         level=l["Date"], window=("-P2D", None)
...     ),
... )
>>> m[
...     "Cumulative quantity with 2 days window partitioned by month"
... ] = tt.agg.sum(
...     m["Quantity.SUM"],
...     scope=tt.CumulativeScope(
...         level=l["Date"],
...         window=("-P2D", None),
...         partitioning=l["Month"],
...     ),
... )
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Cumulative quantity"],
...     m["Cumulative quantity with 2 days window"],
...     m[
...         "Cumulative quantity with 2 days window partitioned by month"
...     ],
...     levels=[l["Day"]],
...     include_totals=True,
... )
                Quantity.SUM Cumulative quantity Cumulative quantity with 2 days window Cumulative quantity with 2 days window partitioned by month
Year  Month Day
Total                     80                  80                                     35
2019                      80                  80                                     35
      6                   45                  45                                      5                                                  5
            1             25                  25                                     25                                                 25
            2             15                  40                                     40                                                 40
            30             5                  45                                      5                                                  5
      7                   35                  80                                     35                                                 35
            1             20                  65                                     25                                                 20
            2             15                  80                                     35                                                 35