atoti.CumulativeScope

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

>>> from datetime import date
>>> df = pd.DataFrame(
...     columns=["Date", "Quantity"],
...     data=[
...         (date(2019, 7, 1), 15),
...         (date(2019, 7, 2), 20),
...         (date(2019, 6, 1), 25),
...         (date(2019, 6, 2), 15),
...         (date(2018, 7, 1), 5),
...         (date(2018, 7, 2), 10),
...         (date(2018, 6, 1), 15),
...         (date(2018, 6, 2), 5),
...     ],
... )
>>> table = session.read_pandas(df, table_name="Cumulative")
>>> cube = session.create_cube(table)
>>> 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["Day"])
... )
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Cumulative quantity"],
...     levels=[l["Day"]],
...     include_totals=True,
... )
                Quantity.SUM Cumulative quantity
Year  Month Day
Total                    110                 110
2018                      35                  35
      6                   20                  20
            1             15                  15
            2              5                  20
      7                   15                  35
            1              5                  25
            2             10                  35
2019                      75                 110
      6                   40                  75
            1             25                  60
            2             15                  75
      7                   35                 110
            1             15                  90
            2             20                 110

dense: bool = False

When True, all members of level, even those with no value for the underlying measure, will be taken into account for the cumulative aggregation (resulting in repeating values).

level: HasIdentifier[LevelIdentifier] | LevelIdentifier

The level along which the aggregation is performed.

partitioning: HasIdentifier[LevelIdentifier] | LevelIdentifier | None = None

The level in the hierarchy at which to start the aggregation over.

>>> m["Partitioned by month"] = tt.agg.sum(
...     m["Quantity.SUM"],
...     scope=tt.CumulativeScope(level=l["Day"], partitioning=l["Month"]),
... )
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Partitioned by month"],
...     levels=[l["Day"]],
...     include_totals=True,
... )
                Quantity.SUM Partitioned by month
Year  Month Day
Total                    110
2018                      35
      6                   20                   20
            1             15                   15
            2              5                   20
      7                   15                   15
            1              5                    5
            2             10                   15
2019                      75
      6                   40                   40
            1             25                   25
            2             15                   40
      7                   35                   35
            1             15                   15
            2             20                   35

window: range | tuple[str, str] | tuple[str | None, str] | tuple[str, str | None] | None = None

The aggregation window defining the set of members before and after a given member (using the level’s 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.

  >>> m["3 previous members window"] = tt.agg.sum(
  ...     m["Quantity.SUM"],
  ...     scope=tt.CumulativeScope(level=l["Day"], window=range(-3, 0)),
  ... )
  >>> cube.query(
  ...     m["Quantity.SUM"],
  ...     m["3 previous members window"],
  ...     levels=[l["Day"]],
  ...     include_totals=True,
  ... )
                  Quantity.SUM 3 previous members window
  Year  Month Day
  Total                    110                        75
  2018                      35                        35
        6                   20                        20
              1             15                        15
              2              5                        20
        7                   15                        35
              1              5                        25
              2             10                        35
  2019                      75                        75
        6                   40                        55
              1             25                        45
              2             15                        55
        7                   35                        75
              1             15                        65
              2             20                        75
  

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

  >>> m["2 days window"] = tt.agg.sum(
  ...     m["Quantity.SUM"],
  ...     scope=tt.CumulativeScope(level=l["Date"], window=("-P2D", None)),
  ... )
  >>> m["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["2 days window"],
  ...     m["2 days window partitioned by month"],
  ...     levels=[l["Day"]],
  ...     include_totals=True,
  ... )
                  Quantity.SUM 2 days window 2 days window partitioned by month
  Year  Month Day
  Total                    110            35
  2018                      35            15
        6                   20            20                                 20
              1             15            15                                 15
              2              5            20                                 20
        7                   15            15                                 15
              1              5             5                                  5
              2             10            15                                 15
  2019                      75            35
        6                   40            40                                 40
              1             25            25                                 25
              2             15            40                                 40
        7                   35            35                                 35
              1             15            15                                 15
              2             20            35                                 35
  

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