add_equity_data
site.SiteProblem.add_equity_data(
equity_data,
equity_col,
common_col,
label,
disadvantaged_end=None,
continuous_measure=False,
n_bins=10,
reverse=False,
verbose=True,
direction=None,
primary=None,
replace=False,
)Add a dataframe containing equity data into your problem.
This method associates demand points with an equity metric (such as the Index of Multiple Deprivation). If a continuous measure is provided, it is automatically discretized into deciles (or maximum possible quantiles) to facilitate categorical plotting and comparative equity analysis.
Call it more than once to register several equity dimensions – e.g. deprivation, rurality and ethnicity – each under its own label. Every registered dimension is merged into each solution’s problem_df, so any of them can be selected for analysis by label. Exactly one is the primary dimension: the one solve() computes its solution_df equity columns (inter_tertile_ratio, weighted_by_equity_group, …) against, and the one weights={"equity": ...} weights by. See primary below, and show_equity_dimensions() for what is currently registered.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| equity_data | str, pandas.DataFrame, or geopandas.GeoDataFrame | The input data containing the equity metrics. Can be a filepath or an already loaded dataframe object. | required |
| equity_col | str | The name of the column in equity_data containing the equity values or categories to be used. |
required |
| common_col | str | The name of the ID column used to join this data to the primary demand/spatial data in the SiteProblem. | required |
| label | str | A human-readable label for the equity metric (e.g., ‘IMD Decile’, ‘Age Group’). This is used internally for auto-generating plot titles and table headers. | required |
| disadvantaged_end | (low, high) | Which end of the equity_col scale represents the most disadvantaged (e.g. most deprived) regions. This is stored as metadata and applied at analysis time — it does not modify the stored data. Equity-aware weighting and analysis prioritise whichever end you name here. - "low" : the lowest values are the most disadvantaged (e.g. IMD decile 1 = most deprived under the standard DLUHC 1–10 scale). - "high" : the highest values are the most disadvantaged (e.g. raw IMD score, where a higher score means more deprived; or a custom scale where 1 = least deprived). .. note:: IMD deciles as published by DLUHC run 1 (most deprived) to 10 (least deprived), so for pre-binned IMD decile columns use disadvantaged_end="low". For raw IMD scores (higher = more deprived) use disadvantaged_end="high". |
"low" |
| continuous_measure | bool | If True, treats equity_col as continuous numerical data and uses quantile-based discretization to convert it into deciles (1-10). The raw continuous data is preserved in a new column named {equity_col}_raw. |
False |
| reverse | bool | Only used when continuous_measure=True. Controls the direction of bin labelling relative to the raw values: - False (default): lower raw values receive lower bin numbers. - True: lower raw values receive higher bin numbers (i.e. the labelling is inverted). This is purely a binning convenience — for instance, to convert a raw IMD score (where lower = less deprived) into a decile where 1 = least deprived. It is independent of direction, which governs downstream analysis rather than how bins are labelled. |
False |
| verbose | bool | If True, output additional warnings and messages | True |
| primary | bool | Whether this dimension becomes the primary one (see above). Required – and rejected as ambiguous if omitted – only when registering a new label on a problem that already has an equity dimension. That case used to overwrite the existing dimension, so silently registering alongside it and leaving the first as primary would keep old code running while quietly changing which bands its numbers describe. Defaults are unambiguous everywhere else: the first dimension registered is always primary (passing primary=False for it raises), and re-registering an existing label with replace=True keeps that label’s current primary status unless you say otherwise. |
None |
| replace | bool | Overwrite the dimension already registered under label. Without it, re-using a label raises rather than silently replacing the data behind it. Passing it for a label that isn’t registered also raises, rather than quietly registering a new dimension. |
False |
| direction | (higher_is_better, higher_is_worse) | .. deprecated:: Use disadvantaged_end instead. "higher_is_better" (higher values = more advantaged, e.g. DLUHC IMD deciles) maps to disadvantaged_end="low"; "higher_is_worse" (higher values = more disadvantaged, e.g. raw IMD scores) maps to disadvantaged_end="high". Passing both arguments raises a ValueError. |
"higher_is_better" |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If continuous_measure is True but the data cannot be meaningfully binned due to too many identical values; if label is already registered and replace is not True; if replace=True names a label that is not registered; if a new label is registered alongside an existing dimension without an explicit primary; if primary=False is given for the only registered dimension; or if equity_col is already used by another registered dimension (they share one per-region frame, so one would overwrite the other). |
Notes
When continuous_measure is True, pandas.qcut is used with duplicates='drop'. If the data is highly skewed with duplicate values, this may result in fewer than 10 bins. The method handles this dynamically to ensure the resulting categories always start at 1.