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.
Back to top