qis.plot_scatter

qis.plot_scatter(df, x=None, y=None, hue=None, xlabel=True, ylabel=True, title=None, annotation_labels=None, annotation_colors=None, annotation_markers=None, annotation_color='red', add_universe_model_label=True, add_universe_model_prediction=False, add_universe_model_ci=False, add_hue_model_label=None, ci=None, order=2, full_sample_order=2, fit_intercept=True, full_sample_color='blue', colors=None, xvar_format='{:.0%}', yvar_format='{:.0%}', x_limits=None, y_limits=None, xticks=None, fontsize=10, linewidth=1, markersize=4, hue_linestyles=None, full_sample_label='Full sample: ', add_45line=False, align_axis=False, legend_loc='upper left', ax=None, **kwargs)[source]

x-y scatter with a fitted relationship, optionally split by a grouping variable.

The fit is the point: a polynomial of degree order is drawn through the full sample and, when hue is given, through each group separately, so the question “does the relationship hold within groups” is answered by the same chart that shows the scatter.

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

Parameters:

  • df (DataFrame) – data to plot; x and y name its columns

  • x (str) – column for the horizontal axis. None takes the first column

  • y (str) – column for the vertical axis. None takes the second column

  • hue (str) – column whose values split the sample into separately fitted groups

  • annotation_labels (List[str]) – text to place beside each point, in row order

  • annotation_colors (List[str]) – colour per annotated point

  • annotation_markers (List[str]) – marker per annotated point

  • annotation_color (str | None) – colour used when annotation_colors is None

  • add_universe_model_label (bool) – report the full-sample fit in the legend

  • add_universe_model_prediction (bool) – draw the full-sample fitted line

  • add_universe_model_ci (bool) – shade the confidence band of the full-sample fit

  • add_hue_model_label (bool | None) – report each group fit in the legend. None follows whether hue was given

  • ci (int | None) – confidence level for the bands, as a percentage. None draws none

  • order (int) – polynomial degree of the per-group fit. 1 is a straight line, 2 a quadratic

  • full_sample_order (int | None) – polynomial degree of the full-sample fit, which need not match the per-group order. None fits nothing on the full sample

  • fit_intercept (bool) – fit an intercept. False forces the line through the origin, which is what a beta regression on excess returns wants

  • full_sample_color (str) – colour of the full-sample fitted line

  • xticks (List[str]) – explicit tick positions on the horizontal axis

  • linewidth (int) – width of the fitted lines

  • hue_linestyles (Dict[str, str]) – line style per group value, for distinguishing fits in monochrome

  • full_sample_label (str) – legend prefix for the full-sample fit

  • add_45line (bool) – draw the y = x diagonal, for comparing two estimates of the same quantity

  • align_axis (bool) – force the two axes onto the same limits, which the 45-degree line needs to be meaningful

  • xlabel (str | bool | None)

  • ylabel (str | bool | None)

  • title (str | None)

  • colors (List[str])

  • xvar_format (str)

  • yvar_format (str)

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

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

  • fontsize (int)

  • markersize (int)

  • legend_loc (str | None)

  • ax (Axes)

Returns:

the figure drawn on, or None when ax was supplied

Return type:

Figure