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