add_equity_data

site.SiteProblem.add_equity_data(
    equity_data,
    equity_col,
    common_col,
    label,
    continuous_measure=False,
    n_bins=10,
    reverse=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.

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
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 applicable if continuous_measure is True. By default (False), lower continuous values are assigned to lower deciles (e.g., 1). If True, the mapping is inverted so that lower continuous values are assigned to the highest deciles. False

Raises

Name Type Description
ValueError If continuous_measure is True but the data cannot be meaningfully binned due to too many identical values.

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.

Back to top