Callout Line Plot
A single line of pre-aggregated data with events called out on it.
plot(df, value_col, callouts, callout_title_col=None, callout_text_col=None, x_col=None, callout_x_col=None, title=None, eyebrow=None, subtitle=None, x_label=None, y_label=None, source_text=None, ax=None, figsize=None, show_markers=True, **kwargs)
Plot value_col as one line and call out the events in callouts on it.
Each row of callouts becomes a bold title, wrapped text or both, joined by a leader to
the line at that row's x value. An x value between two rows of df is anchored on the
straight segment joining them. No callout text touches the line, another callout or a leader,
and the y-axis is given extra headroom when the callouts need the room.
df is not aggregated: pass one row per x value. The layout fits the figure's size and the
axis limits at call time, so pass figsize (or an ax on a figure already at its final
size) instead of resizing the figure afterwards, and do not change the limits afterwards. That
rules out an ax whose y-axis is shared with a chart drawn later, and a second call on the
same ax.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
The line's data, one row per x value. |
required |
value_col
|
str
|
The column to plot. |
required |
callouts
|
DataFrame
|
One row per callout. |
required |
callout_title_col
|
str
|
The |
None
|
callout_text_col
|
str
|
The |
None
|
x_col
|
str
|
The column to use as the x-axis, datetime or numeric. If None, the index is used. |
None
|
callout_x_col
|
str
|
The |
None
|
title
|
str
|
The title of the plot. |
None
|
eyebrow
|
str
|
Small uppercase label rendered above the title. |
None
|
subtitle
|
str
|
Supporting copy rendered below the title. |
None
|
x_label
|
str
|
X-axis label; omitted means no label. |
None
|
y_label
|
str
|
Y-axis label; omitted means no label. |
None
|
source_text
|
str
|
The source text to add to the plot. |
None
|
ax
|
Axes
|
Matplotlib axes object to plot on. |
None
|
figsize
|
tuple[float, float]
|
Figure size in inches when |
None
|
show_markers
|
bool
|
Draw a dot on the line at each callout's point. Defaults to True. |
True
|
**kwargs
|
Any
|
Additional keyword arguments for matplotlib's |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
Axes |
Axes
|
The matplotlib axes object. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
TypeError
|
If |
TypeError
|
If the line's x values are neither datetime nor numeric, or the callouts' x values are not of the same type. |
ValueError
|
If a named column is missing, or |
ValueError
|
If |
ValueError
|
If |
ValueError
|
If the values, x values, callout x values, titles or texts contain missing values. |
ValueError
|
If the values or the line's x values contain infinite values. |
ValueError
|
If a callout's title and text are both blank. |
ValueError
|
If the line's x values are not unique. |
ValueError
|
If a callout's x value is outside the range of the line's x values. |
ValueError
|
If the callouts cannot all be placed without overlapping; the message names the callouts left over. |
Examples:
>>> from openretailscience.plots import callout_line
>>> weekly = pd.DataFrame({"week": range(1, 9), "revenue": [52, 55, 54, 81, 60, 58, 44, 57]})
>>> events = pd.DataFrame({"week": [4, 7], "event": ["Week 4", "Week 7"], "note": ["Easter", "Tills down"]})
>>> ax = callout_line.plot(
... df=weekly, value_col="revenue", x_col="week",
... callouts=events, callout_title_col="event", callout_text_col="note",
... eyebrow="Trading", title="Weekly revenue and what moved it", subtitle="Revenue, £K",
... )
Source code in openretailscience/plots/callout_line.py
781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 | |