macrosynergy.visuals.performance#

Module for plotting comparative return performance metrics across cross-sections, categories, or tickers.

view_performance(df, xcats=None, cids=None, tickers=None, start=None, end=None, val='value', bms=None, metrics=None, sort_by=None, title=None, title_fontsize=16, ylab=None, size=(14, 8), labels=None, legend_loc='upper center', legend_bbox_to_anchor=None, return_metrics=False, return_fig=False)[source]#

Plots comparative return performance metrics in a grouped bar chart.

Creates a bar chart showing performance metrics (annualized returns, standard deviation, Sharpe ratio, Sortino ratio, and optionally benchmark correlation) across cross-sections, categories, or specific tickers.

Parameters:

  • df (DataFrame) – Standardized DataFrame with the necessary columns: ‘cid’, ‘xcat’, ‘real_date’ and at least one column with values of interest (typically returns).

  • xcats (List[str], optional) – Extended categories to compare. Either xcats or cids or tickers must be specified, but not combinations.

  • cids (List[str], optional) – Cross-sections to compare. Either xcats or cids or tickers must be specified, but not combinations.

  • tickers (List[str], optional) – Specific tickers to compare (format: “CID_XCAT”). Either xcats or cids or tickers must be specified, but not combinations.

  • start (str, optional) – Earliest date in ISO format. Default is earliest date in df.

  • end (str, optional) – Latest date in ISO format. Default is latest date in df.

  • val (str) – Name of column that contains the values (returns). Default is ‘value’.

  • bms (str, optional) – Benchmark ticker (format: “CID_XCAT”) for correlation calculation. If None, benchmark correlation is not shown.

  • metrics (List[str], optional) – List of metrics to display. Available options: “Annualized return, %”, “Annualized SD, %”, “Sharpe ratio”, “Sortino ratio”, and “{bms} correl” (if bms provided). If None, all available metrics are shown. Default is None.

  • sort_by (str, optional) – Metric name to sort the items by (e.g., “Sharpe ratio”, “Annualized return, %”). Items will be sorted in descending order by this metric. If None, defaults to sorting by the first displayed metric. Default is None.

  • title (str, optional) – Chart title. If None, a default title is generated.

  • title_fontsize (int) – Font size of the title. Default is 16.

  • ylab (str, optional) – Y-axis label. Default is no label.

  • size (Tuple[float]) – Tuple of width and height of graph. Default is (14, 8).

  • labels (Union[List[str], dict], optional) – Custom labels for the compared items. If dict, maps from cid/xcat/ticker to label. If list, must match the order of items being compared.

  • legend_loc (str) – Location of legend; passed to matplotlib.pyplot.legend(). Default is ‘upper center’.

  • legend_bbox_to_anchor (Tuple[float], optional) – Passed to matplotlib.pyplot.legend(). Default is None, which positions the legend below the plot.

  • return_metrics (bool) – If True, return the metrics DataFrame instead of plotting. Default is False.

  • return_fig (bool) – If True, return the Matplotlib figure object instead of displaying. Default is False.

Returns:

If return_metrics=True, returns DataFrame with performance metrics. If return_fig=True, returns the figure object. Otherwise displays the plot and returns None.

Return type:

pd.DataFrame or matplotlib.figure.Figure or None

Notes

Performance metrics calculated: - Annualized return, %: Annualized return (mean * 261) - Annualized SD, %: Annualized standard deviation (std * sqrt(261)) - Sharpe ratio: Annualized return / annualized standard deviation - Sortino ratio: Annualized return / downside deviation - Benchmark correlation: Correlation with benchmark return series (if bms provided)