mgplot

41class BarKwargs(BaseKwargs):
42    """Keyword arguments for the bar_plot function."""
43
44    # --- options for the entire bar plot
45    ax: NotRequired[Axes | None]
46    stacked: NotRequired[bool]
47    max_ticks: NotRequired[int]
48    plot_from: NotRequired[int | Period]
49    label_rotation: NotRequired[int | float]
50    # --- options for each bar ...
51    color: NotRequired[str | Sequence[str]]
52    label_series: NotRequired[bool | Sequence[bool]]
53    width: NotRequired[float | int | Sequence[float | int]]
54    zorder: NotRequired[int | float | Sequence[int | float]]
55    # --- options for bar annotations
56    annotate: NotRequired[bool]
57    fontsize: NotRequired[int | float | str]
58    fontname: NotRequired[str]
59    rounding: NotRequired[int]
60    rotation: NotRequired[int | float]
61    annotate_color: NotRequired[str]
62    above: NotRequired[bool]

21class FillBetweenKwargs(BaseKwargs):
22    """Keyword arguments for the fill_between_plot function."""
23
24    ax: NotRequired[Axes | None]
25    color: NotRequired[str]
26    alpha: NotRequired[float]
27    label: NotRequired[str | None]
28    linewidth: NotRequired[float]
29    edgecolor: NotRequired[str | None]
30    zorder: NotRequired[int | float]
31    plot_from: NotRequired[int | None]
32    max_ticks: NotRequired[int]

31class FinaliseKwargs(BaseKwargs):
32    """Keyword arguments for the finalise_plot function."""
33
34    # --- value options
35    suptitle: NotRequired[str | None]
36    title: NotRequired[str | None]
37    xlabel: NotRequired[str | None]
38    ylabel: NotRequired[str | None]
39    xlim: NotRequired[tuple[float, float] | None]
40    ylim: NotRequired[tuple[float, float] | None]
41    xticks: NotRequired[list[float] | None]
42    yticks: NotRequired[list[float] | None]
43    xscale: NotRequired[str | None]
44    yscale: NotRequired[str | None]
45    # --- splat options
46    legend: NotRequired[bool | dict[str, Any] | None]
47    axhspan: NotRequired[dict[str, Any] | None]
48    axvspan: NotRequired[dict[str, Any] | None]
49    axhline: NotRequired[dict[str, Any] | None]
50    axvline: NotRequired[dict[str, Any] | None]
51    # --- options for annotations
52    lfooter: NotRequired[str]
53    rfooter: NotRequired[str]
54    lheader: NotRequired[str]
55    rheader: NotRequired[str]
56    # --- file/save options
57    pre_tag: NotRequired[str]
58    tag: NotRequired[str]
59    chart_dir: NotRequired[str]
60    file_type: NotRequired[str]
61    dpi: NotRequired[int]
62    figsize: NotRequired[tuple[float, float]]
63    show: NotRequired[bool]
64    # --- other options
65    preserve_lims: NotRequired[bool]
66    remove_legend: NotRequired[bool]
67    zero_y: NotRequired[bool]
68    y0: NotRequired[bool]
69    x0: NotRequired[bool]
70    axisbelow: NotRequired[bool]
71    dont_save: NotRequired[bool]
72    dont_close: NotRequired[bool]

38class GrowthKwargs(BaseKwargs):
39    """Keyword arguments for the growth_plot function."""
40
41    # --- common options
42    ax: NotRequired[Axes | None]
43    plot_from: NotRequired[int | Period]
44    label_series: NotRequired[bool]
45    max_ticks: NotRequired[int]
46    # --- options passed to the line plot
47    line_width: NotRequired[float | int]
48    line_color: NotRequired[str]
49    line_style: NotRequired[str]
50    annotate_line: NotRequired[bool]
51    line_rounding: NotRequired[bool | int]
52    line_fontsize: NotRequired[str | int | float]
53    line_fontname: NotRequired[str]
54    line_anno_color: NotRequired[str]
55    # --- options passed to the bar plot
56    annotate_bars: NotRequired[bool]
57    bar_fontsize: NotRequired[str | int | float]
58    bar_fontname: NotRequired[str]
59    bar_rounding: NotRequired[int]
60    bar_width: NotRequired[float]
61    bar_color: NotRequired[str]
62    bar_anno_color: NotRequired[str]
63    bar_rotation: NotRequired[int | float]

