plot_site_utilisation

site.SiteProblem.plot_site_utilisation(
    utilisation_df=None,
    site_names=None,
    site_indices=None,
    interactive=False,
    cmap='RdYlGn_r',
    missing_site_colour='lightgrey',
    marker_size_range=(40, 220),
    show_labels=False,
    add_basemap=True,
    tiles='CartoDB positron',
    title=None,
    caption=None,
    ax=None,
    figsize=None,
    **kwargs,
)

Map each candidate site’s current utilisation ratio.

Site markers are coloured and sized by utilisation_ratio from site_utilisation_summary(), so an analyst can see at a glance which sites are already near or over capacity today – entirely independent of solve() or any catchment/demand modelling.

Parameters

Name Type Description Default
utilisation_df pandas.DataFrame A precomputed result from site_utilisation_summary(). If None (the default), it is computed automatically using site_names/site_indices. None
site_names Forwarded to site_utilisation_summary() when utilisation_df is not supplied; see that method’s docstring (mutually exclusive). None
site_indices Forwarded to site_utilisation_summary() when utilisation_df is not supplied; see that method’s docstring (mutually exclusive). None
interactive bool If True, returns an interactive Folium map via .explore(). Otherwise returns a static matplotlib Axes. False
cmap str Colormap for site markers (utilisation_ratio). Deliberately the reversed variant of plot_accessibility’s site_cmap default (“RdYlGn”): there, a high ratio is good (uncontested supply); here, a high ratio is bad (near/at/over capacity), so red must map to the high end and green to the low end. "RdYlGn_r"
missing_site_colour str Colour (and static marker size, at the smallest of marker_size_range) for a site with no baseline utilisation data – typically a not-yet-built proposal. "lightgrey"
marker_size_range tuple of (float, float) Smallest and largest static marker size, linearly scaled by utilisation_ratio. Note this is the opposite sizing convention to plot_accessibility: there, a low (bad) ratio is drawn small; here, a high (bad) ratio is drawn large, so a hotspot is easier to spot on the map. Ignored on interactive maps, where Folium markers are a fixed size. (40, 220)
show_labels bool If True, adds text labels for each site (see plot_sites). Default False since colour/size already carry the signal. False
add_basemap bool If True, adds a background web map. Set False to skip the tile download entirely. True
title str Axes title. Ignored on interactive maps. None
caption str or None None prints a short “how to read this” explanation of the marker colour/size below the chart; pass "" to suppress it or a custom string to replace it, matching the existing caption convention on plot_accessibility() / plot_pareto_summary() / plot_site_reallocation_matrix() / plot_population_impact_histogram(). Static branch only. None
ax matplotlib.axes.Axes Existing axes to plot onto. Ignored if interactive=True. None
figsize tuple Passed to plt.subplots() if ax is not supplied. Ignored if interactive=True. None
**kwargs dict Additional keyword arguments passed to the site plotting call (GeoDataFrame.plot/.explore). {}

Returns

Name Type Description
matplotlib.axes.Axes or folium.Map

Raises

Name Type Description
ValueError If candidate_sites has no real geometry (i.e. add_sites() was never given a GeoDataFrame or lat/long columns), or if utilisation_df is not supplied and neither current_load_col+capacity_col nor utilisation_col was registered via add_sites() (see site_utilisation_summary()).
Back to top