site_reallocation_matrix

site_solutions.SolutionComparator.site_reallocation_matrix(
    matrix=None,
    demand=None,
    config_a=None,
    config_b=None,
    by='demand',
    changed_only=False,
)

Cross-tabulate each demand location’s closest site under set_a against its closest site under set_b – “if a region’s nearest site changed, which site did it move from, and which did it move to?”

A single table answers both directions of “reallocation”: read a row (a set_a site) across to see where that site’s demand ended up in set_b – e.g. a closed site’s row shows exactly which remaining sites picked up its patients. Read a column (a set_b site) down to see which set_a sites its demand came from – e.g. a newly opened site’s column shows which existing sites it drew demand away from. The diagonal (same site name in both) is the demand that didn’t move at all.

Parameters

Name Type Description Default
matrix str Label of a secondary travel matrix registered via add_secondary_travel_matrix(). Cross-tabulates each side’s selected_site__<label> column instead of the primary matrix’s selected_site. None
demand str Label of a secondary demand scenario registered via add_secondary_demand(). Weights by that scenario’s demand instead of the primary demand data (only relevant for by="demand"). None
config_a dict Passed to _select_solution() to choose which solution from set_a/set_b to compare (e.g. {"solution_rank": 2}). Default to {"solution_rank": 1}. None
config_b dict Passed to _select_solution() to choose which solution from set_a/set_b to compare (e.g. {"solution_rank": 2}). Default to {"solution_rank": 1}. None
by (demand, regions) “demand” sums the registered demand weight moving between each (from-site, to-site) pair; “regions” counts demand locations instead, ignoring demand weighting entirely – the only option available when no demand data is registered. "demand"
changed_only bool If True, drop every row/column whose site didn’t actually experience any reallocation – see Notes for the precise rule. Rows and columns are dropped independently, so a site that kept 100% of its own patients but also picked up new ones from elsewhere still keeps its column (something new arrived) even though its row is dropped (nothing left). False

Returns

Name Type Description
pandas.DataFrame Rows = set_a’s selected sites, columns = set_b’s selected sites. Cell (i, j) = the demand (or region count) whose closest site was i under set_a and is j under set_b. Every selected site gets a full row/column even if it captures no reallocated demand at all – those cells are 0.0, not NaN, since “nothing moved this way” is a real, meaningful answer (matching site_allocation_summary()’s own “explicit 0” convention). The index/column names are self.labels[0]/self.labels[1]. Each axis is ordered persisting sites first (present on both sides, in canonical site-index order), then that axis’s own “changed” sites last (closed sites at the bottom of the row axis; newly opened sites at the right of the column axis). Otherwise an unrelated unchanged site could sort after the genuinely closed/opened ones purely by candidate index, burying the actual reallocation in the middle of the table instead of grouping it where it’s easy to scan.

Raises

Name Type Description
ValueError If by is not “demand” or “regions”; if by="demand" but no demand data is registered (see Notes); if demand names an unregistered secondary demand scenario; or if set_a and set_b’s selected solutions were evaluated against different demand locations (via _population_impact_frame).

Notes

changed_only’s precise rule: a row is dropped only if its site is also a column (i.e. it persists into set_b) AND every one of its cells outside that same-named column is 0 – meaning none of that site’s own demand went anywhere else. A closed site (no matching column at all) is never dropped, since its departure is exactly the event this method exists to show. Columns are dropped by the mirror-image rule (site persists from set_a AND received nothing from any other row); a newly opened site (no matching row) is never dropped either. This means a site that kept 100% of its own patients but ALSO gained new ones from elsewhere loses its row (nothing left) while keeping its column (something arrived) – rows and columns are independent, not a single “this site is boring, drop it entirely” decision.

To instead see only what the review persona literally asked for – “closed sites down the left, the sites they moved to across the top” – slice the (changed_only=False) result yourself using the already-available sites_closed_vs_baseline/ sites_added_vs_baseline columns: result.loc[closed_sites] for “where did each closed site’s demand go?”, or result[added_sites] for “which sites did each added site draw demand from?”.

Back to top