28class LineKwargs(BaseKwargs):
29    """Keyword arguments for the line_plot function."""
30
31    # --- options for the entire line plot
32    ax: NotRequired[Axes | None]
33    style: NotRequired[str | Sequence[str]]
34    width: NotRequired[float | int | Sequence[float | int]]
35    color: NotRequired[str | Sequence[str]]
36    alpha: NotRequired[float | Sequence[float]]
37    drawstyle: NotRequired[str | Sequence[str] | None]
38    marker: NotRequired[str | Sequence[str] | None]
39    markersize: NotRequired[float | Sequence[float] | int | None]
40    zorder: NotRequired[int | float | Sequence[int | float]]
41    dropna: NotRequired[bool | Sequence[bool]]
42    annotate: NotRequired[bool | Sequence[bool]]
43    rounding: NotRequired[Sequence[int | bool] | int | bool | None]
44    fontsize: NotRequired[Sequence[str | int | float] | str | int | float]
45    fontname: NotRequired[str | Sequence[str]]
46    rotation: NotRequired[Sequence[int | float] | int | float]
47    annotate_color: NotRequired[str | Sequence[str] | bool | Sequence[bool] | None]
48    plot_from: NotRequired[int | Period | None]
49    label_series: NotRequired[bool | Sequence[bool] | None]
50    max_ticks: NotRequired[int]

30class PostcovidKwargs(LineKwargs):
31    """Keyword arguments for the post-COVID plot."""
32
33    start_r: NotRequired[Period]  # start of regression period
34    end_r: NotRequired[Period]  # end of regression period

32class RunKwargs(LineKwargs):
33    """Keyword arguments for the run_plot function."""
34
35    threshold: NotRequired[float]
36    direction: NotRequired[str]
37    highlight_color: NotRequired[str | Sequence[str]]
38    highlight_label: NotRequired[str | Sequence[str]]

66class SeriesGrowthKwargs(GrowthKwargs):
67    """Keyword arguments for the series_growth_plot function."""
68
69    ylabel: NotRequired[str | None]

41class SummaryKwargs(BaseKwargs):
42    """Keyword arguments for the summary_plot function."""
43
44    ax: NotRequired[Axes | None]
45    verbose: NotRequired[bool]
46    middle: NotRequired[float]
47    plot_type: NotRequired[str]
48    plot_from: NotRequired[int | Period]
49    legend: NotRequired[bool | dict[str, Any] | None]
50    xlabel: NotRequired[str | None]

158def abbreviate_state(state: str) -> str:
159    """Abbreviate long-form state names.
160
161    Args:
162        state: str - the long-form state name.
163
164    Return the abbreviation for a state name.
165
166    """
167    return _state_names_multi.get(state.lower(), state)

