origin_sdk.service.Scenario

Scenario Objects

class Scenario()

A Scenario class that holds state in order to provide a more Pythonic interface for Scenario building and downloading outputs

Arguments:

• scenario_id str - The ID to initialise the scenario with. Will fetch the scenario details and populate itself with details
• session OriginSession - You should first instantiate an OriginSession and pass this over to the Scenario.

Attributes:

• scenario_id str - The scenario ID
• session OriginSession - The OriginSession attached to this scenario
• scenario ScenarioType - The full Scenario object from the service

get_downloadable_regions

def get_downloadable_regions()

A helper function to return the regions available for download from this scenario

Returns:

A list of regions available

get_scenario_regions

def get_scenario_regions()

Helper function to get the regions object on the Scenario, as it's a common access pattern.

get_scenario_region

def get_scenario_region(region: str)

Helper function to get a specific region from the regions object, as it's a common access pattern.

Returns:

RegionDict

get_download_types

def get_download_types(region: str)

Returns the types, granularities, and optional sub-types of downloads available for the region. Expect something like "system"|"technology" and "1y"|"1m" for type and granularity respectively.

Arguments:

region (String)

Returns:

A list of download descriptors including type, granularity, and subType (where available).

get_download_years

def get_download_years(region: str)

Returns the valid download years for the region, as defined in the region metadata.

Arguments:

region (String)

Returns:

A list of valid years for downloads in the region.

get_scenario_data_csv

def get_scenario_data_csv(region: str,
                          download_type: str,
                          granularity: str,
                          currency: Optional[str] = None,
                          year: Optional[int] = None,
                          node: Optional[str] = None,
                          sub_type: Optional[str] = None,
                          force_no_cache: bool = False,
                          params: Optional[dict[str, str]] = None)

Downloads a csv from the service and returns as a string. Recommended to use if looking to generate a csv file on disk.

In general, our csvs have two header rows. The first identifies the column of data and the second is a unit string or other contextual information if relevant. To convert this to a pandas data frame, pass the output of this method to pandas' read_csv() method via a buffer.

Examples:

csv_data = scenario.get_scenario_data_csv('gbr', 'system', '1y')
buffer = StringIO(csv_data)
df = pd.read_csv(buffer, header=[0,1])

csv_data = scenario.get_scenario_data_csv(
    region='erc',
    download_type='nodal',
    granularity='1h',
    currency='usd2024',
    node='ZONDWD_6_B1',
)
buffer = StringIO(csv_data)
df = pd.read_csv(buffer, header=[0,1])

csv_data = scenario.get_scenario_data_csv(
    region='peu_deu',
    download_type='interconnector',
    granularity='1h',
    year=2028,
)

Arguments:

• region String - The region to download for. Use "get_downloadable_regions" to see a list of options.
• download_type String - The "type" of file to download. You can use "get_download_types" to query the available options.
• granularity String - The "granularity" of file to download. You can use "get_download_types" to query the available options.
• currency Optional, String - The currency year to download the file in. Will default to defaultCurrency on the scenario if available.
• year Optional, int - The scenario year to download when supported by the download filename template.
• node Optional, String - The node identifier to download nodal data for.
• sub_type Optional, String - Metadata sub-type used to disambiguate downloads that share the same type and granularity.

Returns:

CSV as text string

get_scenario_dataframe

def get_scenario_dataframe(region: str,
                           download_type: str,
                           granularity: str,
                           currency: Optional[str] = None,
                           year: Optional[int] = None,
                           sub_type: Optional[str] = None,
                           force_no_cache: bool = False,
                           params: Optional[dict[str, str]] = None)

This method is deprecated. Use get_scenario_data_csv instead.

Example:

csv_data = scenario.get_scenario_data_csv('gbr', 'system', '1y')
buffer = StringIO(csv_data)
df = pd.read_csv(buffer, header=[0,1])

---

Much the same as get_scenario_data but instead parses the CSV as a pandas data frame for easier consumption via a script. In general, our CSVs have two header rows. The first identifies the column of data and the second is a unit string or other contextual information if relevant.

Arguments:

• region String - The region to download for. Use "get_downloadable_regions" to see a list of options.
• type String - The "type" of file to download. You can use "get_download_types" to query the available options.
• granularity String - The "granularity" of file to download. You can use "get_download_types" to query the available options.
• currency Optional, String - The currency year to download the file in. Will default to defaultCurrency on the scenario if available.
• year Optional, int - The scenario year to download when supported by the download filename template.
• sub_type Optional, String - Metadata sub-type used to disambiguate downloads that share the same type and granularity.

Returns:

Pandas Dataframe

refresh

def refresh()

Contacts the service to get an updated view of the scenario. Useful for things such as polling on a frequency.

get

def get(key: str)

Shortcut for Scenario.scenario.get()

get_latest_scenario_from_region

@staticmethod
def get_latest_scenario_from_region(
        session: OriginSession,
        region: str,
        name_filter: Optional[Union[str, List[str]]] = None)

Given a region (and optional name match) will return the latest scenario found.