bptk

The bptk class provides high level functions that let you interact with your simulation models and scenarios.

You will typically start the framework by instantiating the bptk class within a Jupyer notebook, as follows:

import BPTK_PY
bptk=bptk()

This automatically starts a background process that scans your scenario directory and imports all scenarios.

class bptk(loglevel='WARN')
add_scenario(dictionary)
Add scenario during runtime
param dictionary

dictionary that contains all data required for the scenario. Check the readme!

type dictionary

A dictionary defining the scenario

return

Nothing is return from this method

rtype

dashboard(scenarios, scenario_managers, kind='area', agents=[], agent_states=[], equations=[], alpha=0.25, stacked=False, freq='D', start_date='', title='', visualize_from_period=0, visualize_to_period=0, x_label='', y_label='', series_names={}, strategy=False, return_df=False, constants=[])
Generic method for plotting with interactive widgets
param scenarios

names of scenarios to plot

param equations

names of equations to plot

param agents

Agents to plot

param agent_states

States of agents to plot

param scenario_managers

names of scenario managers to plot

param kind

type of graph to plot

param alpha

transparency 0 < x <= 1

param stacked

if yes, use stacked (only with kind=”bar”)

param freq

frequency of time series

param start_date

start date for time series

param title

title of plot

param visualize_from_period

visualize from specific period onwards

param visualize_to_period

visualize until a specific period

param x_label

label for x axis

param y_label

label for y axis

param series_names

names of series to modify

param strategy

set True if you want to use the scenarios’ strategies

param return_df

set True if you want to receive a dataFrame instead of the plot

param constants

constants to modify and type of widget (widget_type, equation_name, from, to ) –> from, to only for sliders

return

dataFrame with simulation results if return_df=True

destroy()
When we do not want to use the BPTK object anymore but keep the Python Kernel running, use this. It essentially only kills all the file monitors and makes sure the Python process can die happily.
return

None

export_scenarios(scenario_manager, scenarios=None, equations=None, interactive_scenario=None, interactive_equations=None, interactive_settings=None, time_column_name='time', scenario_df_name='scenario', scenario_column_name='scenario', indicator_df_name='indicator', interactive_df_name='interactive', filename=None)

Export data for the given scenarios in a structure that is amenable to analysis in BI tools. By default, the data is returned in a dictionary of dataframes.

The first dataframe named scenario_df_name will contain all the data for all the scenarios, indexed by the scenario name. The second dataframe named interactive_df_name will contain all the data for the interactive scenarios.

The interactive scenarios are generated by the export function according to the interactive settings. If you provide a filename, the data will not be returned in a dictionary but will be writen directly to an Excel (.xlsx) file.

The data will be split into two tabs, one named <scenario_df_name> for the scenario data and one named <interactive_df_name> for the interactive data. Currently the export function only works for System Dynamcis models.
param scenario_manager

param scenarios

param equations

param interactive_scenario

param interactive_equations

param interactive_settings

param time_column_name

param scenario_column_name

param scenario_df_name

param indicator_df_name

param interactive_df_name

param filename

return

get_scenario(scenario_manager, scenario)
Get a scenario object from a scenario manager
param scenario_manager

Name of the scenario manager

type scenario_manager

str

param scenario

Name of the scenario

type scenario

str

return

the scenario object if found or else None

rtype

SimulationScenario

get_scenario_names(scenario_managers)
Returns a concated list of all the scenario names from a list of scenario managers
param scenario_managers

list of scenario managers

type scenario_managers

list of strings

return

Returns a list of scenario names

rtype

List of strings

get_scenarios(scenario_managers=[], scenarios=[], scenario_manager_type='')
Get a dictionary of scenario objects. The keys of the dictionary are the scenario names, unless more than one scenario manager is passed, in which case the name of the scenario manager is used to prefixes the scenario name (i.e. <scenario_manager>_<scenario>).
param scenario_managers

List of scenario managers to get the scenarios from

type scenario_managers

List of strings, optional

param scenarios

Names of the scenarios to get

type scenarios

List of strings, optional

return

Dictionary of scenario objects

rtype

Dictionary of str:SimulationScenario entries

model_check(data, check, message)
Model checker
param data

dataframe series or any data that the given check method can parse

param check

lambda function of structure : lambda data : BOOLEAN CHECK ON DATA

param message

Error message if test failed

return

None

modify_strategy(scenarios, extended_strategy)
Modifies a strategy during runtime. Experimental feature for now. You may even add lambdas to strategy
param scenarios

names of scenarios to modify the strategies for

param extended_strategy

the actual extended strategy as a dict. Consult the readme!

return

None

plot_lookup(scenarios, scenario_managers, lookup_names, return_df=False, visualize_from_period=0, visualize_to_period=0, stacked=False, title='', alpha=0.25, x_label='', y_label='', start_date='', freq='D', series_names={}, kind='area')
Plot lookup functions. If they come with very different indices, do not be surprised that the plot looks weird as I greedily try to plot everything
param scenarios