215def bar_plot(data: DataT, **kwargs: Unpack[BarKwargs]) -> Axes:
216    """Create a bar plot from the given data.
217
218    Each column in the DataFrame will be stacked on top of each other,
219    with positive values above zero and negative values below zero.
220
221    Args:
222        data: Series | DataFrame - The data to plot. Can be a DataFrame or a Series.
223        **kwargs: BarKwargs - Additional keyword arguments for customization.
224        (see BarKwargs for details)
225
226    Note: This function does not assume all data is timeseries with a PeriodIndex.
227
228    Returns:
229        axes: Axes - The axes for the plot.
230
231    """
232    # --- check the kwargs
233    report_kwargs(caller=ME, **kwargs)
234    validate_kwargs(schema=BarKwargs, caller=ME, **kwargs)
235
236    # --- get the data
237    # no call to check_clean_timeseries here, as bar plots are not
238    # necessarily timeseries data. If the data is a Series, it will be
239    # converted to a DataFrame with a single column.
240    df = DataFrame(data)  # really we are only plotting DataFrames
241    df, kwargs_d = constrain_data(df, **kwargs)
242    item_count = len(df.columns)
243
244    # --- deal with string indices
245    saved_strings = map_stringindex(df)
246    if saved_strings is not None:
247        df = saved_strings[0]
248
249    # --- deal with complete PeriodIndex indices
250    saved_pi = map_periodindex(df)
251    if saved_pi is not None:
252        df = saved_pi[0]  # extract the reindexed DataFrame from the PeriodIndex
253
254    # --- set up the default arguments
255    chart_defaults: dict[str, bool | int] = {
256        "stacked": False,
257        "max_ticks": DEFAULT_MAX_TICKS,
258        "label_series": item_count > 1,
259        "label_rotation": 0,
260    }
261    chart_args = {k: kwargs_d.get(k, v) for k, v in chart_defaults.items()}
262
263    bar_defaults = {
264        "color": get_color_list(item_count),
265        "width": get_setting("bar_width"),
266        "label_series": item_count > 1,
267        "zorder": None,
268    }
269    above = kwargs_d.get("above", False)
270    anno_args: AnnoKwargs = {
271        "annotate": kwargs_d.get("annotate", False),
272        "fontsize": kwargs_d.get("fontsize", "small"),
273        "fontname": kwargs_d.get("fontname", "Helvetica"),
274        "rotation": kwargs_d.get("rotation", 0),
275        "rounding": kwargs_d.get("rounding", True),
276        "color": kwargs_d.get("annotate_color", "black" if above else "white"),
277        "above": above,
278    }
279    bar_args, remaining_kwargs = apply_defaults(item_count, bar_defaults, kwargs_d)
280
281    # --- plot the data
282    axes, remaining_kwargs = get_axes(**dict(remaining_kwargs))
283    if chart_args["stacked"]:
284        stacked(axes, df, anno_args, **bar_args)
285    else:
286        grouped(axes, df, anno_args, **bar_args)
287
288    # --- handle index labels and rotation
289    if saved_strings is not None:
290        axes.set_xticks(range(len(saved_strings[1])))
291        axes.set_xticklabels(saved_strings[1])
292    elif saved_pi is not None:
293        set_labels(axes, saved_pi[1], chart_args["max_ticks"])
294    plt.xticks(rotation=chart_args["label_rotation"])
295
296    return axes

