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

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