List of scenarios with names

param scenario_managers

param lookup_names

param return_df

param visualize_from_period

param visualize_to_period

param stacked

param title

param alpha

param x_label

param y_label

param start_date

param freq

param series_names

param kind

return

plot_scenarios(scenarios, scenario_managers, agents=[], agent_states=[], agent_properties=[], agent_property_types=[], equations=[], kind='area', alpha=0.25, stacked=False, freq='D', start_date='', title='', visualize_from_period=0, visualize_to_period=0, x_label='', y_label='', series_names={}, strategy=False, progress_bar=False, return_df=False)
THE method for plotting scenarios for SD as well as Agent based models (ABM)
param scenarios

names of scenarios to plot

param equations

names of equations to plot (System Dynamics, SD)

param agents

List of agents to plot (Agent based modelling)

param agent_states

List of agent states to plot, REQUIRES “AGENTS” param

param scenario_managers

names of scenario managers to plot

param kind

type of graph to plot (“line” or “area”)

param alpha

transparency 0 < x <= 1

param stacked

if yes, use stacked (only with kind=”bar”)

param freq

frequency of time series

param start_date

start date for time series

param title

title of plot

param visualize_from_period

visualize from specific period onwards

param visualize_to_period

visualize until a specific period

param x_label

label for x axis

param y_label

label for y axis

param series_names

names of series to rename to, using a dict: {equation_name : rename_to}

param strategy

set True if you want to use the scenarios’ strategies

param progress_bar

set True if you want to show a progress bar (useful for ABM simulations)

param return_df

set True if you want to receive a dataFrame instead of the plot

return

dataFrame with simulation results if return_df=True

pulse_function_create(scenarios, scenario_managers)
Create a PULSE function using the PulseWidget interactively. This is a nice feature to create SD PULSE functions in interactive sessions. No need for re-modelling in Stella or SD DSL. Displays an interactive dashboard for selecting the equations/constants to define the PULSEs for (as many as possible).
param scenarios

Name of scenarios to create the function(s) for

param scenario_managers

Name of scenario managers to take the scenarios from

return

None

register_scenario_manager(scenario_manager)
Register a manually defined Scenario manager using the common JSON notation. Keep in mind that it HAS TO contain a reference to a live model instance
param scenario_manager

JSON notation as used in the scenarios definitions as well. DOes not necessarily need to contain scenarios, but can!

return

None

register_scenarios(scenarios, scenario_manager)
Register a new scenario with an existing scenario manager using the common JSON notation (Read the interactive tutorial)
param scenarios

JSON notation of scenario as known from “offline” definition in JSON file

param scenario_manager

name of scenario manager to add the scenario to

return

None

reset_all_scenarios()
Reload all scenarios from storage
return

All ABMModel Managers

reset_scenario(scenario_manager, scenario)
Reload scenario from storage
param scenario_manager

name of scenario manager for lookup

param scenario

name of scenario

return

None

reset_simulation_model(scenario_manager='', scenario='')
Resets only the memo (equation results) of a scenario, does not re-read from storage
param scenario_manager

name of scenario manager for lookup

param scenario

name of scenario

return

None

run_simulations(scenarios, scenario_managers, agents=[], agent_states=[], agent_properties=[], agent_property_types=[], equations=[], series_names={}, strategy=False, progressBar=False)
Method to run simulations (if you want to omit plotting). Use it to bypass plotting and obtain raw results
param scenarios

names of scenarios to simulate

param equations

names of equations to simulate

param output

output types as list. Default: [“frame”], may add “csv” to store results in results/scenario_name.csv

param scenario_managers

names of scenario managers to select scenarios from

return

dict of simulationScenarios

run_simulations_with_strategy(scenarios, equations=[], output=['frame'], scenario_managers=[])
method to run raw simulations (if you want to omit plotting). Simulates with the strategies of the scenarios
param scenarios

names of scenarios to simulate

param equations

names of equations to simulate

param output

output types as list. Default: [“frame”], may add “csv” to store results in results/scenario.csv

param scenario_managers

names of scenario managers to select scenarios from

return

dict of SimulationScenario

train_simulations(scenarios, scenario_managers, episodes=1, agents=[], agent_states=[], agent_properties=[], agent_property_types=[], series_names={}, return_df=False, progress_bar=False)
Used to run a simulation repeatedly in episodes. Ensures that the begin_epsiode and end_epsisode methds are called on the underlying model. Currently this method only works on agent-based-models
param episodes

the number of episodes to run

param scenarios

the scenarios to run

param scenario_managers

the scenario managers to select the scenarios from

param agents

the agents containing the results we want to measure.

param agent_states

the agent state information we are interested in

param agent_properties

the agent property information we are interested in

param agent_property_types

the agent property type we are interested in

param series_names

allows renaming of variables in the plots

param progressBar

shows a progress bar that tracks the epsiode number

return

If return_df is true it returns a dataframe of the results, otherwise the results are plotted directly.