xpressinsight.scenario.InsightRestClient.get_scenario_data

Purpose

Loads the entities described in annotations on the given class, from the given scenario, into an instance of the given class.

Synopsis

xpressinsight.scenario.InsightRestClient.get_scenario_data(self, scenario_id: str, scenario_data_class: Type[~SCENARIO_DATA_CONTAINER], filters: Optional[Dict[str, Dict[str, Iterable]]] = None) -> ~SCENARIO_DATA_CONTAINER

Arguments

scenario_id	The ID of the scenario from which to read.
scenario_data_class	A class declared with the ScenarioData or AppConfig decorator, describing entities to capture with class attributes with xi.data. or xi.types. type hints.
filters	A dictionary of filters to apply when reading each array. The key of the dictionary is the entity name of the array (which may be different from the attribute name or the column name in the scenario_data_class), and the value is a dictionary from index set entity name to the allowed values for those sets.

Return value

An instance of the supplied scenario_data_class, populated with values read from the scenario.

This function may raise the following errors:

scenario.ItemNotFoundError: If there is no scenario with this ID, or the REST API client credentials do not have permission to access it.
scenario.InsightServerError: If there is an issue communicating with the Insight server.

Example

Example of reading multiple entities from a scenario:

>>> @xi.ScenarioData()
... class EntitiesToRead:
...     my_integer: xi.data.Scalar(dtype=xi.integer)
...     my_string: xi.data.Scalar()
...     my_set: xi.data.Index()
...     my_array: xi.data.Series()
...     my_table: xi.data.DataFrame(
...         columns=[
...             xi.data.Column('my_first_column', dtype=xi.real),
...             xi.data.Column('my_second_column')])
...
... with ins.InsightRestClient(insight_url='http://localhost:8080/') as client:
...     SCENARIO_ID = '570b9100-46e3-4643-baee-2e24aa538f25'
...     scenario_data = client.get_scenario_data(SCENARIO_ID, SCENARIO_ID)
...     print(f'my_integer={scenario_data.my_integer}')

Example of applying a filter to array being read:

>>> @xi.ScenarioData()
... class EntitiesToRead:
...     factories: xi.data.DataFrame(
...         columns=[
...             xi.data.Column('sales'),
...             xi.data.Column('expenses')])
...
... # Fetch data for factories in Washington for the first 3 months of the year
... with ins.InsightRestClient(insight_url='http://localhost:8080/') as client:
...     # Apply a filter to both columns of the data-frame
...     factories_filter = {
...         'month': ['january', 'february', 'march'],
...         'state': ['Washington']
...     }
...     SCENARIO_ID = '570b9100-46e3-4643-baee-2e24aa538f25'
...     scenario_data = client.get_scenario_data(SCENARIO_ID, EntitiesToRead,
...         filters={'factories_sales': factories_filter,
...                  'factories_expenses': factories_filter})
...     print(scenario_data.factories)

Further information

1. scenario_data_class must be a class that has type attributes annotated using the xpressinsight.data. or xpressinsight.types. helper functions, and it must be decorated using the ScenarioData or AppConfig decorator. It's recommended to use ScenarioData unless the class is the application class for the app being read from, as AppConfig will perform additional validation that is only relevent for application definitions.

2. The caller may optionally restrict which rows of a Series, DataFrame, or PolarsDataFrame entity are returned by passing a dictionary of filters. When an array is filtered, it's passed a dictionary from index entity name to the allowed values of that index set. If an index set is not included in the filter, this is equivalent to allowing all set elements of that index set.

3. This function requests data in JSON format using the Insight REST API. When requesting a nontrivial amount of data within an executing Insight app, it is more efficient to use AppInterface.get_scenario_data, which transfers data using a compressed Parquet format.

Contents

Index

Glossary

Search Results

xpressinsight.scenario.InsightRestClient.get_scenario_data