mgplot.seastrend_plot

Create seasonal+trend plots.

 1"""Create seasonal+trend plots."""
 2
 3from typing import Final, Unpack
 4
 5from matplotlib.axes import Axes
 6
 7from mgplot.keyword_checking import report_kwargs, validate_kwargs
 8from mgplot.line_plot import LineKwargs, line_plot
 9from mgplot.settings import DataT
10from mgplot.utilities import check_clean_timeseries, get_color_list, get_setting
11
12# --- constants
13ME: Final[str] = "seastrend_plot"
14REQUIRED_COLUMNS: Final[int] = 2
15
16
17# --- public functions
18def seastrend_plot(data: DataT, **kwargs: Unpack[LineKwargs]) -> Axes:
19    """Produce a seasonal+trend plot.
20
21    Arguments:
22        data: DataFrame - the data to plot. Must have exactly 2 columns:
23                          Seasonal data in column 0, Trend data in column 1
24        kwargs: LineKwargs - additional keyword arguments to pass to line_plot()
25
26    Returns:
27        Axes: A matplotlib Axes object containing the seasonal+trend plot
28
29    Raises:
30        ValueError: If the DataFrame does not have exactly 2 columns
31
32    """
33    # --- check the kwargs
34    report_kwargs(caller=ME, **kwargs)
35    validate_kwargs(schema=LineKwargs, caller=ME, **kwargs)
36
37    # --- check the data
38    data = check_clean_timeseries(data, ME)
39    if data.shape[1] != REQUIRED_COLUMNS:
40        raise ValueError(
41            f"{ME}() expects a DataFrame with exactly {REQUIRED_COLUMNS} columns "
42            f"(seasonal and trend), but got {data.shape[1]} columns."
43        )
44
45    # --- set defaults for seasonal+trend visualization
46    kwargs["color"] = kwargs.get("color", get_color_list(REQUIRED_COLUMNS))
47    kwargs["width"] = kwargs.get("width", [get_setting("line_normal"), get_setting("line_wide")])
48    kwargs["style"] = kwargs.get("style", ["-", "-"])
49    kwargs["annotate"] = kwargs.get("annotate", [True, False])  # annotate seasonal, not trend
50    kwargs["rounding"] = kwargs.get("rounding", True)
51    kwargs["dropna"] = kwargs.get("dropna", False)  # series breaks are common in seas-trend data
52
53    return line_plot(
54        data,
55        **kwargs,
56    )
ME: Final[str] = 'seastrend_plot'
REQUIRED_COLUMNS: Final[int] = 2
def seastrend_plot( data: ~DataT, **kwargs: Unpack[mgplot.LineKwargs]) -> matplotlib.axes._axes.Axes:
19def seastrend_plot(data: DataT, **kwargs: Unpack[LineKwargs]) -> Axes:
20    """Produce a seasonal+trend plot.
21
22    Arguments:
23        data: DataFrame - the data to plot. Must have exactly 2 columns:
24                          Seasonal data in column 0, Trend data in column 1
25        kwargs: LineKwargs - additional keyword arguments to pass to line_plot()
26
27    Returns:
28        Axes: A matplotlib Axes object containing the seasonal+trend plot
29
30    Raises:
31        ValueError: If the DataFrame does not have exactly 2 columns
32
33    """
34    # --- check the kwargs
35    report_kwargs(caller=ME, **kwargs)
36    validate_kwargs(schema=LineKwargs, caller=ME, **kwargs)
37
38    # --- check the data
39    data = check_clean_timeseries(data, ME)
40    if data.shape[1] != REQUIRED_COLUMNS:
41        raise ValueError(
42            f"{ME}() expects a DataFrame with exactly {REQUIRED_COLUMNS} columns "
43            f"(seasonal and trend), but got {data.shape[1]} columns."
44        )
45
46    # --- set defaults for seasonal+trend visualization
47    kwargs["color"] = kwargs.get("color", get_color_list(REQUIRED_COLUMNS))
48    kwargs["width"] = kwargs.get("width", [get_setting("line_normal"), get_setting("line_wide")])
49    kwargs["style"] = kwargs.get("style", ["-", "-"])
50    kwargs["annotate"] = kwargs.get("annotate", [True, False])  # annotate seasonal, not trend
51    kwargs["rounding"] = kwargs.get("rounding", True)
52    kwargs["dropna"] = kwargs.get("dropna", False)  # series breaks are common in seas-trend data
53
54    return line_plot(
55        data,
56        **kwargs,
57    )

Produce a seasonal+trend plot.

Arguments: data: DataFrame - the data to plot. Must have exactly 2 columns: Seasonal data in column 0, Trend data in column 1 kwargs: LineKwargs - additional keyword arguments to pass to line_plot()

Returns: Axes: A matplotlib Axes object containing the seasonal+trend plot

Raises: ValueError: If the DataFrame does not have exactly 2 columns