Scenario and cycle management

The previous section provided documentation on Scenario (and Pipeline) creation. Now that we know how to create a new Scenario, this section will describe the scenario's attributes and the various utility methods.

In the following, it is assumed that my_config.py module contains a Taipy configuration already implemented.

Scenario attributes

The scenario creation method returns a Scenario entity. It is identified by a unique identifier id that was generated by Taipy. A scenario also holds various properties, each accessible as an attribute of the scenario:

• config_id is the id of the scenario configuration.
• creation_date corresponds to the date-time provided at the creation.
• is_primary is True if it is a primary scenario. False otherwise.
• subscribers is the list of Tuple(callbacks, params) representing the subscribers.
• properties is the complete dictionary of the scenario properties. It includes a copy of the properties of the scenario configuration, in addition to the properties provided at the creation and at runtime.
• cycle is the cycle of the scenario.
• pipelines is a dictionary holding the various pipelines of the scenario. The key corresponds to the pipeline's config_id (while the value is the pipeline itself).
• Each property of the properties dictionary is also directly exposed as an attribute.
• Each nested entity is also exposed as an attribute of the scenario. The attribute name corresponds to the config_id of the nested entity.

Example

import taipy as tp
from datetime import datetime
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg,
                              creation_date=datetime(2022, 1, 1),
                              name="Scenario for January")

# The config_name is an attribute of the scenario and equals "scenario_configuration"
scenario.config_name
# The creation date is the date-time provided at the creation. It equals datetime(2022, 1, 1)
scenario.creation_date
# The is_primary property equals `True` since it is the only scenario of the cycle.
scenario.is_primary
# There was no subscription, so subscribers is an empty list
scenario.subscribers # []
# The properties' dictionary equals {"name": "Scenario for January"}. It contains all the properties,
# including the `name` provided at the creation
scenario.properties # {"name": "Scenario for January"}
# The `name` property is also exposed directly as an attribute. It equals "Scenario for January"
scenario.name
# the sales pipeline entity is exposed as an attribute of the scenario
sales_pipeline = scenario.sales
# the production pipeline entity as well
production_pipeline = scenario.production
# All the tasks are also exposed as attributes, including the training task entity
training_task = scenario.training
# The six data nodes are also exposed as attributes of the scenario.
current_month_data_node = scenario.current_month

Taipy exposes multiple methods to manage the various scenarios.

Get a scenario by id

The first method to get a scenario is from its id by using the get() method:

import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)
scenario_retrieved = tp.get(scenario.id)
scenario == scenario_retrieved

Here, the two variables scenario and scenario_retrieved are equal.

Get all scenarios

All the scenarios can be retrieved using the method get_scenarios(). This method returns the list of all existing scenarios. If an optional cycle is given as a parameter, the list contains all the existing scenarios of the cycle. If an optional tag is provided as a parameter, the list contains all the existing scenarios tagged with the tag provided.

Get primary scenarios

The get_primary() method returns the primary scenario of the cycle given as a parameter.

get_primary_scenarios() returns the primary scenarios for all the existing cycles.

Promote a scenario as primary

To set a scenario as primary, the set_primary() method must be used. It promotes the scenario given as a parameter to the primary scenario of its cycle. If the cycle already had a primary scenario it will be demoted, and it will no longer be primary for the cycle.

Delete a scenario

A scenario can be deleted by using delete() which takes the scenario id as a parameter. The deletion is also propagated to the nested pipelines, tasks, data nodes, and jobs if they are not shared with any other scenarios.

If there is more than one scenario in the cycle, an error will be raised if you try to delete a primary scenario. You must promote another scenario as primary before deleting the primary one. On the other hand, if there is only one scenario in the cycle, the primary scenario can be deleted, which will also delete its cycle.

Compare scenarios

You can compare two or more scenarios, created from the same scenario configuration, by using taipy.compare_scenarios(). This function accepts two or more scenarios to be compared, you can also provide the data node config id to specify which data nodes from the scenarios you want to compare.

import taipy as tp
from datetime import datetime
from my_config import *

previous_month_scenario = tp.create_scenario(monthly_scenario_cfg)
previous_month_scenario.current_month.write(datetime(2020, 1, 1))
previous_month_scenario.submit()

current_month_scenario = tp.create_scenario(monthly_scenario_cfg)
current_month_scenario.current_month.write(datetime(2020, 2, 1))
current_month_scenario.submit()

tp.compare(previous_month_scenario,
           current_month_scenario,
           data_node_config_id="sales_predictions")

Info

Defining the comparison function To see how you can define the function used to compare data nodes, please refer to the Scenario Config page.

Tag or untag a scenario

A scenario can have multiple tags. You can add a tag to a scenario using tag(). Alternatively, you can use the Scenario.add_tag() method.

import taipy as tp
from my_config import *

scenario = tp.create_scenario(monthly_scenario_cfg)
tp.tag(scenario, "my_tag")
# or
scenario.add_tag("my_tag")

You can retrieve all scenarios that have a specific tag using get_scenarios() with the tag parameter.

Two scenarios can not have the same tag in the same cycle. If an existing tag is set on another scenario from the same cycle, it will be removed from the current scenario having that tag.

You can remove a tag of a scenario using untag(). Alternatively, you can use the Scenario.remove_tag() method.

import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)
tp.untag(scenario, "my_tag")
# or
scenario.remove_tag("my_tag")

You can define a list of authorized tags in the scenario configuration by specifying the value of authorized_tags. From the scenarios that are created from that configuration, if you add a tag that is not authorized, an exception will be raised.

Cycle attributes

As we saw in the previous chapter, the Cycle creation is indirectly triggered by the scenario creation method. A cycle is identified by a unique identifier id that was generated by Taipy. A cycle also holds various attributes and properties, each accessible as an attribute of the cycle:

• frequency corresponds to the cycle Frequency. It is populated at the cycle creation using the scenario frequency that triggered the cycle creation.
• creation_date corresponds to the date-time of the creation of this cycle.
• start_date corresponds to the date and time of the start of this cycle.
• end_date corresponds to the date and time of the end of this cycle.
• name corresponds to a user readable name of this cycle.
• Each property of the properties dictionary is also directly exposed as an attribute.

Example

import taipy as tp
from datetime import datetime
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg,
                              creation_date=datetime(2022, 1, 3))
cycle = scenario.cycle

# The frequency is an attribute of the cycle. In the example, it equals
# Frequency.MONTHLY since my_config.monthly_scenario_cfg is used has been
# used to instantiate scenario and cycle.
cycle.frequency
# The creation date is the date-time provided at the creation. It equals datetime(2022, 1, 3)
cycle.creation_date
# The start date is the date-time of the start of the cycle. It equals datetime(2022, 1, 1)
cycle.start_date
# The end date is the date-time of the end of the cycle. It equals datetime(2022, 1, 31)
cycle.end_date
# By default, the `name` is None. It can be set manually.
cycle.name = "January cycle"

Get a cycle by id

The basic method to get a cycle is from its id by using the get() method:

import taipy as tp
import my_config

scenario = tp.create_scenario(my_config.monthly_scenario_cfg)
cycle = scenario.cycle
cycle_retrieved = tp.get(cycle.id)
cycle == cycle_retrieved

Here, the two variables cycle and cycle_retrieved are equal.

Get all cycles

All the cycles can be retrieved using the method get_cycles(). This method returns the list of all existing cycles.

Delete a cycle

A cycle can be deleted by using delete() which takes the cycle id as a parameter. The deletion is also propagated to the nested scenarios, pipelines, tasks, data nodes, and jobs if they are not shared with any other cycles.

The next section presents the pipeline management.