138def bar_plot_finalise(
139    data: DataT,
140    **kwargs: Unpack[BPFKwargs],
141) -> None:
142    """Call bar_plot() and finalise_plot().
143
144    Args:
145        data: The data to be plotted.
146        kwargs: Combined bar plot and finalise plot keyword arguments.
147
148    """
149    validate_kwargs(schema=BPFKwargs, caller="bar_plot_finalise", **kwargs)
150    kwargs = impose_legend(kwargs=kwargs, data=data)
151    plot_then_finalise(
152        data,
153        function=bar_plot,
154        **kwargs,
155    )

 35def fill_between_plot(data: DataFrame, **kwargs: Unpack[FillBetweenKwargs]) -> Axes:
 36    """Plot a filled region between lower and upper bounds.
 37
 38    Args:
 39        data: DataFrame - A two-column DataFrame with PeriodIndex.
 40              The first column is the lower bound, the second is the upper bound.
 41        kwargs: FillBetweenKwargs - keyword arguments for the plot.
 42
 43    Returns:
 44        Axes - matplotlib Axes object.
 45
 46    Raises:
 47        TypeError: If data is not a DataFrame.
 48        ValueError: If data does not have exactly two columns.
 49
 50    """
 51    # --- validate inputs
 52    report_kwargs(caller=ME, **kwargs)
 53    validate_kwargs(schema=FillBetweenKwargs, caller=ME, **kwargs)
 54
 55    if not isinstance(data, DataFrame):
 56        raise TypeError(f"data must be a DataFrame for {ME}()")
 57
 58    if len(data.columns) != REQUIRED_COLUMNS:
 59        raise ValueError(f"data must have exactly two columns for {ME}(), got {len(data.columns)}")
 60
 61    # --- check and constrain data
 62    data = check_clean_timeseries(data, ME)
 63    data, kwargs_d = constrain_data(data, **kwargs)
 64
 65    # --- handle PeriodIndex conversion
 66    saved_pi = map_periodindex(data)
 67    if saved_pi is not None:
 68        data = saved_pi[0]
 69
 70    # --- get axes
 71    axes, kwargs_d = get_axes(**kwargs_d)
 72
 73    if data.empty or data.isna().all().all():
 74        print(f"Warning: No data to plot in {ME}().")
 75        return axes
 76
 77    # --- extract bounds
 78    lower = data.iloc[:, 0]
 79    upper = data.iloc[:, 1]
 80
 81    # --- extract plot arguments
 82    color = kwargs_d.get("color", DEFAULT_COLOR)
 83    alpha = kwargs_d.get("alpha", DEFAULT_ALPHA)
 84    label = kwargs_d.get("label", None)
 85    linewidth = kwargs_d.get("linewidth", 0)
 86    edgecolor = kwargs_d.get("edgecolor", None)
 87    zorder = kwargs_d.get("zorder", None)
 88
 89    # --- plot
 90    axes.fill_between(
 91        data.index,
 92        lower,
 93        upper,
 94        color=color,
 95        alpha=alpha,
 96        label=label,
 97        linewidth=linewidth,
 98        edgecolor=edgecolor,
 99        zorder=zorder,
100    )
101
102    # --- set axis labels
103    if saved_pi is not None:
104        set_labels(axes, saved_pi[1], kwargs_d.get("max_ticks", get_setting("max_ticks")))
105
106    return axes

158def fill_between_plot_finalise(
159    data: DataFrame,
160    **kwargs: Unpack[FBPFKwargs],
161) -> None:
162    """Call fill_between_plot() and finalise_plot().
163
164    Args:
165        data: DataFrame with two columns (lower bound, upper bound).
166        kwargs: Combined fill_between plot and finalise plot keyword arguments.
167
168    """
169    validate_kwargs(schema=FBPFKwargs, caller="fill_between_plot_finalise", **kwargs)
170    kwargs = impose_legend(kwargs=kwargs, data=data)
171    plot_then_finalise(
172        data,
173        function=fill_between_plot,
174        **kwargs,
175    )

111def calc_growth(series: Series) -> DataFrame:
112    """Calculate annual and periodic growth for a pandas Series.
113
114    Args:
115        series: Series - a pandas series with a date-like PeriodIndex.
116
117    Returns:
118        DataFrame: A two column DataFrame with annual and periodic growth rates.
119
120    Raises:
121        TypeError if the series is not a pandas Series.
122        TypeError if the series index is not a PeriodIndex.
123        ValueError if the series is empty.
124        ValueError if the series index does not have a frequency of Q, M, or D.
125        ValueError if the series index has duplicates.
126
127    """
128    # --- sanity checks
129    if not isinstance(series, Series):
130        raise TypeError("The series argument must be a pandas Series")
131    if not isinstance(series.index, PeriodIndex):
132        raise TypeError("The series index must be a pandas PeriodIndex")
133    if series.empty:
134        raise ValueError("The series argument must not be empty")
135    freq = series.index.freqstr
136    if not freq or freq[0] not in FREQUENCY_TO_PERIODS:
137        raise ValueError("The series index must have a frequency of Q, M, or D")
138    if series.index.has_duplicates:
139        raise ValueError("The series index must not have duplicate values")
140
141    # --- ensure the index is complete and the date is sorted
142    complete = period_range(start=series.index.min(), end=series.index.max())
143    series = series.reindex(complete, fill_value=nan)
144    series = series.sort_index(ascending=True)
145
146    # --- calculate annual and periodic growth
147    freq = PeriodIndex(series.index).freqstr
148    if not freq or freq[0] not in FREQUENCY_TO_PERIODS:
149        raise ValueError("The series index must have a frequency of Q, M, or D")
150
151    freq_key = freq[0]
152    ppy = FREQUENCY_TO_PERIODS[freq_key]
153    annual = series.pct_change(periods=ppy) * 100
154    periodic = series.pct_change(periods=1) * 100
155    periodic_name = FREQUENCY_TO_NAME[freq_key] + " Growth"
156    return DataFrame(
157        {
158            "Annual Growth": annual,
159            periodic_name: periodic,
160        },
161    )

