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?”.