qis.plot_bars

qis.plot_bars(df, stacked=True, date_format='%d-%b-%y', x_date_freq='QE', title=None, fontsize=10, add_bar_values=False, add_top_bar_values=False, is_top_totals=False, totals=None, legend_stats=LegendStats.NONE, xvar_format='{:.1%}', yvar_format='{:,.2f}', x_rotation=90, total_rotation=0, skip_y_axis=False, legend_loc='upper center', bbox_to_anchor=None, y_limits=None, annotate_totals=True, totals_offset=(2.55, 5), series_color='steelblue', colors=None, legend_labels=None, legend_colors=None, vline_columns=None, xlabel=None, ylabel=None, reverse_columns=False, is_sns=True, alpha=0.9, x_loc_width_shift=0.2, add_avg_line=False, is_horizontal=False, labels_frequency=None, ax=None, **kwargs)[source]

plot columns of a DataFrame as bars, grouped or stacked, one group per index entry.

Stacked is the default because the usual subject is a decomposition — exposures by asset class, attribution by group — where the total is as interesting as the parts. Set stacked=False for side-by-side comparison of series that do not sum to anything.

Arguments shared with every plot_* function are documented in qis/docs/plotting_kwargs.md.

Parameters:

  • df (DataFrame | Series) – values to draw, one bar group per index entry and one bar per column

  • stacked (bool) – stack the columns within each group rather than placing them side by side

  • date_format (str) – strftime format for a DatetimeIndex on the category axis

  • add_bar_values (bool) – annotate each bar segment with its own value

  • add_top_bar_values (bool) – annotate only the topmost segment of a stacked group

  • is_top_totals (bool) – place the group total above the bar rather than inside it

  • totals (List[float]) – group totals to annotate. None computes the row sum, which is the total only when the columns are additive; pass it explicitly when they are not

  • legend_stats (LegendStats) – summary statistics appended to each legend entry

  • x_rotation (int) – rotation in degrees of the category labels

  • total_rotation (int) – rotation in degrees of the total annotations

  • skip_y_axis (bool) – draw no vertical axis, for a bar row read entirely from its labels

  • bbox_to_anchor (Tuple[float, float] | None) – legend anchor passed to matplotlib, for placing the legend outside

  • annotate_totals (bool) – draw the totals at all

  • totals_offset (Tuple[float, float]) – (x, y) offset in points of the total annotation from the bar

  • series_color (str) – colour used when the frame has a single column and colors is None

  • legend_labels (List[str]) – replace the column names in the legend

  • legend_colors (List[str]) – legend swatch colours, when they should differ from the bar colours

  • vline_columns (List[int]) – positions after which to draw a vertical separator, to group categories

  • reverse_columns (bool) – reverse the column order, which reverses the stacking order

  • is_sns (bool) – draw through seaborn rather than matplotlib directly

  • alpha (float) – bar opacity

  • x_loc_width_shift (float) – horizontal offset of grouped bars within a category

  • add_avg_line (bool) – draw a horizontal line at the mean of the plotted values

  • is_horizontal (bool) – draw horizontal bars, which reads better with long category names

  • labels_frequency (int | None) – label every nth category. None labels all of them

  • x_date_freq (str)

  • title (str)

  • fontsize (int)

  • xvar_format (str)

  • yvar_format (str)

  • legend_loc (str | None)

  • y_limits (Tuple[float | None, float | None])

  • colors (List[str])

  • xlabel (str)

  • ylabel (str)

  • ax (Axes)

Returns:

the figure drawn on, or None when ax was supplied

Return type:

Figure | None