plot_site_capacity_summary

site.SiteSolutionSet.plot_site_capacity_summary(
    metric='allocated_utilisation_ratio',
    capacity_df=None,
    capacity_col=None,
    demand_to_capacity_rate=1.0,
    sort_by=None,
    solution_rank=1,
    site_names=None,
    site_indices=None,
    matrix=None,
    demand=None,
    interactive=True,
    sort=True,
    under_capacity_colour='#4C72B0',
    over_capacity_colour='#C44E52',
    missing_colour='lightgrey',
    show_reference_line=True,
    title='default',
    x_axis_label='default',
    y_axis_label='default',
    caption=None,
    interactive_width=800,
    interactive_height=600,
    static_width=10,
    static_height=6,
    ax=None,
)

Bar chart of site_capacity_summary() for one chosen solution.

Parameters

Name	Type	Description	Default
metric	(allocated_utilisation_ratio, incremental_headroom_ratio)	Which `site_capacity_summary()` ratio to plot. “allocated_utilisation_ratio” assumes the allocated demand replaces today’s activity entirely – the whole-network reallocation `solve()` actually models. “incremental_headroom_ratio” assumes it lands on top of today’s activity instead, and raises if no baseline load data (`current_load_col`/`utilisation_col`) was registered. These two answer genuinely different questions – see `site_capacity_summary`’s Notes before picking one.	`"allocated_utilisation_ratio"`
capacity_df	pandas.DataFrame	A precomputed result from `site_capacity_summary()`. If given, `capacity_col`, `demand_to_capacity_rate`, and the solution selection arguments below are ignored entirely – the frame is used exactly as supplied, matching `plot_accessibility(region_frame=...)`.	`None`
capacity_col			`None`
demand_to_capacity_rate			`None`
sort_by			`None`
solution_rank			`None`
site_names		Passed straight through to `site_capacity_summary()` when `capacity_df` is not supplied.	`None`
site_indices		Passed straight through to `site_capacity_summary()` when `capacity_df` is not supplied.	`None`
matrix		Passed straight through to `site_capacity_summary()` when `capacity_df` is not supplied.	`None`
demand		Passed straight through to `site_capacity_summary()` when `capacity_df` is not supplied.	`None`
interactive	bool	If True, generates an interactive Plotly bar chart. If False, generates a static Matplotlib bar chart.	`True`
sort	bool	If True, bars are ordered ascending by `metric`. NaN values (no capacity registered for that site) sort last. If False, sites keep canonical site-index order.	`True`
under_capacity_colour	str	Colours for bars at or below, and above, the reference value (`1.0` for `allocated_utilisation_ratio`; `0.0` for `incremental_headroom_ratio`, where negative means already over capacity today). Colour here is deliberately semantic (over/under), not categorical by site as in `plot_site_allocation_summary` – the finding this chart exists to show is whether a site fits, not which site is which, so `site_color_map` is not offered.	`'#4C72B0'`
over_capacity_colour	str	Colours for bars at or below, and above, the reference value (`1.0` for `allocated_utilisation_ratio`; `0.0` for `incremental_headroom_ratio`, where negative means already over capacity today). Colour here is deliberately semantic (over/under), not categorical by site as in `plot_site_allocation_summary` – the finding this chart exists to show is whether a site fits, not which site is which, so `site_color_map` is not offered.	`'#4C72B0'`
missing_colour	str	Colour for a site with no capacity registered (`NaN` ratio).	`"lightgrey"`
show_reference_line	bool	If True, draws a vertical line at the reference value (see `under_capacity_colour` above) labelled “at capacity”.	`True`
caption	str or None	`None` prints a short “how to read this” explanation of the reference line and, for `metric="incremental_headroom_ratio"`, that this treats allocated demand as landing on top of today’s activity. Pass `""` to suppress it, or a custom string to replace it. Static branch only (matches `_add_plot_caption`’s existing convention on `plot_accessibility()` etc.).	`None`
ax	matplotlib.axes.Axes	Existing axes to draw the static chart onto instead of creating a new figure, e.g. to embed this as one panel of a larger layout. Ignored if `interactive=True`. When given, the caller owns the figure’s lifecycle: unlike the default (self-contained) case, this method does not call `plt.tight_layout()` or close the figure afterwards. `caption` (if not suppressed) is still placed relative to the whole figure `ax` belongs to, not just this panel – pass `caption=""` if that would land awkwardly among the other panels of a shared figure.	`None`

Returns

Name	Type	Description
	plotly.graph_objects.Figure or matplotlib.figure.Figure

Raises

Name	Type	Description
	ValueError	If `metric` is invalid, or if `metric="incremental_headroom_ratio"` but no baseline load data was registered.

Notes

A site with NaN capacity is drawn as a zero-length bar labelled “N/A”, coloured missing_colour – not 0, which would misleadingly read as “empty”. A site with an infinite ratio (zero registered capacity but nonzero allocated load) is drawn at a finite length (just past the largest finite bar) so the axis stays usable, but labelled with the infinity symbol – the bar’s length is a drawing convenience only, not a real value.