atoti.measures module#

class atoti.measures.Measures#

Manage the Measure of a Cube.

The built-in measure contributors.COUNT counts how many facts (i.e. rows) from the cube’s base table contributed to each aggregate of a query:

Example

>>> df = pd.DataFrame(
...     columns=["ID", "Continent", "Country", "City", "Color"],
...     data=[
...         (1, "Asia", "Japan", "Tokyo", "red"),
...         (2, "Asia", "Japan", "Kyoto", "red"),
...         (3, "Asia", "Singapore", "Singapore", "white"),
...         (4, "Europe", "Spain", "Madrid", "green"),
...         (5, "Europe", "Spain", "Barcelona", "blue"),
...     ],
... )
>>> table = session.read_pandas(df, keys=["ID"], table_name="Cities")
>>> cube = session.create_cube(table, mode="manual")
>>> h, l, m = cube.hierarchies, cube.levels, cube.measures
>>> h["ID"] = [table["ID"]]
>>> cube.query(m["contributors.COUNT"])
  contributors.COUNT
0                  5
>>> cube.query(m["contributors.COUNT"], levels=[l["ID"]], include_totals=True)
      contributors.COUNT
ID
Total                  5
1                      1
2                      1
3                      1
4                      1
5                      1

The caption of this measure can be changed with I18nConfig.

A measure can evaluate to the current member of an expressed level:

Example

>>> h["Color"] = [table["Color"]]
>>> m["Color"] = l["Color"]
>>> cube.query(
...     m["Color"],
...     m["contributors.COUNT"],
...     levels=[l["Color"]],
...     include_totals=True,
... )
       Color contributors.COUNT
Color
Total                         5
blue    blue                  1
green  green                  1
red      red                  2
white  white                  1

Or, for a multilevel hierarchy:

Example

>>> h["Geography"] = [table["Continent"], table["Country"], table["City"]]
>>> m["Geography"] = h["Geography"]
>>> cube.query(
...     m["Geography"],
...     m["contributors.COUNT"],
...     levels=[l["City"]],
...     include_totals=True,
... )
                               Geography contributors.COUNT
Continent Country   City
Total                                                     5
Asia                                Asia                  3
          Japan                    Japan                  2
                    Kyoto          Kyoto                  1
                    Tokyo          Tokyo                  1
          Singapore            Singapore                  1
                    Singapore  Singapore                  1
Europe                            Europe                  2
          Spain                    Spain                  2
                    Barcelona  Barcelona                  1
                    Madrid        Madrid                  1

A measure can be compared to other objects, such as a constant, a Level, or another measure. If some condition inputs evaluate to None, the resulting measure will evaluate to False:

Example

>>> df = pd.DataFrame(
...     columns=["Product", "Quantity", "Threshold"],
...     data=[
...         ("bag", 5, 1),
...         ("car", 1, 5),
...         ("laptop", 4, None),
...         ("phone", None, 2),
...         ("watch", 3, 3),
...     ],
... )
>>> table = session.read_pandas(df, keys=["Product"], table_name="Products")
>>> cube = session.create_cube(table)
>>> l, m = cube.levels, cube.measures
>>> m["Condition"] = m["Quantity.SUM"] > m["Threshold.SUM"]
>>> cube.query(
...     m["Quantity.SUM"],
...     m["Threshold.SUM"],
...     m["Condition"],
...     levels=[l["Product"]],
...     include_totals=True,
... )
        Quantity.SUM Threshold.SUM Condition
Product
Total          13.00         11.00      True
bag             5.00          1.00      True
car             1.00          5.00     False
laptop          4.00                   False
phone                         2.00     False
watch           3.00          3.00     False