Plotting Utilities#

balsa.routines.plotting.convergence_boxplot(targets: DataFrame, results: DataFrame, filter_func: Callable[[Series], Series], *, adjust_target: bool = True, percentage: bool = True, band: Tuple[float, float] = None, simple_labels: bool = True, ax: Axes = None, fp: str | PathLike = None, title: str = None) → Axes#

Measures convergence of constrained location-choice models (such as work-location choice). Can be used to produce multiple box plots for different sub-sets of zones, usually based on size.

Parameters:

  • targets (pandas.DataFrame) –

  • results (pandas.DataFrame) –

  • filter_func (Callable[[pandas.Series], pandas.Series]) –

  • adjust_target (bool, optional) –

  • percentage (bool, optional) –

  • band (Tuple[float, float], optional) –

  • simple_labels (bool, optional) –

  • ax (Axes, optional) –

  • fp (str | PathLike, optional) –

  • title (str, optional) –

Returns:

matplotlib.Axes

balsa.routines.plotting.location_summary(model: DataFrame, target: DataFrame, ensemble_names: Series, *, title: str = '', fp: str | PathLike = None, dpi: int = 150, district_name: str = 'Ensemble') → Axes#

Creates a compound plot showing total attractions to specified locations

Parameters:

  • model (pandas.DataFrame) –

  • target (pandas.DataFrame) –

  • ensemble_names (pandas.Series) –

  • title (str, optional) –

  • fp (Path, optional) –

  • dpi (int, optional) –

  • district_name (str, optional) –

Returns:

matplotlib.Axes

balsa.routines.plotting.trumpet_diagram(counts: Series, model_volume: Series, *, categories: Series | List[Series] = None, category_colours: Dict[str | tuple, str] = None, category_markers: Dict[str | tuple, str] = None, label_format: str = None, title: str = '', y_bounds: Tuple[float, float] = (-2, 2), ax: Axes = None, x_label: str = 'Count volume', legend: bool = True, **kwargs) → Axes#

Plots an auto volumes “trumpet” diagram of relative error vs. target count, and will draw min/max error curves based on FHWA guidelines. Can be used to plot different categories of count locations.

Parameters:

  • counts (pandas.Series) – Target counts. Each item represents a different count location. Index does not need to be unique.

  • model_volume (pandas.Series) – Modelled volumes for each location. The index must match the counts Series.

  • categories (Union[pandas.Series, List[pandas.Series]], optional) – Defaults to None. Optional classification of each count location. Must match the index of the count Series. Can be provided as a List of Series (which all must match the count index) to enable tuple-based categorization.

  • category_colours (Dict[Union[str, tuple], str], optional) – Defaults to None. Mapping of each category to a colour, specified as a hex string. Only used when categories are provided. Missing categories revert to None, using the default colour for the style.

  • category_markers (Dict[Union[str, tuple], str], optional) – Defaults to None. Mapping of each category to a matplotlib marker string (see https://matplotlib.org/api/markers_api.html for options). Only used when categories are provided. Missing categories revert to None, using the default marker for the style.

  • label_format (str, optional) – Defaults to None. Used to convert category values (especially tuples) into readable strings for the plot legend. The relevant line of code is current_label = label_format % category_key. Only used when categories are provided.

  • title (str, optional) – The title to set on the plot.

  • y_bounds (tuple, optional) – Defaults to (-2, 2), or (-200%, 200%). Limit of the Y-Axis. This is needed because relative errors can be very high close to the y-intercept of the plot.

  • ax (matplotlib.Axes, optional) – Defaults to None. Sub-Axes to add this plot to, if using subplots().

  • x_label (str, optional) – Defaults to 'Count volume'. Label to use for the X-axis. The Y-axis is always “Relative Error”

  • legend (bool, optional) – Defaults to True. Flag to add a legend.

  • **kwargs – Additional kwargs to pass to DataFrame.plot.scatter()

Returns:

The Axes object generated from the plot. For most use cases, this is not really needed.

Return type:

matplotlib.Axes