146def clear_chart_dir() -> None:
147    """Remove all graph-image files from the global chart_dir."""
148    chart_dir = get_setting("chart_dir")
149    Path(chart_dir).mkdir(parents=True, exist_ok=True)
150    for ext in IMAGE_EXTENSIONS:
151        for fs_object in Path(chart_dir).glob(f"*.{ext}"):
152            if fs_object.is_file():
153                fs_object.unlink()

103def colorise_list(party_list: Iterable[str]) -> list[str]:
104    """Return a list of party/state colors for a party_list."""
105    return [get_color(x) for x in party_list]

108def contrast(orig_color: str) -> str:
109    """Provide a contrasting color to any party color."""
110    new_color = DEFAULT_CONTRAST_COLOR
111    match orig_color:
112        case "royalblue":
113            new_color = "indianred"
114        case "indianred":
115            new_color = "royalblue"
116
117        case "darkorange":
118            new_color = "mediumblue"
119        case "mediumblue":
120            new_color = "darkorange"
121
122        case "seagreen":
123            new_color = "darkblue"
124
125        case color if color == DEFAULT_UNKNOWN_COLOR:
126            new_color = "hotpink"
127
128    return new_color

343def finalise_plot(axes: Axes, **kwargs: Unpack[FinaliseKwargs]) -> None:
344    """Finalise and save plots to the file system.
345
346    The filename for the saved plot is constructed from the global
347    chart_dir, the plot's title, any specified tag text, and the
348    file_type for the plot.
349
350    Args:
351        axes: Axes - matplotlib axes object - required
352        kwargs: FinaliseKwargs
353
354    """
355    # --- check the kwargs
356    report_kwargs(caller=ME, **kwargs)
357    validate_kwargs(schema=FinaliseKwargs, caller=ME, **kwargs)
358
359    # --- sanity checks
360    if len(axes.get_children()) < 1:
361        print(f"Warning: {ME}() called with an empty axes, which was ignored.")
362        return
363
364    # --- remember axis-limits should we need to restore thems
365    xlim, ylim = axes.get_xlim(), axes.get_ylim()
366
367    # margins
368    axes.margins(DEFAULT_MARGIN)
369    axes.autoscale(tight=False)  # This is problematic ...
370
371    apply_kwargs(axes, **kwargs)
372
373    # tight layout and save the figure
374    fig = axes.figure
375    if suptitle := kwargs.get("suptitle"):
376        fig.suptitle(suptitle)
377    if kwargs.get("preserve_lims"):
378        # restore the original limits of the axes
379        axes.set_xlim(xlim)
380        axes.set_ylim(ylim)
381    if not isinstance(fig, SubFigure):
382        fig.tight_layout(pad=TIGHT_LAYOUT_PAD)
383    apply_late_kwargs(axes, **kwargs)
384    legend = axes.get_legend()
385    if legend and kwargs.get("remove_legend", False):
386        legend.remove()
387    if not isinstance(fig, SubFigure):
388        save_to_file(fig, **kwargs)
389
390    # show the plot in Jupyter Lab
391    if kwargs.get("show"):
392        plt.show()
393
394    # And close
395    if not kwargs.get("dont_close", False):
396        plt.close()

 45def get_color(s: str) -> str:
 46    """Return a matplotlib color for a party label or an Australian state/territory.
 47
 48    Args:
 49        s: str - the party label or Australian state/territory name.
 50
 51    Returns a color string that can be used in matplotlib plots.
 52
 53    """
 54    # Flattened color map for better readability
 55    color_map: dict[str, str] = {
 56        # --- Australian states and territories
 57        "wa": "gold",
 58        "western australia": "gold",
 59        "sa": "red",
 60        "south australia": "red",
 61        "nt": "#CC7722",  # ochre
 62        "northern territory": "#CC7722",
 63        "nsw": "deepskyblue",
 64        "new south wales": "deepskyblue",
 65        "act": "blue",
 66        "australian capital territory": "blue",
 67        "vic": "navy",
 68        "victoria": "navy",
 69        "tas": "seagreen",  # bottle green #006A4E?
 70        "tasmania": "seagreen",
 71        "qld": "#c32148",  # a lighter maroon
 72        "queensland": "#c32148",
 73        "australia": "grey",
 74        "aus": "grey",
 75        # --- political parties
 76        "dissatisfied": "darkorange",  # must be before satisfied
 77        "satisfied": "mediumblue",
 78        "lnp": "royalblue",
 79        "l/np": "royalblue",
 80        "liberal": "royalblue",
 81        "liberals": "royalblue",
 82        "coalition": "royalblue",
 83        "dutton": "royalblue",
 84        "ley": "royalblue",
 85        "liberal and/or nationals": "royalblue",
 86        "nat": "forestgreen",
 87        "nats": "forestgreen",
 88        "national": "forestgreen",
 89        "nationals": "forestgreen",
 90        "alp": "#dd0000",
 91        "labor": "#dd0000",
 92        "albanese": "#dd0000",
 93        "grn": "limegreen",
 94        "green": "limegreen",
 95        "greens": "limegreen",
 96        "other": "darkorange",
 97        "oth": "darkorange",
 98    }
 99
