site.EvaluatedCombination

site.EvaluatedCombination(
    solution_type,
    site_names,
    site_indices,
    evaluated_combination_df,
    weights,
    site_problem,
    coverage_threshold=None,
    baseline_costs=None,
    meaningful_change_threshold=0.0,
    beyond_thresholds=None,
    unreachable_cost=None,
)

Container for results and summary metrics of an evaluated site combination.

This class stores the outcome of evaluating a candidate solution (i.e., a set of selected sites) against a demand dataset, and computes a range of summary statistics based on the minimum cost (e.g., travel time or distance) from demand locations to the selected sites.

Parameters

Name	Type	Description	Default
solution_type	str	Label describing the type of solution (e.g., optimisation method or scenario).	required
site_names	list of str	Names of the selected sites in the solution.	required
site_indices	list of int	Indices of the selected sites corresponding to the original site list.	required
evaluated_combination_df	pandas.DataFrame	DataFrame containing evaluation results for each demand point. Must include: - “min_cost”: Minimum cost from each demand point to the selected sites. - “within_threshold”: Boolean indicator of whether the demand point is within the specified coverage threshold. - A demand column specified by `site_problem._demand_data_demand_col`.	required
site_problem	object	Object containing problem configuration and metadata, including the name of the demand column via `_demand_data_demand_col`.	required
coverage_threshold	float	Threshold used to determine whether a demand point is considered covered. If provided, used to compute the proportion of demand points within coverage.	`None`
baseline_costs	dict[str, pandas.Series]	Maps a cost-column name (“min_cost”, or “min_cost__” for a registered secondary travel matrix) to a baseline per-region cost Series, indexed by demand-location ID (`site_problem._demand_data_id_col`). When given, `population_impact` (and the corresponding `demand_improved`/`regions_improved`/etc. keys in `return_solution_metrics()`) diff this combination’s own costs against it. `None` (the default) skips this entirely.	`None`
meaningful_change_threshold	float	Passed through to `_population_impact_metrics()` – see there for the improved/worsened/unchanged classification rule.	`0.0`
beyond_thresholds	float or sequence of float	One or more “left behind” travel-cost thresholds. For each value `t`, adds `demand_beyond_threshold_<t>` / `regions_beyond_ threshold_<t>` (headcount/region-count with a cost beyond `t`) to `return_solution_metrics()`, plus a `_by_equity_group` dict variant of each when equity data is registered. Deliberately a distinct parameter from `coverage_threshold`/`threshold_for_coverage` (opposite crossing direction: “covered” is good, “beyond” is bad) and, unlike it, supports more than one threshold at once. `None` (the default) adds no columns, keeping `solution_df`’s schema unchanged for callers that never ask for this.	`None`

Attributes

Name	Type	Description
solution_type	str	Type or label of the solution.
site_names	list of str	Names of the selected sites.
site_indices	list of int	Indices of the selected sites.
evaluated_combination_df	pandas.DataFrame	DataFrame containing per-demand-point evaluation results.
site_problem	object	Problem definition object.
coverage_threshold	float or None	Coverage threshold used in evaluation.
weighted_average	float	Demand-weighted average of the minimum cost.
unweighted_average	float	Simple (unweighted) average of the minimum cost.
percentile_90th	float	90th percentile of the minimum cost distribution.
max	float	Maximum minimum cost across all demand points.
total_cost	float	Total fixed cost of the selected sites (sum of the `cost_col` values configured via `add_sites()`). `NaN` if no `cost_col` was configured. Always calculated; only influences which solution is selected if explicitly passed as a weight (`weights={"cost": ...}`).
proportion_within_coverage_threshold	float	Proportion of total demand that falls within the coverage threshold, weighted by the demand registered via `add_demand()`. `NaN` if no `threshold_for_coverage` was supplied.
proportion_regions_within_coverage_threshold	float	Proportion of demand regions that fall within the coverage threshold, counting every region equally regardless of its demand. Identical to `proportion_within_coverage_threshold` when demand is uniform (including when `add_demand()` was never called).
population_impact	dict or None	`_population_impact_metrics()`’s output diffing this combination’s `min_cost` against `baseline_costs["min_cost"]`, or `None` if no `baseline_costs` was supplied.

Notes

The weighted average is computed using demand values as weights.

Methods

Name	Description
return_solution_metrics