mgplot.revision_plot

 1"""Plot ABS revisions to estimates over time."""
 2
 3from typing import Unpack
 4
 5from matplotlib.axes import Axes
 6from pandas import DataFrame
 7
 8from mgplot.keyword_checking import report_kwargs, validate_kwargs
 9from mgplot.line_plot import LineKwargs, line_plot
10from mgplot.settings import DataT
11from mgplot.utilities import check_clean_timeseries
12
13# --- constants
14ME = "revision_plot"
15DEFAULT_PLOT_FROM = -15
16MIN_REVISION_COLUMNS = 2
17DEFAULT_NEAR_END = 0.0  # revision vintages bunch at the right edge; don't snap labels to the border
18
19
20# --- functions
21def revision_plot(data: DataT, **kwargs: Unpack[LineKwargs]) -> Axes:
22    """Plot the revisions to ABS data.
23
24    Args:
25        data: DataFrame - the data to plot, with a column for each data revision.
26               Must have at least 2 columns to show meaningful revision comparisons.
27        kwargs: LineKwargs - additional keyword arguments for the line_plot function.
28
29    Returns:
30        Axes: A matplotlib Axes object containing the revision plot.
31
32    Raises:
33        TypeError: If data is not a DataFrame.
34        ValueError: If DataFrame has fewer than 2 columns for revision comparison.
35
36    """
37    # --- check the kwargs and data
38    report_kwargs(caller=ME, **kwargs)
39    validate_kwargs(schema=LineKwargs, caller=ME, **kwargs)
40    data = check_clean_timeseries(data, ME)
41
42    # --- additional checks
43    if not isinstance(data, DataFrame):
44        print(f"{ME}() requires a DataFrame with columns for each revision, not a Series or any other type.")
45        raise TypeError(f"{ME}() requires a DataFrame, got {type(data).__name__}")
46
47    if data.shape[1] < MIN_REVISION_COLUMNS:
48        raise ValueError(
49            f"{ME}() requires at least {MIN_REVISION_COLUMNS} columns for revision comparison, "
50            f"but got {data.shape[1]} columns"
51        )
52
53    # --- set defaults for revision visualization
54    kwargs["plot_from"] = kwargs.get("plot_from", DEFAULT_PLOT_FROM)
55    kwargs["annotate"] = kwargs.get("annotate", True)
56    kwargs["annotate_color"] = kwargs.get("annotate_color", "black")
57    kwargs["rounding"] = kwargs.get("rounding", 3)
58    kwargs["near_end"] = kwargs.get("near_end", DEFAULT_NEAR_END)
59
60    # --- plot
61    return line_plot(data, **kwargs)