100    return color_map.get(s.lower(), DEFAULT_UNKNOWN_COLOR)

21def get_party_palette(party_text: str) -> str:
22    """Return a matplotlib color-map name based on party_text.
23
24    Works for Australian major political parties.
25
26    Args:
27        party_text: str - the party label or name.
28
29    """
30    # Note: light to dark colormaps work best for sequential data visualization
31    match party_text.lower():
32        case "alp" | "labor":
33            return "Reds"
34        case "l/np" | "coalition":
35            return "Blues"
36        case "grn" | "green" | "greens":
37            return "Greens"
38        case "oth" | "other":
39            return "YlOrBr"
40        case "onp" | "one nation":
41            return "YlGnBu"
42    return DEFAULT_PARTY_PALETTE

102def get_setting(setting: str) -> Any:
103    """Get a setting from the global settings.
104
105    Args:
106        setting: str - name of the setting to get.
107
108    Raises:
109        KeyError: if the setting is not found
110
111    Returns:
112        value: Any - the value of the setting
113
114    """
115    if setting not in get_fields():
116        raise KeyError(f"Setting '{setting}' not found in mgplot_defaults.")
117    return getattr(mgplot_defaults, setting)

164def growth_plot(
165    data: DataT,
166    **kwargs: Unpack[GrowthKwargs],
167) -> Axes:
168    """Plot annual growth and periodic growth on the same axes.
169
170    Args:
171        data: A pandas DataFrame with two columns:
172        kwargs: GrowthKwargs
173
174    Returns:
175        axes: The matplotlib Axes object.
176
177    Raises:
178        TypeError if the data is not a 2-column DataFrame.
179        TypeError if the annual index is not a PeriodIndex.
180        ValueError if the annual and periodic series do not have the same index.
181
182    """
183    # --- check the kwargs
184    me = "growth_plot"
185    report_kwargs(caller=me, **kwargs)
186    validate_kwargs(GrowthKwargs, caller=me, **kwargs)
187
188    # --- data checks
189    data = check_clean_timeseries(data, me)
190    if len(data.columns) != TWO_COLUMNS:
191        raise TypeError("The data argument must be a pandas DataFrame with two columns")
192    data, kwargsd = constrain_data(data, **kwargs)
193
194    # --- get the series of interest ...
195    annual = data[data.columns[0]]
196    periodic = data[data.columns[1]]
197
198    # --- series names
199    annual.name = "Annual Growth"
200    freq = PeriodIndex(periodic.index).freqstr
201    if freq and freq[0] in FREQUENCY_TO_NAME:
202        periodic.name = FREQUENCY_TO_NAME[freq[0]] + " Growth"
203    else:
204        periodic.name = "Periodic Growth"
205
206    # --- convert PeriodIndex periodic growth data to integer indexed data.
207    saved_pi = map_periodindex(periodic)
208    if saved_pi is not None:
209        periodic = saved_pi[0]  # extract the reindexed DataFrame
210
211    # --- simple bar chart for the periodic growth
212    if "bar_anno_color" not in kwargsd or kwargsd["bar_anno_color"] is None:
213        kwargsd["bar_anno_color"] = "black" if kwargsd.get("above", False) else "white"
214    selected = package_kwargs(to_bar_plot, **kwargsd)
215    axes = bar_plot(periodic, **selected)
216
217    # --- and now the annual growth as a line
218    selected = package_kwargs(to_line_plot, **kwargsd)
219    line_plot(annual, ax=axes, **selected)
220
221    # --- fix the x-axis labels
222    if saved_pi is not None:
223        set_labels(axes, saved_pi[1], kwargsd.get("max_ticks", 10))
224
225    # --- and done ...
226    return axes

