atoti.Cube.create_parameter_simulation()

Cube.create_parameter_simulation(name, *, measures, levels=(), base_scenario_name='Base')

Create a parameter simulation and its associated measures.

Parameters:

• name (str) – The name of the simulation. This is also the name of the corresponding table that will be created.

• measures (Mapping[str, ConstantValue | None]) – The mapping from the names of the created measures to their default value.

• levels (Collection[Level]) – The levels to simulate on.

• base_scenario_name (str) – The name of the base scenario.

Return type:

Table

Example

>>> sales_table = session.read_csv(
...     f"{TUTORIAL_RESOURCES}/sales.csv",
...     table_name="Sales",
...     keys=["Sale ID"],
... )
>>> shops_table = session.read_csv(
...     f"{TUTORIAL_RESOURCES}/shops.csv",
...     table_name="Shops",
...     keys=["Shop ID"],
... )
>>> sales_table.join(
...     shops_table, sales_table["Shop"] == shops_table["Shop ID"]
... )
>>> cube = session.create_cube(sales_table)
>>> l, m = cube.levels, cube.measures

Creating a parameter simulation on one level:

>>> country_simulation = cube.create_parameter_simulation(
...     "Country simulation",
...     measures={"Country parameter": 1.0},
...     levels=[l["Country"]],
... )
>>> country_simulation += ("France crash", "France", 0.8)
>>> country_simulation.head()
                      Country parameter
Scenario     Country
France crash France                 0.8

• France crash is the name of the scenario.

• France is the coordinate at which the value will be changed.

• 0.8 is the value the Country parameter measure will have in this scenario.

>>> m["Unparametrized turnover"] = tt.agg.sum(
...     sales_table["Unit price"] * sales_table["Quantity"]
... )
>>> m["Turnover"] = tt.agg.sum(
...     m["Unparametrized turnover"] * m["Country parameter"],
...     scope=tt.OriginScope(l["Country"]),
... )
>>> cube.query(m["Turnover"], levels=[l["Country simulation"]])
                      Turnover
Country simulation
Base                961,463.00
France crash        889,854.60

Drilldown to the Country level for more details:

>>> cube.query(
...     m["Unparametrized turnover"],
...     m["Country parameter"],
...     m["Turnover"],
...     levels=[l["Country simulation"], l["Country"]],
... )
                           Unparametrized turnover Country parameter    Turnover
Country simulation Country
Base               France               358,042.00              1.00  358,042.00
                   USA                  603,421.00              1.00  603,421.00
France crash       France               358,042.00               .80  286,433.60
                   USA                  603,421.00              1.00  603,421.00

Creating a parameter simulation on multiple levels:

>>> size_simulation = cube.create_parameter_simulation(
...     "Size simulation",
...     measures={"Size parameter": 1.0},
...     levels=[l["Country"], l["Shop size"]],
... )
>>> size_simulation += (
...     "Going local",
...     None,  # ``None`` serves as a wildcard matching any member value.
...     "big",
...     0.8,
... )
>>> size_simulation += ("Going local", "USA", "small", 1.2)
>>> m["Turnover"] = tt.agg.sum(
...     m["Unparametrized turnover"]
...     * m["Country parameter"]
...     * m["Size parameter"],
...     scope=tt.OriginScope(l["Country"], l["Shop size"]),
... )
>>> cube.query(
...     m["Turnover"],
...     levels=[l["Size simulation"], l["Shop size"]],
... )
                             Turnover
Size simulation Shop size
Base            big        120,202.00
                medium     356,779.00
                small      484,482.00
Going local     big         96,161.60
                medium     356,779.00
                small      547,725.20

When several rules contain None, the one where the first None appears last takes precedence.

>>> size_simulation += ("Going France and Local", "France", None, 2)
>>> size_simulation += ("Going France and Local", None, "small", 10)
>>> cube.query(
...     m["Unparametrized turnover"],
...     m["Turnover"],
...     levels=[l["Country"], l["Shop size"]],
...     filter=l["Size simulation"] == "Going France and Local",
... )
                  Unparametrized turnover      Turnover
Country Shop size
France  big                     47,362.00     94,724.00
        medium                 142,414.00    284,828.00
        small                  168,266.00    336,532.00
USA     big                     72,840.00     72,840.00
        medium                 214,365.00    214,365.00
        small                  316,216.00  3,162,160.00

Creating a parameter simulation without levels:

>>> crisis_simulation = cube.create_parameter_simulation(
...     "Global Simulation",
...     measures={"Global parameter": 1.0},
... )
>>> crisis_simulation += ("Global Crisis", 0.9)
>>> m["Turnover"] = m["Unparametrized turnover"] * m["Global parameter"]
>>> cube.query(m["Turnover"], levels=[l["Global Simulation"]])
                     Turnover
Global Simulation
Base               961,463.00
Global Crisis      865,316.70

Creating a parameter simulation with multiple measures:

>>> multi_parameter_simulation = cube.create_parameter_simulation(
...     "Price And Quantity",
...     measures={
...         "Price parameter": 1.0,
...         "Quantity parameter": 1.0,
...     },
... )
>>> multi_parameter_simulation += ("Price Up Quantity Down", 1.2, 0.8)
>>> m["Simulated Price"] = (
...     tt.agg.single_value(sales_table["Unit price"])
...     * m["Price parameter"]
... )
>>> m["Simulated Quantity"] = (
...     tt.agg.single_value(sales_table["Quantity"])
...     * m["Quantity parameter"]
... )
>>> m["Turnover"] = tt.agg.sum_product(
...     m["Simulated Price"],
...     m["Simulated Quantity"],
...     scope=tt.OriginScope(l["Sale ID"]),
... )
>>> cube.query(m["Turnover"], levels=[l["Price And Quantity"]])
                          Turnover
Price And Quantity
Base                    961,463.00
Price Up Quantity Down  923,004.48