mgplot.seastrend_plot

seas_trend_plot.py This module contains a function to create seasonal+trend plots.

 1"""
 2seas_trend_plot.py
 3This module contains a function to create seasonal+trend plots.
 4"""
 5
 6# --- imports
 7from matplotlib.pyplot import Axes
 8
 9from mgplot.settings import DataT
10from mgplot.line_plot import line_plot, LINE_KW_TYPES
11from mgplot.utilities import get_color_list, get_setting, check_clean_timeseries
12from mgplot.kw_type_checking import report_kwargs, validate_kwargs
13
14
15# --- constants
16SEASTREND_KW_TYPES = LINE_KW_TYPES
17
18COLOR = "color"
19WIDTH = "width"
20STYLE = "style"
21ANNOTATE = "annotate"
22ROUNDING = "rounding"
23LEGEND = "legend"
24DROPNA = "dropna"
25
26
27# --- public functions
28def seastrend_plot(data: DataT, **kwargs) -> Axes:
29    """
30    Publish a DataFrame, where the first column is seasonally
31    adjusted data, and the second column is trend data.
32
33    Aguments:
34    - data: DataFrame - the data to plot with the first column
35      being the seasonally adjusted data, and the second column
36      being the trend data.
37    The remaining arguments are the same as those passed to
38    line_plot().
39
40    Returns:
41    - a matplotlib Axes object
42    """
43
44    # Note: we will rely on the line_plot() function to do most of the work.
45    # including constraining the data to the plot_from keyword argument.
46
47    # --- check the kwargs
48    me = "seastrend_plot"
49    report_kwargs(called_from=me, **kwargs)
50    validate_kwargs(SEASTREND_KW_TYPES, me, **kwargs)
51
52    # --- check the data
53    data = check_clean_timeseries(data, me)
54    if len(data.columns) < 2:
55        raise ValueError(
56            "seas_trend_plot() expects a DataFrame data item with at least 2 columns."
57        )
58
59    # --- defaults if not in kwargs
60    colors = kwargs.pop(COLOR, get_color_list(2))
61    widths = kwargs.pop(WIDTH, [get_setting("line_normal"), get_setting("line_wide")])
62    styles = kwargs.pop(STYLE, ["-", "-"])
63    annotations = kwargs.pop(ANNOTATE, [True, False])
64    rounding = kwargs.pop(ROUNDING, True)
65    legend = kwargs.pop(LEGEND, True)
66
67    # series breaks are common in seas-trend data
68    kwargs[DROPNA] = kwargs.pop(DROPNA, False)
69
70    return line_plot(
71        data,
72        color=colors,
73        width=widths,
74        style=styles,
75        annotate=annotations,
76        rounding=rounding,
77        legend=legend,
78        **kwargs,
79    )
SEASTREND_KW_TYPES = {'ax': (<class 'matplotlib.axes._axes.Axes'>, <class 'NoneType'>), 'style': (<class 'str'>, <class 'collections.abc.Sequence'>, (<class 'str'>,)), 'width': (<class 'float'>, <class 'int'>, <class 'collections.abc.Sequence'>, (<class 'float'>, <class 'int'>)), 'color': (<class 'str'>, <class 'collections.abc.Sequence'>, (<class 'str'>,)), 'alpha': (<class 'float'>, <class 'collections.abc.Sequence'>, (<class 'float'>,)), 'drawstyle': (<class 'str'>, <class 'collections.abc.Sequence'>, (<class 'str'>,), <class 'NoneType'>), 'marker': (<class 'str'>, <class 'collections.abc.Sequence'>, (<class 'str'>,), <class 'NoneType'>), 'markersize': (<class 'float'>, <class 'collections.abc.Sequence'>, (<class 'float'>,), <class 'int'>, <class 'NoneType'>), 'dropna': (<class 'bool'>, <class 'collections.abc.Sequence'>, (<class 'bool'>,)), 'annotate': (<class 'bool'>, <class 'collections.abc.Sequence'>, (<class 'bool'>,)), 'rounding': (<class 'collections.abc.Sequence'>, (<class 'bool'>, <class 'int'>), <class 'int'>, <class 'bool'>, <class 'NoneType'>), 'fontsize': (<class 'collections.abc.Sequence'>, (<class 'str'>, <class 'int'>), <class 'str'>, <class 'int'>, <class 'NoneType'>), 'plot_from': (<class 'int'>, <class 'pandas._libs.tslibs.period.Period'>, <class 'NoneType'>), 'legend': (<class 'dict'>, (<class 'str'>, <class 'object'>), <class 'bool'>, <class 'NoneType'>)}
COLOR = 'color'
WIDTH = 'width'
STYLE = 'style'
ANNOTATE = 'annotate'
ROUNDING = 'rounding'
LEGEND = 'legend'
DROPNA = 'dropna'
def seastrend_plot(data: ~DataT, **kwargs) -> matplotlib.axes._axes.Axes:
29def seastrend_plot(data: DataT, **kwargs) -> Axes:
30    """
31    Publish a DataFrame, where the first column is seasonally
32    adjusted data, and the second column is trend data.
33
34    Aguments:
35    - data: DataFrame - the data to plot with the first column
36      being the seasonally adjusted data, and the second column
37      being the trend data.
38    The remaining arguments are the same as those passed to
39    line_plot().
40
41    Returns:
42    - a matplotlib Axes object
43    """
44
45    # Note: we will rely on the line_plot() function to do most of the work.
46    # including constraining the data to the plot_from keyword argument.
47
48    # --- check the kwargs
49    me = "seastrend_plot"
50    report_kwargs(called_from=me, **kwargs)
51    validate_kwargs(SEASTREND_KW_TYPES, me, **kwargs)
52
53    # --- check the data
54    data = check_clean_timeseries(data, me)
55    if len(data.columns) < 2:
56        raise ValueError(
57            "seas_trend_plot() expects a DataFrame data item with at least 2 columns."
58        )
59
60    # --- defaults if not in kwargs
61    colors = kwargs.pop(COLOR, get_color_list(2))
62    widths = kwargs.pop(WIDTH, [get_setting("line_normal"), get_setting("line_wide")])
63    styles = kwargs.pop(STYLE, ["-", "-"])
64    annotations = kwargs.pop(ANNOTATE, [True, False])
65    rounding = kwargs.pop(ROUNDING, True)
66    legend = kwargs.pop(LEGEND, True)
67
68    # series breaks are common in seas-trend data
69    kwargs[DROPNA] = kwargs.pop(DROPNA, False)
70
71    return line_plot(
72        data,
73        color=colors,
74        width=widths,
75        style=styles,
76        annotate=annotations,
77        rounding=rounding,
78        legend=legend,
79        **kwargs,
80    )

Publish a DataFrame, where the first column is seasonally adjusted data, and the second column is trend data.

Aguments:

  • data: DataFrame - the data to plot with the first column being the seasonally adjusted data, and the second column being the trend data. The remaining arguments are the same as those passed to line_plot().

Returns:

  • a matplotlib Axes object