Skip to content

Scenario comparison

This page explains how to use scenario comparators to compare alternative data between scenarios.

Main principles

In Taipy, comparing a scenario means comparing their data nodes. The global idea is to use a user defined function that takes list of data to compare and returns a comparison result. The function can return any data type, but the best is to format the comparison results in a way it can easily be used in a visual element.

  1. Define a comparison function: You can define a comparison function to compare specific data nodes of a scenario. For example a data node representing a KPI. The comparison function takes as input parameters the list of the data referred by the data nodes to compare and returns a comparison result.

  2. Configure the scenario with a comparator: The comparison function is then added to the scenario configuration as a scenario comparator.

  3. Compare scenarios: At runtime, you can compare the scenarios using the taipy.compare_scenarios() function. It takes as input parameters the list of scenarios to compare and returns the comparison results.

  4. Visualize the comparison results: The comparison results can be visualized using the various visual elements.

Example

Let's consider a simple example where a company wants to predict its sales for the next month. The sales forecasts depend on a weather parameter. The company wants to simulate multiple scenarios compare the yield revenue.

We can have the following:

  • One data node for the weather parameter.
  • One data node for the sales predictions.

Scenario with Tasks

To simplify the use case, we only have data nodes. No data processing is presented in this example, and the sales predictions data node is populated manually. However, in a real world, the sales predictions would have been generated by a Taipy Task, for example using a trained model based on some historical sales data.
For more details, see the task orchestration page.

The following code snippet shows how to compare scenarios:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
import pandas as pd
import taipy as tp
import taipy.gui.builder as tgb
from taipy import Config
from taipy.gui import Gui


def compare_revenue(*sales_predictions):
    unit_price = 9.99
    scenario_names = [f"Scenario {i}" for i in range(len(sales_predictions))]
    revenues = {"Scenarios": scenario_names,
                "Revenues": [sales * unit_price for sales in sales_predictions]}
    return pd.DataFrame(revenues)

if __name__ == "__main__":
    # Configure scenario
    weather_cfg = Config.configure_data_node("weather")
    sales_cfg = Config.configure_data_node("sales")
    scenario_cfg = Config.configure_scenario("scenario",
                                             additional_data_node_configs=[weather_cfg, sales_cfg],
                                             comparators={sales_cfg.id: compare_revenue})

    # Instantiate multiple scenarios and populate data
    # Create a scenario with sunny weather
    sunny = tp.create_scenario(scenario_cfg)
    sunny.weather.write("SUNNY")  # Set the weather to sunny
    sunny.sales.write(1000)  # Set the sales to

    # Create another scenario with a cloudy weather
    cloudy = tp.create_scenario(scenario_cfg)
    cloudy.weather.write("CLOUDY")  # Set the weather to cloudy
    cloudy.sales.write(800)  # Set the sales to

    # Create another scenario with a rainy weather
    rainy = tp.create_scenario(scenario_cfg)
    rainy.weather.write("RAINY")  # Set the weather to rainy
    rainy.sales.write(250)  # Set the sales to

    # Compare the scenarios on sales data node with the compare_revenue comparator
    revenues = tp.compare_scenarios(sunny, cloudy, rainy)[sales_cfg.id]["compare_revenue"]

    # Create a user interface
    with tgb.Page() as compare_page:
        tgb.chart("{revenues}", type="bar", x="Scenarios", y="Revenues")
        tgb.table("{revenues}")

    Gui(compare_page).run()
Here is the complete python code corresponding to the example.

Comparator function

User defined functions are used as comparator to compare scenarios on the data nodes (from the same configuration). The user defined function takes as input parameters the list of the data referred by the data nodes of each scenario to compare. The function returns a comparison results in a format that best suits the user needs.

In our example, a user function is defined to compare the scenarios on the sales predictions data node. The function compare_revenue computes the revenue based on the sales forecast. It takes as input parameters the list of the sales values. One value per scenario to compare. It returns the comparison results as a dataframe with the scenario name in a first column and the revenue in a second one. This way, the comparison results can be easily used in a chart or table visual element.

Configuration

The scenario configuration is created with the Config.configure_scenario() method. As usual the data node configurations and/or the task configurations are passed as parameters to the method. In addition, the comparators optional parameter is used to provide comparison functions. Note that multiple comparators can be added. A dictionary is used to associate the comparison function to the data node configuration on which it is applied.

In our example, the scenario configuration scenario_cfg is created. The compare_revenue function is passed as a comparator. The id of the sales predictions data node configuration is used as a key in the dictionary.

For more details on how to configure scenarios, see the scenario configuration page.

Comparison

The scenarios are compared using the taipy.compare_scenarios() function. The function takes as input parameters the list of scenarios to compare and returns all the comparison results in a dictionary. One result per comparator function defined in the scenario configuration.

In our example, three scenarios (previously created) are compared. We get the comparison result for the compare_revenue function applied to the sales predictions data nodes. The comparison result is directly stored in the revenues variable to be bound to a Taipy visual element.

User interface

The comparison results can be visualized using the various Taipy visual elements. Any visual element can be used to display the comparison results depending on the user needs.

In our example, the revenue is formatted as a dataframe, so it can be easily used in Taipy. We use two visual representations to display the comparison results: a table and a bar chart. Note that the Python API is used in the example to create the user interface, but the same interface can be done using the Markdown API.

For more details on the various visual elements, see the visual elements page.