plot_equity_tertiles
site.SiteSolutionSet.plot_equity_tertiles(
solution_rank=1,
sort_by=None,
weighted=True,
show_tertile_averages=True,
colours=None,
title='default',
caption=None,
figsize=(9, 6),
ax=None,
matrix=None,
)Bar chart of average travel time per equity band, ordered most- to least-disadvantaged, with the most- and least-disadvantaged thirds highlighted and their own averages drawn across their bars – visually decomposing inter_tertile_ratio as “these bars against those bars” instead of leaving the reader to reconstruct its direction from a single number near 1.
Distinct from check_solution_equity(), which by default plots the unweighted mean of min_cost per band (every region counts equally). This method defaults to the demand-weighted mean (weighted_by_equity_group), because that is what inter_tertile_ratio is actually built from – the two can differ materially on real data, so a solution that looks balanced on one can look skewed on the other. Pass weighted=False to instead plot the same unweighted figure check_solution_equity() shows, for a direct comparison.
Entirely unreachable bands are excluded before splitting into thirds, matching the reported disparity metrics. The default caption names these exclusions; at least three reachable bands must remain.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| solution_rank | int | Rank of the solution to plot (1-indexed). | 1 |
| sort_by | str or None | Column name used to rank solutions before selecting solution_rank. If None, the existing order is used. |
None |
| weighted | bool | If True (the default), bars show the demand-weighted mean travel time per band (weighted_by_equity_group), matching inter_tertile_ratio. If False, bars show the plain (unweighted) mean instead, matching check_solution_equity(weighted=False) (its own default). |
True |
| show_tertile_averages | bool | If True, draw a dashed horizontal line across the most- and least-disadvantaged thirds at their own average, annotated with its value. | True |
| colours | tuple of str | (most_disadvantaged, middle, least_disadvantaged) bar colours. Defaults to a red/grey/blue triple already used elsewhere in this module for “worse/neutral/better” (plot_site_capacity_summary’s over/under-capacity colours). |
None |
| title | str | Plot title. If “default”, states the inter-tertile ratio and its plain-English verdict (inter_tertile_description) when weighted=True, or the two thirds’ own averages when weighted=False (which has no single official ratio to name). |
"default" |
| caption | str or None | None prints a short “how to read this” explanation of the bar colours and dashed lines. Pass "" to suppress it, or a custom string to replace it (matches _add_plot_caption’s existing convention on plot_site_capacity_summary() etc.). |
None |
| figsize | tuple | Figure size when this method creates its own figure (i.e. ax is None). Ignored otherwise. |
(9, 6) |
| ax | matplotlib.axes.Axes | Existing axes to draw onto instead of creating a new figure, e.g. to embed this as one panel of a larger layout. When given, the caller owns the figure’s lifecycle: this method does not call plt.tight_layout() or close the figure afterwards, and caption (if not suppressed) is still placed relative to the whole figure ax belongs to – pass caption="" if that would land awkwardly among other panels. |
None |
| matrix | str | Label of a secondary travel matrix registered via add_secondary_travel_matrix(). Requires that matrix to have been solved with solve(..., full_secondary_metrics=True), since the per-band breakdown this plot needs is only computed then. |
None |
Returns
| Name | Type | Description |
|---|---|---|
| matplotlib.figure.Figure |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If no equity data was registered, if fewer than 3 distinct equity bands have reachable regions (a tertile split is meaningless below that), or if matrix names a secondary travel matrix that was not solved with full_secondary_metrics=True. |