plot_best_combination

site.SiteSolutionSet.plot_best_combination(
    ax=None,
    sort_by=None,
    solution_rank=1,
    site_names=None,
    site_indices=None,
    title='default',
    show_all_locations=True,
    label_all_locations=False,
    plot_site_allocation=False,
    plot_regions_not_meeting_threshold=False,
    cmap=None,
    chosen_site_colour='black',
    unchosen_site_colour='white',
    unchosen_site_opacity=0.7,
    legend_loc='upper right',
    legend_bbox_to_anchor=(1.75, 0.5),
    legend_fontsize=10,
    title_fontsize=12,
    annotation_size=6,
    label_wrap_width=40,
    height=12,
    width=6,
    site_legend_loc='best',
    matrix=None,
)

Plot a map of the best-performing site combination.

This method visualises the spatial performance of the best solution in the solution set, including travel costs, site allocations, or coverage relative to a threshold. Regions are coloured according to the selected metric, and candidate site locations can be overlaid.

Parameters

Name Type Description Default
sort_by str Column name used to rank solutions. If provided, solutions are ranked best-first by this column – highest for coverage proportions, lowest for travel costs. Ignored if site_names or site_indices is provided. None
solution_rank int Which ranked solution to plot (1 = best, 2 = second best, etc.). Ignored if site_names or site_indices is provided. 1
site_names list of str Specific site names to plot. If provided, filters solution_df to the row containing this exact combination of sites. Overrides sort_by and solution_rank. None
site_indices list of int or np.ndarray Specific site indices to plot. If provided, filters solution_df to the row containing this exact combination. Overrides sort_by, solution_rank, and site_names. None
title str or None Title for the plot. If “default”, an automatic title is generated based on the objective and solution metrics. If a string is provided, it may be evaluated using _safe_evaluate with access to the selected solution. If None, no title is set. "default"
show_all_locations bool If True, plots all candidate site locations in addition to the selected sites. True
plot_site_allocation bool If True, regions are coloured by the assigned (nearest) site. Overrides other colouring options. False
plot_regions_not_meeting_threshold bool If True, regions are coloured based on whether they fall within the coverage threshold. Overrides default cost-based colouring. False
cmap str or matplotlib colormap Colormap used for plotting. If None, a default is chosen: - Sequential colormap (“Blues”) for cost-based plots - Qualitative colormap (“Set2”) for site allocation plots None
chosen_site_colour str Colour used to plot selected site locations. "black"
unchosen_site_colour str Colour used to plot unselected candidate site locations. "grey"
unchosen_site_opacity float Opaqueness/alpha of the points for unchosen sites 0.5
legend_loc Adjust position of the legend within the main plot. Accepts standard matplotlib positioning strings. 'upper right'
site_legend_loc Adjust position of the legend within the main plot. Accepts standard matplotlib positioning strings. Only used if required sites are present in the problem. 'best'
legend_bbox_to_anchor tuple or None If provided, places the legend outside the plot area. Accepts a 2-tuple (x, y) in axes coordinates. Common examples: - (1.05, 1) for right side, top aligned - (0.5, -0.1) for bottom center - (1.05, 0.5) for right side, center aligned When set, legend_loc is used as the anchor point on the legend box. None
legend_fontsize int or float Font size for legend text. 10
title_fontsize int or float Font size for the plot title. 12
label_wrap_width int Maximum character width before wrapping legend labels. Set to None to disable wrapping. 40
annotation_size Font size of site name annotations on the map 6
matrix str Label of a secondary travel matrix registered via add_secondary_travel_matrix(). If provided, the plot and its title metrics use that matrix’s columns and unit instead of the primary travel matrix. None

Returns

Name Type Description
matplotlib.axes.Axes The matplotlib Axes object containing the generated plot.

Raises

Name Type Description
ValueError If the region geometry layer has not been initialised in the site_problem instance.

Notes

The method requires a valid region_geometry_layer to be present in site_problem. This should be added prior to calling this method.

The plot is generated using GeoPandas and includes a basemap via contextily.add_basemap.

Depending on the flags provided, regions are coloured by: - “min_cost” (default): travel time/distance to the nearest site - “selected_site”: assigned site (categorical) - “within_threshold”: whether the region meets the coverage threshold

Site markers require candidate_sites to carry real point geometry. This holds both for sites registered via a GeoDataFrame/geojson and for tabular lat/long input, which add_sites() converts internally – it does not hold if site names were inferred from the travel matrix’s columns without ever calling add_sites().

Titles are dynamically generated based on the objective type and may include metrics such as weighted/unweighted averages, maximum cost, and coverage proportion.

The method assumes that lower values of the ranking metric correspond to better solutions.

Back to top