Welfare Analysis

Welfare Analysis#

Utilities for loading and validating welfare tables and welfare metrics.

API path: apem.unit_based_model.evaluation.welfare_analysis

Utilities for loading and validating welfare tables from structured files or allocation stats text files.

load_welfare_table(
path,
*,
power_flow_model_name=None,
welfare_scope_column='welfare_scope',
period_column='period',
welfare_column='welfare',
sheet_name='Sheet1',
)[source]#

Load a welfare table from disk and normalize core columns.

Supported file types are .txt, .csv, .parquet, .xlsx, and .xls.

Parameters:

  • path (str | Path) – file path to load

  • power_flow_model_name (str | None) – model name override used when the loaded file does not include power_flow_model

  • welfare_scope_column (str) – source column name mapped to welfare_scope

  • period_column (str) – source column name mapped to period

  • welfare_column (str) – source column name mapped to welfare

  • sheet_name (str) – Excel sheet name when loading .xlsx/.xls

Returns:

validated normalized welfare table

Raises:

ValueError – if file type is unsupported or parsed data fails validation

Return type:

DataFrame

validate_welfare_table(df)[source]#

Validate and normalize a generic welfare-analysis input table.

Parameters:

df (DataFrame) – input table expected to contain power_flow_model, welfare_scope, period, and welfare

Returns:

normalized copy with lowercase scope labels, integer-like periods, and numeric welfare values

Raises:

ValueError – if required columns are missing, scope values are unsupported, model labels are empty, or period/scope combinations are inconsistent

Return type:

DataFrame