Plotting Utilities

Plotting utilities for efficient frontiers and portfolio summaries.

pyvallocation.plotting.plot_assumptions_3d(mean, cov, *, scenarios=None, uncertainty_cov=None, n_std=1.0, uncertainty_std=1.0, max_points=2500, titles=None)[source]

Plot mean/covariance assumptions (and optional mean uncertainty) in 3D.

The function projects high-dimensional inputs onto the first three principal components implied by cov and renders: - a covariance ellipsoid around the mean, - optional scenario clouds, - and, when provided, a second panel for the mean-uncertainty ellipsoid.

Parameters:

  • mean (numpy.ndarray)

  • cov (numpy.ndarray)

  • scenarios (numpy.ndarray | None)

  • uncertainty_cov (numpy.ndarray | None)

  • n_std (float)

  • uncertainty_std (float)

  • max_points (int)

  • titles (Tuple[str, str] | None)

pyvallocation.plotting.plot_frontier_report(frontier, *, selection='min_risk', selection_kwargs=None, risk_label=None, overlay_risk_labels=None, show_points=True, percent_axes=True, weights=None, weights_title='Weights', figsize=(10.0, 4.0))[source]

Compact report plot: frontier plus selected weights bar.

Parameters:

  • frontier – Frontier to plot.

  • selection – Selector key (e.g. min_risk, tangency).

  • selection_kwargs – Keyword arguments for the selector.

  • risk_label – Optional risk label for the frontier x-axis.

  • overlay_risk_labels – Optional list of risk labels to overlay.

  • show_points – Whether to draw frontier nodes.

  • percent_axes – Whether to format axes as percentages.

  • weights – Optional pre-selected weights (skip selector).

  • weights_title – Title for the weights subplot.

  • figsize – Figure size in inches.

Returns:

matplotlib.figure.Figure – Figure containing the report plot.

Parameters:

  • frontier (PortfolioFrontier)

  • selection (str)

  • selection_kwargs (Mapping[str, object] | None)

  • risk_label (str | None)

  • overlay_risk_labels (Sequence[str] | None)

  • show_points (bool)

  • percent_axes (bool)

  • weights (pandas.Series | None)

  • weights_title (str)

  • figsize (Tuple[float, float])

pyvallocation.plotting.plot_frontiers(frontiers, *, ax=None, labels=None, highlight=('min_risk', 'max_return'), risk_free_rate=None, legend=True, line_kwargs=None, marker_kwargs=None, scatter_kwargs=None, show_points=False, percent_axes=False, overlay_risk_labels=None, risk_label=None, return_label='Expected Return', highlight_metadata_keys=None, metadata_value_formatter=None)[source]

Plot one or more efficient frontiers.

Parameters:

  • frontiers – Frontier instance(s) to be visualised.

  • ax – Optional matplotlib axis. If omitted, a new figure and axis are created.

  • labels – Optional labels associated with each frontier.

  • highlight – Iterable of portfolio markers to emphasise. Valid entries are "min_risk", "max_return" and "tangency".

  • risk_free_rate – Required when highlighting the tangency portfolio.

  • legend – Whether to render a legend.

  • line_kwargs – Keyword arguments passed to Axes.plot for the frontier lines.

  • marker_kwargs – Mapping from highlight name to keyword arguments for the corresponding scatter points.

  • scatter_kwargs – Global keyword arguments applied to all highlight markers.

  • show_points – When True, scatter all frontier nodes (useful for reports).

  • percent_axes – Format both axes as percentages (assumes decimal inputs).

  • overlay_risk_labels – Optional risk labels to overlay as dashed diagnostic lines (e.g., raw CVaR before convexification).

  • risk_label – Axis label for the risk dimension. If supplied, the plotting uses the corresponding risk grid (primary or alternate_risks) from each frontier. When omitted, the primary risk is used.

  • return_label – Axis label for expected returns.

  • highlight_metadata_keys – Optional iterable of metadata field names to append to highlight labels when the underlying PortfolioFrontier exposes metadata.

  • metadata_value_formatter – Optional callable used to render metadata values in highlight labels. Receives (key, value) and must return a string.

Returns:

The matplotlib Axes containing the plot. The axis is also populated with a _frontier_highlights attribute containing the highlighted points.

Parameters:

  • frontiers (PortfolioFrontier | Sequence[PortfolioFrontier] | Mapping[str, PortfolioFrontier])

  • labels (Sequence[str] | None)

  • highlight (Iterable[str])

  • risk_free_rate (float | None)

  • legend (bool)

  • line_kwargs (Mapping[str, object] | None)

  • marker_kwargs (Mapping[str, Mapping[str, object]] | None)

  • scatter_kwargs (Mapping[str, object] | None)

  • show_points (bool)

  • percent_axes (bool)

  • overlay_risk_labels (Sequence[str] | None)

  • risk_label (str | None)

  • return_label (str)

  • highlight_metadata_keys (Sequence[str] | None)

  • metadata_value_formatter (Callable[[str, object], str] | None)