178def growth_plot_finalise(data: DataT, **kwargs: Unpack[GrowthPFKwargs]) -> None:
179    """Call growth_plot() and finalise_plot().
180
181    Args:
182        data: The growth data to be plotted.
183        kwargs: Combined growth plot and finalise plot keyword arguments.
184
185    Note:
186        Use this when you are providing the raw growth data. Don't forget to
187        set the ylabel in kwargs.
188
189    """
190    validate_kwargs(schema=GrowthPFKwargs, caller="growth_plot_finalise", **kwargs)
191    kwargs = impose_legend(kwargs=kwargs, force=True)
192    plot_then_finalise(data=data, function=growth_plot, **kwargs)

149def line_plot(data: DataT, **kwargs: Unpack[LineKwargs]) -> Axes:
150    """Build a single or multi-line plot.
151
152    Args:
153        data: DataFrame | Series - data to plot
154        kwargs: LineKwargs - keyword arguments for the line plot
155
156    Returns:
157    - axes: Axes - the axes object for the plot
158
159    """
160    # --- check the kwargs
161    report_kwargs(caller=ME, **kwargs)
162    validate_kwargs(schema=LineKwargs, caller=ME, **kwargs)
163
164    # --- check the data
165    data = check_clean_timeseries(data, ME)
166    df = DataFrame(data)  # we are only plotting DataFrames
167    df, kwargs_d = constrain_data(df, **kwargs)
168
169    # --- convert PeriodIndex to Integer Index
170    saved_pi = map_periodindex(df)
171    if saved_pi is not None:
172        df = saved_pi[0]
173
174    if isinstance(df.index, PeriodIndex):
175        print("Internal error: data is still a PeriodIndex - come back here and fix it")
176
177    # --- Let's plot
178    axes, kwargs_d = get_axes(**kwargs_d)  # get the axes to plot on
179    if df.empty or df.isna().all().all():
180        # Note: finalise plot should ignore an empty axes object
181        print(f"Warning: No data to plot in {ME}().")
182        return axes
183
184    # --- get the arguments for each line we will plot ...
185    item_count = len(df.columns)
186    num_data_points = len(df)
187    swce, kwargs_d = get_style_width_color_etc(item_count, num_data_points, **kwargs_d)
188
189    for i, column in enumerate(df.columns):
190        series = df[column]
191        series = series.dropna() if "dropna" in swce and swce["dropna"][i] else series
192        if series.empty or series.isna().all():
193            print(f"Warning: No data to plot for {column} in line_plot().")
194            continue
195
196        axes.plot(
197            # using matplotlib, as pandas can set xlabel/ylabel
198            series.index,  # x
199            series,  # y
200            ls=swce["style"][i],
201            lw=swce["width"][i],
202            color=swce["color"][i],
203            alpha=swce["alpha"][i],
204            marker=swce["marker"][i],
205            ms=swce["markersize"][i],
206            drawstyle=swce["drawstyle"][i],
207            zorder=swce["zorder"][i],
208            label=(column if "label_series" in swce and swce["label_series"][i] else f"_{column}_"),
209        )
210
211        if swce["annotate"][i] is None or not swce["annotate"][i]:
212            continue
213
214        color = swce["color"][i] if swce["annotate_color"][i] is True else swce["annotate_color"][i]
215        annotate_series(
216            series,
217            axes,
218            color=color,
219            rounding=swce["rounding"][i],
220            fontsize=swce["fontsize"][i],
221            fontname=swce["fontname"][i],
222            rotation=swce["rotation"][i],
223        )
224
225    # --- set the labels
226    if saved_pi is not None:
227        set_labels(axes, saved_pi[1], kwargs_d.get("max_ticks", get_setting("max_ticks")))
228
229    return axes

