Data

Data#

APIs for data loading, parsing, and analysis helpers in the unit-based workflow.

Scenario#

Scenario data structures and helpers used by unit-based data parsing.

API path: apem.unit_based_model.data.parsing.scenario

class Scenario(
name,
df_buyers,
df_sellers,
network,
nodes_agents,
periods,
blocks_buyers,
blocks_sellers,
r_star,
)[source]#

Bases: object

Container for all inputs that define one unit-based market scenario.

A scenario bundles bid tables, network topology, node metadata, and time/block structure into a single object passed through allocation, pricing, and evaluation workflows.

The object is intentionally lightweight and mutable so parsing steps and algorithms can derive adjusted views (for example, relaxed or scaled variants) from the same base scenario.

Expected table structure:

  • df_buyers typically includes at least buyer, period, node, max_dem and one or more valuation block columns (for example val1, val2, …).

  • df_sellers typically includes at least seller, period, node, max_prod and one or more production cost block columns.

  • network edges are expected to carry electrical attributes used by clearing/flow models (for example susceptance and capacity limits).

Parameters:

  • name (str) – human-readable scenario identifier used in logs and output paths

  • df_buyers (DataFrame) – buyer-side bids or demand blocks by period and node

  • df_sellers (DataFrame) – seller-side offers or generation blocks by period and node

  • network (Graph) – transmission graph used by nodal/zonal clearing models

  • nodes_agents (dict) – node metadata and node-to-agent mapping; entries are keyed by node and commonly include buyers, sellers, latitude and longitude

  • periods (list) – ordered list of market periods represented in the scenario

  • blocks_buyers (range) – buyer block index range used by multi-block demand bids

  • blocks_sellers (range) – seller block index range used by multi-block supply bids

  • r_star (str) – identifier of the reference node used by DC-style formulations

analyse_scenario(results_root='')[source]#

Compute and persist descriptive scenario statistics.

The method writes aggregate counts and demand/supply totals (overall and per period) to <results_root>/<scenario>_base_scenario.txt. If seller carrier information is available, renewable shares are included.

Parameters:

results_root (str) – output directory; if empty, a default scenario result folder under ./results/unit_based_model is used

Returns:

None

Return type:

None

plot_network(power_flow_model, zonal_config='', results_root='')[source]#

Plot the scenario network and optionally color nodes by zone.

The figure is stored in the scenario results directory and uses node coordinates from nodes_agents together with line endpoints from network.

Parameters:

  • power_flow_model – selected power-flow model name, used in output directory routing

  • zonal_config (str) – optional zonal configuration identifier; when provided, nodes are colored by node_to_zone.csv

  • results_root (str) – base output directory; if empty, a default scenario result folder under ./results/unit_based_model is used

Returns:

None

Return type:

None