pyvallocation.plotting.plot_frontiers_grid(frontiers, *, by=None, labels=None, cols=None, figsize=(12.0, 4.5), sharex=False, sharey=False, highlight=('min_risk', 'max_return'), risk_free_rate=None, legend=True, legend_policy='auto', **kwargs)[source]

Plot groups of efficient frontiers on a grid.

Parameters:

  • frontiers – Single frontier, sequence, or mapping of frontiers.

  • by – Optional grouping key function (label, frontier) -> group.

  • labels – Optional labels aligned to the frontier sequence.

  • cols – Number of columns in the grid. Defaults to len(groups).

  • figsize – Figure size in inches.

  • sharex – Whether to share x-axes across subplots.

  • sharey – Whether to share y-axes across subplots.

  • highlight – Iterable of highlight markers (e.g. min_risk).

  • risk_free_rate – Risk-free rate for tangency highlights.

  • legend – Whether to show legends.

  • legend_policy – auto (default), all, or none.

  • **kwargs – Forwarded to plot_frontiers().

Returns:

matplotlib.figure.Figure – Figure containing the grid of plots.

Parameters:

  • frontiers (PortfolioFrontier | Sequence[PortfolioFrontier] | Mapping[str, PortfolioFrontier])

  • by (Callable[[str | None, PortfolioFrontier], str] | None)

  • labels (Sequence[str] | None)

  • cols (int | None)

  • figsize (Tuple[float, float])

  • sharex (bool)

  • sharey (bool)

  • highlight (Iterable[str])

  • risk_free_rate (float | None)

  • legend (bool)

  • legend_policy (str)

pyvallocation.plotting.plot_param_impact(frontier, *, param='lambda', risk_label=None, percent_axes=False, ax=None)[source]

Plot parameter vs return/risk in a two-panel figure.

Parameters:

  • frontier – Frontier with metadata containing parameter values.

  • param – Metadata key to plot along the x-axis.

  • risk_label – Risk label for the risk panel.

  • percent_axes – Whether to format y-axes as percentages.

  • ax – Optional tuple of axes or a figure axis to reuse.

Returns:

Tuple[matplotlib.figure.Figure, tuple] – Figure and axes tuple.

Parameters:

  • frontier (PortfolioFrontier)

  • param (str)

  • risk_label (str | None)

  • percent_axes (bool)

pyvallocation.plotting.plot_robust_path(frontier, *, param='lambda', risk_label=None, overlay_risk_label=None, ax=None, cmap='viridis', percent_axes=False, show_points=True)[source]

Plot robust frontier with colour indicating parameter impact.

Parameters:

  • frontier – Robust frontier instance with metadata.

  • param – Metadata key to color by (default "lambda").

  • risk_label – Risk label for the x-axis.

  • overlay_risk_label – Optional risk label to overlay as a dashed line.

  • ax – Optional matplotlib axis to draw on.

  • cmap – Colormap name for parameter coloring.

  • percent_axes – Whether to format axes as percentages.

  • show_points – Whether to show individual frontier nodes.

Returns:

matplotlib.axes.Axes – Axis with the plot.

Parameters:

  • frontier (PortfolioFrontier)

  • param (str)

  • risk_label (str | None)

  • overlay_risk_label (str | None)

  • cmap (str)

  • percent_axes (bool)

  • show_points (bool)

pyvallocation.plotting.plot_robust_surface(frontier, *, param='lambda', risk_label=None, ax=None)[source]

3D scatter of parameter vs risk vs return for robust frontiers.

Parameters:

  • frontier – Frontier with metadata containing parameter values.

  • param – Metadata key to use for the x-axis and color.

  • risk_label – Risk label for the y-axis.

  • ax – Optional matplotlib 3D axis to reuse.

Returns:

matplotlib.axes.Axes – 3D axis with the scatter plot.

Parameters:

  • frontier (PortfolioFrontier)

  • param (str)

  • risk_label (str | None)

pyvallocation.plotting.plot_weights(weights, *, ax=None, top_n=None, title=None, kind='barh', stacked=False, percent_axes=True, legend=True)[source]

Plot portfolio weights (Series or DataFrame) with minimal setup.

Parameters:

  • weights – Weight Series or DataFrame.

  • ax – Optional matplotlib axis to draw on.

  • top_n – If set, plot only the largest top_n weights.

  • title – Optional plot title.

  • kind – Plot kind (e.g., barh or bar).

  • stacked – Whether to stack DataFrame columns.

  • percent_axes – If True format axes as percentages.

  • legend – Whether to show legend for DataFrame inputs.

Returns:

matplotlib.axes.Axes – Axis with the plot.

Parameters:

  • top_n (int | None)

  • title (str | None)

  • kind (str)

  • stacked (bool)

  • percent_axes (bool)

  • legend (bool)