mgplot.revision_plot

Plot ABS revisions to estimates over time.

 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
17
18
19# --- functions
20def revision_plot(data: DataT, **kwargs: Unpack[LineKwargs]) -> Axes:
21    """Plot the revisions to ABS data.
22
23    Args:
24        data: DataFrame - the data to plot, with a column for each data revision.
25               Must have at least 2 columns to show meaningful revision comparisons.
26        kwargs: LineKwargs - additional keyword arguments for the line_plot function.
27
28    Returns:
29        Axes: A matplotlib Axes object containing the revision plot.
30
31    Raises:
32        TypeError: If data is not a DataFrame.
33        ValueError: If DataFrame has fewer than 2 columns for revision comparison.
34
35    """
36    # --- check the kwargs and data
37    report_kwargs(caller=ME, **kwargs)
38    validate_kwargs(schema=LineKwargs, caller=ME, **kwargs)
39    data = check_clean_timeseries(data, ME)
40
41    # --- additional checks
42    if not isinstance(data, DataFrame):
43        print(f"{ME}() requires a DataFrame with columns for each revision, not a Series or any other type.")
44        raise TypeError(f"{ME}() requires a DataFrame, got {type(data).__name__}")
45
46    if data.shape[1] < MIN_REVISION_COLUMNS:
47        raise ValueError(
48            f"{ME}() requires at least {MIN_REVISION_COLUMNS} columns for revision comparison, "
49            f"but got {data.shape[1]} columns"
50        )
51
52    # --- set defaults for revision visualization
53    kwargs["plot_from"] = kwargs.get("plot_from", DEFAULT_PLOT_FROM)
54    kwargs["annotate"] = kwargs.get("annotate", True)
55    kwargs["annotate_color"] = kwargs.get("annotate_color", "black")
56    kwargs["rounding"] = kwargs.get("rounding", 3)
57
58    # --- plot
59    return line_plot(data, **kwargs)
ME = 'revision_plot'
DEFAULT_PLOT_FROM = -15
MIN_REVISION_COLUMNS = 2
def revision_plot( data: ~DataT, **kwargs: Unpack[mgplot.LineKwargs]) -> matplotlib.axes._axes.Axes:
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
59    # --- plot
60    return line_plot(data, **kwargs)

Plot the revisions to ABS data.

Args: data: DataFrame - the data to plot, with a column for each data revision. Must have at least 2 columns to show meaningful revision comparisons. kwargs: LineKwargs - additional keyword arguments for the line_plot function.

Returns: Axes: A matplotlib Axes object containing the revision plot.

Raises: TypeError: If data is not a DataFrame. ValueError: If DataFrame has fewer than 2 columns for revision comparison.