atoti.scope package

Module contents

atoti.scope.cumulative(level, *, dense=False, partitioning=None, window=None)

Create a scope to be used in the computation of cumulative aggregations.

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

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 levels in the hierarchy at which to start the aggregation over.

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

    The custom aggregation window. The window defines the set of members before and after a given member (using the level comparator) 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.scope.cumulative(l["date"], window=range(-5, 0)))

    • time period as a two-element tuple starting with an offset of the form -xxDxxWxxMxxQxxY or None and ending with an offset of the form xxDxxWxxMxxQxxY or None.

      For instance, to compute the 5 previous days sliding mean:

      m2 = atoti.agg.mean(m1, scope=tt.scope.cumulative(l["date"], window=("-5D", None)))

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")
>>> 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.scope.cumulative(l["Day"])
... )
>>> m["Cumulative quantity partitioned by month"] = tt.agg.sum(
...     m["Quantity.SUM"],
...     scope=tt.scope.cumulative(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
Return type

Scope

atoti.scope.origin(*levels)

Create an aggregation scope with an arbitrary number of levels.

The passed levels define a boundary above and under which the aggregation is performed differently. When those levels are not expressed in a query, the measure will drill down until finding the value for all members of these levels, and then aggregate those values using the user-defined aggregation function. This allows to compute measures that show the yearly mean when looking at the grand total, but the sum of each month’s value when looking at each year individually.

Parameters

levels (Level) – The levels defining the dynamic aggregation domain.

Example

>>> df = pd.DataFrame(
...     columns=["Year", "Month", "Day", "Quantity"],
...     data=[
...         (2019, 7, 1, 15),
...         (2019, 7, 2, 20),
...         (2019, 7, 3, 30),
...         (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="Origin")
>>> cube = session.create_cube(table, mode="manual")
>>> 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["Average of monthly quantities"] = tt.agg.mean(
...     m["Quantity.SUM"], scope=tt.scope.origin(l["Month"])
... )
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Average of monthly quantities"],
...     levels=[l["Day"]],
...     include_totals=True,
... )
                Quantity.SUM Average of monthly quantities
Year  Month Day
Total                    140                         35.00
2018                      35                         17.50
      6                   20                         20.00
            1             15                         15.00
            2              5                          5.00
      7                   15                         15.00
            1              5                          5.00
            2             10                         10.00
2019                     105                         52.50
      6                   40                         40.00
            1             25                         25.00
            2             15                         15.00
      7                   65                         65.00
            1             15                         15.00
            2             20                         20.00
            3             30                         30.00
Return type

Scope

atoti.scope.siblings(hierarchy, *, exclude_self=False)

Create a “siblings” aggregation scope.

In a siblings scope, the value for the member of a given level in the hierarchy is computed by taking the contribution of all of the members on the same level (its siblings).

A siblings aggregation is an appropriate tool for operations such as marginal aggregations (marginal VaR, marginal mean) for non-linear aggregation functions.

Parameters

  • hierarchy (Hierarchy) – The hierarchy containing the levels along which the aggregation is performed.

  • exclude_self (bool) – Whether to include the current member’s contribution in its cumulative value.

Example

>>> df = pd.DataFrame(
...     columns=["Year", "Month", "Day", "Quantity"],
...     data=[
...         (2019, 7, 1, 15),
...         (2019, 7, 2, 20),
...         (2019, 7, 3, 30),
...         (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="Siblings")
>>> cube = session.create_cube(table, mode="manual")
>>> 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["Siblings quantity"] = tt.agg.sum(
...     m["Quantity.SUM"], scope=tt.scope.siblings(h["Date"])
... )
>>> m["Siblings quantity excluding self"] = tt.agg.sum(
...     m["Quantity.SUM"], scope=tt.scope.siblings(h["Date"], exclude_self=True)
... )
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Siblings quantity"],
...     m["Siblings quantity excluding self"],
...     levels=[l["Day"]],
...     include_totals=True,
... )
                Quantity.SUM Siblings quantity Siblings quantity excluding self
Year  Month Day
Total                    140               140                                0
2018                      35               140                              105
      6                   20                35                               15
            1             15                20                                5
            2              5                20                               15
      7                   15                35                               20
            1              5                15                               10
            2             10                15                                5
2019                     105               140                               35
      6                   40               105                               65
            1             25                40                               15
            2             15                40                               25
      7                   65               105                               40
            1             15                65                               50
            2             20                65                               45
            3             30                65                               35
Return type

Scope