Price Analysis

Utilities for validating, summarizing, and comparing market-price outputs.

API path: apem.unit_based_model.evaluation.price_analysis

Utilities for validating, summarizing, and comparing price tables across algorithms.

compare_price_algorithms(df, *, align_on=None, baseline=None)

Compare algorithm price series on aligned observations.

Parameters:

• df (DataFrame) – input price table with one algorithm and price value per aligned observation

• align_on (Sequence[str] | None) – explicit alignment key columns; when omitted, all non-required columns are used, or an inferred row index if none are available

• baseline (str | None) – optional algorithm name; if provided, only pairs including this baseline are returned

Returns:

pairwise comparison table with mean levels, mean differences, absolute differences, and correlation per algorithm pair

Raises:

ValueError – if duplicates exist for the same alignment key and algorithm, if fewer than two algorithms are present, or if baseline is not present

Return type:

DataFrame

round_numeric_columns(df, digits=2)

Round all numeric columns to a fixed number of decimal places.

Parameters:

• df (DataFrame) – input table

• digits (int) – number of decimals used for rounding numeric columns

Returns:

copy of df with rounded numeric columns

Return type:

DataFrame

summarize_prices(df, *, group_by=('algorithm',))

Compute descriptive statistics for prices grouped by one or more columns.

Parameters:

• df (DataFrame) – input price table

• group_by (Sequence[str]) – grouping columns to summarize by; defaults to ("algorithm",)

Returns:

one row per group with counts, central moments, quantiles, spread, and additional quality metrics

Return type:

DataFrame

validate_price_table(df)

Validate and normalize a generic price-analysis input table.

Parameters:

df (DataFrame) – input table containing at least algorithm and price columns; additional columns are preserved

Returns:

normalized copy with trimmed column names, normalized algorithm labels, and numeric price values

Raises:

ValueError – if required columns are missing, algorithm labels are empty, or no numeric prices are available

Return type:

DataFrame