macrosynergy.visuals.heatmap#

A subclass inheriting from macrosynergy.visuals.plotter.Plotter, designed to plot time series data as a heatmap.

class Heatmap(df, cids=None, xcats=None, metrics=None, start=None, end=None, *args, **kwargs)[source]#

Bases: Plotter

Class for plotting time series data as a heatmap. Inherits from macrosynergy.visuals.plotter.Plotter.

Parameters:

  • df (DataFrame) – A DataFrame with the following columns: ‘cid’, ‘xcat’, ‘real_date’, and at least one metric from - ‘value’, ‘grading’, ‘eop_lag’, or ‘mop_lag’.

  • cids (List[str]) – A list of cids to select from the DataFrame. If None, all cids are selected.

  • xcats (List[str]) – A list of xcats to select from the DataFrame. If None, all xcats are selected.

  • metrics (List[str]) – A list of metrics to select from the DataFrame. If None, all metrics are selected.

  • start (str) – ISO-8601 formatted date. Select data from this date onwards. If None, all dates are selected.

  • end (str) – ISO-8601 formatted date. Select data up to and including this date. If None, all dates are selected.

plot(df, figsize=(12, 8), x_axis_label=None, y_axis_label=None, axis_fontsize=14, title=None, title_fontsize=22, title_xadjust=0.5, title_yadjust=1.0, footnote=None, footnote_fontsize=9, vmin=None, vmax=None, show=True, save_to_file=None, dpi=300, return_figure=False, on_axis=None, max_xticks=50, cmap=None, rotate_xticks=0, rotate_yticks=0, show_tick_lines=True, show_colorbar=True, show_annotations=False, show_boundaries=False, annotation_fontsize=14, tick_fontsize=13, *args, **kwargs)[source]#

Plots a DataFrame as a heatmap with the columns along the x-axis and rows along the y-axis.

Parameters:

  • figsize (Tuple) – tuple specifying the size of the figure. Default is (12, 8).

  • x_axis_label (str) – label for x-axis.

  • y_axis_label (str) – label for y-axis.

  • axis_fontsize (int) – the font size for the axis labels.

  • title (str) – the figure’s title.

  • title_fontsize (int) – the font size for the title.

  • title_xadjust (float) – sets the x position of the title text.

  • title_yadjust (float) – sets the y position of the title text.

  • footnote (str) – Optional text shown at the bottom-left of the figure canvas.

  • footnote_fontsize (int) – Font size of the footnote. Default is 9.

  • vmin (float) – optional minimum value for heatmap scale.

  • vmax (float) – optional maximum value for heatmap scale.

  • show (bool) – if True, the image is displayed.

  • save_to_file (str) – the path at which to save the heatmap as an image. If not specified, the plot will not be saved.

  • dpi (int) – the resolution in dots per inch used if saving the figure.

  • return_figure (bool) – if True, the function will return the figure.

  • on_axis (plt.Axes) – optional plt.Axes object to be used instead of creating a new one.

  • max_xticks (int) – the maximum number of ticks to be displayed along the x axis. Default is 50.

  • cmap (mpl.colors.Colormap) – string or matplotlib Colormap object specifying the colormap of the plot.

  • rotate_xticks (int) – number of degrees to rotate the tick labels on the x-axis. Default is zero.

  • rotate_yticks (int) – number of degrees to rotate the tick labels on the y-axis. Default is zero.

  • show_tick_lines (bool) – if True, lines are shown for ticks. Default is True.

  • show_colorbar (bool) – if True, the colorbar is shown. Default is True.

  • show_annotations (bool) – if True, annotations display the value of each cell. Default is False.

  • show_boundaries (bool) – if True, cells are divided by a grid. Default is False.

  • annotation_fontsize (int) – sets the font size of the annotations.

  • tick_fontsize (int) – sets the font size of tick labels.

Return type:

Optional[Figure]

plot_metric(x_axis_column, y_axis_column, metric, xcats=None, cids=None, start=None, end=None, freq=None, agg='mean', figsize=(12, 8), x_axis_label=None, y_axis_label=None, axis_fontsize=14, title=None, title_fontsize=22, title_xadjust=0.5, title_yadjust=1.0, footnote=None, footnote_fontsize=9, vmin=None, vmax=None, show=True, save_to_file=None, dpi=300, return_figure=False, on_axis=None, max_xticks=50, cmap=None, rotate_xticks=0, rotate_yticks=0, show_tick_lines=True, show_colorbar=True, show_annotations=False, show_boundaries=False, annotation_fontsize=14, tick_fontsize=13, *args, **kwargs)[source]#

Plots a metric from the DataFrame as a heatmap.

Parameters:

  • x_axis_column (str) – the column to be used as the x-axis.

  • y_axis_column (str) – the column to be used as the y-axis.

  • metric (str) – the metric to be plotted.

  • xcats (List[str]) – a list of xcats to select from the DataFrame. If None, all xcats are selected.

  • cids (List[str]) – a list of cids to select from the DataFrame. If None, all cids are selected.

  • start (str) – ISO-8601 formatted date string. Select data from this date onwards. If None, all dates are selected.

  • end (str) – ISO-8601 formatted date string. Select data up to and including this date. If None, all dates are selected.

  • freq (str) – frequency to downsample the data. Default is None.

  • agg (str) – aggregation method. Must be one of ‘mean’, ‘median’, ‘min’, ‘max’, ‘first’ or ‘last’.

  • figsize (Tuple[float, float]) – tuple specifying the size of the figure. Default is (12, 8).

  • x_axis_label (str) – label for x-axis.

  • y_axis_label (str) – label for y-axis.

  • axis_fontsize (int) – the font size for the axis labels.

  • title (str) – the figure’s title.

  • title_fontsize (int) – the font size for the title.

  • title_xadjust (float) – sets the x position of the title text.

  • title_yadjust (float) – sets the y position of the title text.

  • footnote (str) – Optional text shown at the bottom-left of the figure canvas.

  • footnote_fontsize (int) – Font size of the footnote. Default is 9.

  • vmin (float) – optional minimum value for heatmap scale.

  • vmax (float) – optional maximum value for heatmap scale.

  • show (bool) – if True, the image is displayed.

  • save_to_file (str) – the path at which to save the heatmap as an image. If not specified, the plot will not be saved.

  • dpi (int) – the resolution in dots per inch used if saving the figure.

  • return_figure (bool) – if True, the function will return the figure.

  • on_axis (plt.Axes) – optional plt.Axes object to be used instead of creating a new one.

  • max_xticks (int) – the maximum number of ticks to be displayed along the x axis. Default is 50.

  • cmap (mpl.colors.Colormap) – string or matplotlib Colormap object specifying the colormap of the plot.

  • rotate_xticks (int) – number of degrees to rotate the tick labels on the x-axis. Default is zero.

  • rotate_yticks (int) – number of degrees to rotate the tick labels on the y-axis. Default is zero.

  • show_tick_lines (bool) – if True, lines are shown for ticks. Default is True.

  • show_colorbar (bool) – if True, the colorbar is shown. Default is True.

  • show_annotations (bool) – if True, annotations display the value of each cell. Default is False.

  • show_boundaries (bool) – if True, cells are divided by a grid. Default is False.

  • annotation_fontsize (int) – sets the font size of the annotations.

  • tick_fontsize (int) – sets the font size of tick labels.