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