195def line_plot_finalise(
196    data: DataT,
197    **kwargs: Unpack[LPFKwargs],
198) -> None:
199    """Call line_plot() then finalise_plot().
200
201    Args:
202        data: The data to be plotted.
203        kwargs: Combined line plot and finalise plot keyword arguments.
204
205    """
206    validate_kwargs(schema=LPFKwargs, caller="line_plot_finalise", **kwargs)
207    kwargs = impose_legend(kwargs=kwargs, data=data)
208    plot_then_finalise(data, function=line_plot, **kwargs)

273def multi_column(
274    data: DataFrame,
275    function: Callable | list[Callable],
276    **kwargs: Any,
277) -> None:
278    """Create multiple plots, one for each column in a DataFrame.
279
280    Args:
281        data: DataFrame - The data to be plotted.
282        function: Callable | list[Callable] - The plotting function(s) to be used.
283        kwargs: Any - Additional keyword arguments passed to plotting functions.
284
285    Returns:
286        None
287
288    Raises:
289        TypeError: If data is not a DataFrame.
290        ValueError: If DataFrame is empty or has no columns.
291
292    Note:
293        The plot title will be kwargs["title"] plus the column name.
294
295    """
296    # --- sanity checks
297    me = "multi_column"
298    report_kwargs(caller=me, **kwargs)
299    if not isinstance(data, DataFrame):
300        raise TypeError("data must be a pandas DataFrame for multi_column()")
301    if data.empty:
302        raise ValueError("DataFrame cannot be empty")
303    if len(data.columns) == 0:
304        raise ValueError("DataFrame must have at least one column")
305
306    # --- check the function argument
307    title_stem = kwargs.get("title", "")
308    tag: Final[str] = kwargs.get("tag", "")
309    first, kwargs["function"] = first_unchain(function)
310    if not kwargs["function"]:
311        del kwargs["function"]  # remove the function key if it is empty
312
313    # --- iterate over the columns
314    for i, col in enumerate(data.columns):
315        series = data[col]  # Extract as Series, not single-column DataFrame
316        kwargs["title"] = f"{title_stem}{col}" if title_stem else str(col)
317        kwargs["tag"] = _generate_tag(tag, i)
318        first(series, **kwargs)