mgplot 0.1.1__tar.gz → 0.1.3__tar.gz

{mgplot-0.1.1/src/mgplot.egg-info → mgplot-0.1.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mgplot
-Version: 0.1.1
-Summary: mgplot is a frontend for matplotlib
+Version: 0.1.3
+Summary: mgplot is a time-series/PeriodIndex frontend for matplotlib
 Project-URL: Homepage, https://github.com/bpalmer4/mgplot
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -18,6 +18,7 @@ Requires-Dist: pdoc
 Requires-Dist: pylint
 Requires-Dist: ruff
 Requires-Dist: pandas-stubs
+Requires-Dist: numpy-typing
 Requires-Dist: types-tabulate
 Provides-Extra: build
 Requires-Dist: setuptools; extra == "build"
@@ -64,7 +65,7 @@ The remaining arrguments are passed as keyword arguments:
 - summary_plot() -- plots the latest data in a summary-format against
   the range of previous data. 
 
-Once a plot has been generated and am Axes object is available. The
+Once a plot has been generated and an Axes object is available. The
 plot can be finalised or published, with appropriate titles and
 axis labels using
 - finalise_plot()

{mgplot-0.1.1 → mgplot-0.1.3}/README.md

@@ -38,7 +38,7 @@ The remaining arrguments are passed as keyword arguments:
 - summary_plot() -- plots the latest data in a summary-format against
   the range of previous data. 
 
-Once a plot has been generated and am Axes object is available. The
+Once a plot has been generated and an Axes object is available. The
 plot can be finalised or published, with appropriate titles and
 axis labels using
 - finalise_plot()
@@ -69,4 +69,4 @@ function:
 
 For more details, see the documentation folder.
 
----
+---

{mgplot-0.1.1 → mgplot-0.1.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "mgplot"
-version = "0.1.1"
-description = "mgplot is a frontend for matplotlib"
+version = "0.1.3"
+description = "mgplot is a time-series/PeriodIndex frontend for matplotlib"
 readme = "README.md"
 requires-python = ">=3.11"
 
@@ -25,6 +25,7 @@ dependencies = [
 
     # - typing
     "pandas-stubs",
+    "numpy-typing",
     "types-tabulate",
 ]
 

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/__init__.py

@@ -8,7 +8,7 @@ with timeseries data that is indexed with a PeriodIndex.
 
 # --- version and author
 # NOTE: update version number here (below) and in pyproject.toml
-__version__ = "0.1.0"
+__version__ = "0.1.3"
 __author__ = "Bryan Palmer"
 
 
@@ -27,7 +27,8 @@ from mgplot.growth_plot import (
     calc_growth,
     raw_growth_plot,
     series_growth_plot,
-    GROWTH_KW_TYPES,
+    SERIES_GROWTH_KW_TYPES,
+    RAW_GROWTH_KW_TYPES,
 )
 from mgplot.multi_plot import (
     multi_start,
@@ -62,13 +63,7 @@ from mgplot.finalisers import (
 )
 
 
-# --- version and author
-__version__ = "0.0.1"
-__author__ = "Bryan Palmer"
-
-
 # --- public API
-SERIES_GROWTH_KW_TYPES = RAW_GROWTH_KW_TYPES = GROWTH_KW_TYPES
 __all__ = (
     "__version__",
     "__author__",
@@ -129,7 +124,6 @@ __all__ = (
     "REVISION_KW_TYPES",
     "RUN_KW_TYPES",
     "SUMMARY_KW_TYPES",
-    "GROWTH_KW_TYPES",
     "SERIES_GROWTH_KW_TYPES",
     "RAW_GROWTH_KW_TYPES",
     # --- The rest are internal use only

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/bar_plot.py

@@ -16,7 +16,12 @@ from matplotlib.pyplot import Axes
 
 from mgplot.settings import DataT, get_setting
 from mgplot.utilities import apply_defaults, get_color_list, get_axes, constrain_data
-from mgplot.kw_type_checking import validate_kwargs, validate_expected, ExpectedTypeDict
+from mgplot.kw_type_checking import (
+    ExpectedTypeDict,
+    validate_expected,
+    report_kwargs,
+    validate_kwargs,
+)
 from mgplot.date_utils import set_labels
 
 
@@ -61,11 +66,15 @@ def bar_plot(
     - axes: Axes - The axes for the plot.
     """
 
-    # --- validate the kwargs
-    validate_kwargs(BAR_KW_TYPES, "bar_plot", **kwargs)
-    # note data may not be time-series or have a period index.
+    # --- check the kwargs
+    me = "bar_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(BAR_KW_TYPES, me, **kwargs)
 
     # --- get the data
+    # no call to check_clean_timeseries here, as bar plots are not
+    # necessarily timeseries data. If the data is a Series, it will be
+    # converted to a DataFrame with a single column.
     df = DataFrame(data)  # really we are only plotting DataFrames
     df, kwargs = constrain_data(df, **kwargs)
     item_count = len(df.columns)

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/finalise_plot.py

@@ -5,7 +5,7 @@ file system. It is used to publish plots.
 """
 
 # --- imports
-from typing import Final
+from typing import Final, Any
 import re
 import matplotlib as mpl
 import matplotlib.pyplot as plt
@@ -121,6 +121,22 @@ _internal_consistency_kwargs()
 # - private utility functions for finalise_plot()
 
 
+def make_legend(axes: Axes, legend: None | bool | dict[str, Any]) -> None:
+    """Create a legend for the plot."""
+
+    if legend is None or legend is False:
+        return
+
+    if legend is True:  # use the global default settings
+        legend = get_setting("legend")
+
+    if isinstance(legend, dict):
+        axes.legend(**legend)
+        return
+
+    print(f"Warning: expected dict argument for legend, but got {type(legend)}.")
+
+
 def _apply_value_kwargs(axes: Axes, settings: tuple, **kwargs) -> None:
     """Set matplotlib elements by name using Axes.set()."""
 
@@ -128,6 +144,9 @@ def _apply_value_kwargs(axes: Axes, settings: tuple, **kwargs) -> None:
         value = kwargs.get(setting, None)
         if value is None and setting not in _value_must_kwargs:
             continue
+        if setting == "ylabel" and value is None and axes.get_ylabel():
+            # already set - probably in series_growth_plot() - so skip
+            continue
         axes.set(**{setting: value})
 
 
@@ -141,6 +160,11 @@ def _apply_splat_kwargs(axes: Axes, settings: tuple, **kwargs) -> None:
     for method_name in settings:
         if method_name in kwargs:
 
+            if method_name == "legend":
+                # special case for legend
+                make_legend(axes, kwargs[method_name])
+                continue
+
             if kwargs[method_name] is None or kwargs[method_name] is False:
                 continue
 
@@ -153,7 +177,7 @@ def _apply_splat_kwargs(axes: Axes, settings: tuple, **kwargs) -> None:
                 method(**kwargs[method_name])
             else:
                 print(
-                    f"Warning expected dict argument: {method_name} but got "
+                    f"Warning expected dict argument for {method_name} but got "
                     + f"{type(kwargs[method_name])}."
                 )
 
@@ -297,9 +321,15 @@ def finalise_plot(axes: Axes, **kwargs) -> None:
         - None
     """
 
+    # --- check the kwargs
+    me = "finalise_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(FINALISE_KW_TYPES, me, **kwargs)
+
     # --- sanity checks
-    report_kwargs(called_from="finalise_plot", **kwargs)
-    validate_kwargs(FINALISE_KW_TYPES, "finalise_plot", **kwargs)
+    if len(axes.get_children()) < 1:
+        print("Warning: finalise_plot() called with empty axes, which was ignored.")
+        return
 
     # --- remember should we need to restore the axes limits
     xlim, ylim = axes.get_xlim(), axes.get_ylim()

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/finalisers.py

@@ -149,8 +149,6 @@ def series_growth_plot_finalise(data: DataT, **kwargs) -> None:
     the growth series.
     """
 
-    kwargs["ylabel"] = kwargs.get("ylabel", "Per cent Growth")
-    kwargs["xlabel"] = kwargs.get("xlabel", None)
     plot_then_finalise(
         data=data,
         function=series_growth_plot,
@@ -165,8 +163,6 @@ def raw_growth_plot_finalise(data: DataT, **kwargs) -> None:
     set the ylabel in kwargs.
     """
 
-    kwargs["ylabel"] = kwargs.get("ylabel", "Growth Units unspecified")
-    kwargs["xlabel"] = kwargs.get("xlabel", None)
     plot_then_finalise(
         data=data,
         function=raw_growth_plot,
@@ -192,46 +188,24 @@ def summary_plot_finalise(
           defaults to "zscores".
     """
 
-    # --- sanity checks
-    if not isinstance(data.index, PeriodIndex):
-        raise ValueError("data must have a PeriodIndex")
-
     # --- standard arguments
-    kwargs["legend"] = kwargs.get(
-        "legend",
-        {
-            # put the legend below the x-axis label
-            "loc": "upper center",
-            "fontsize": "xx-small",
-            "bbox_to_anchor": (0.5, -0.125),
-            "ncol": 4,
-        },
-    )
-    start = kwargs.get("plot_from", None)
+    kwargs["title"] = kwargs.get("title", f"Summary at {data.index[-1]}")
+    kwargs["preserve_lims"] = kwargs.get(
+        "preserve_lims", True
+    )  # preserve the x-axis limits
+
+    start: None | int | Period = kwargs.get("plot_from", None)
+    if start is None:
+        start = data.index[0]
+    if isinstance(start, int):
+        start = data.index[start]
+    kwargs["plot_from"] = start
 
     for plot_type in (ZSCORES, ZSCALED):
         # some sorting of kwargs for plot production
         kwargs["plot_type"] = plot_type
-        kwargs["title"] = kwargs.get("title", f"Summary at {data.index[-1]}")
-        kwargs["pre_tag"] = plot_type  # necessary because the title is same
-        kwargs["preserve_lims"] = kwargs.get(
-            "preserve_lims", True
-        )  # preserve the x-axis limits
-
-        # get the start date for the plot
-        set_default = start is None
-        if isinstance(start, int):
-            start = data.index[start]
-        if set_default:
-            freq = data.index.freqstr[0]
-            if freq not in ("D", "M", "Q"):
-                raise ValueError(f"Unknown frequency {freq} for data index")
-            start = Period("1995-01-01", freq=data.index.freqstr)
-        kwargs["plot_from"] = start
-
-        if plot_type not in (ZSCORES, ZSCALED):
-            print(f"Unknown plot type {plot_type}, defaulting to {ZSCORES}")
-            plot_type = ZSCORES
+        kwargs["pre_tag"] = plot_type  # necessary because the title is the same
+
         if plot_type == "zscores":
             kwargs["xlabel"] = f"Z-scores for prints since {start}"
             kwargs["x0"] = True

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/growth_plot.py

@@ -14,6 +14,7 @@ from matplotlib.pyplot import Axes
 import matplotlib.patheffects as pe
 from tabulate import tabulate
 
+from mgplot.finalise_plot import make_legend
 from mgplot.test import prepare_for_test
 from mgplot.settings import get_setting, DataT
 from mgplot.date_utils import set_labels
@@ -30,7 +31,7 @@ from mgplot.kw_type_checking import (
 ANNUAL = "annual"
 PERIODIC = "periodic"
 
-GROWTH_KW_TYPES: Final[ExpectedTypeDict] = {
+RAW_GROWTH_KW_TYPES: Final[ExpectedTypeDict] = {
     "line_width": (float, int),
     "line_color": str,
     "line_style": str,
@@ -41,9 +42,13 @@ GROWTH_KW_TYPES: Final[ExpectedTypeDict] = {
     "annotation_rounding": int,
     "plot_from": (type(None), Period, int),
     "max_ticks": int,
+    "legend": (type(None), bool, dict, (str, object)),
 }
-validate_expected(GROWTH_KW_TYPES, "growth_plot")
-# --- alieses for intuitive compatibility
+validate_expected(RAW_GROWTH_KW_TYPES, "growth_plot")
+SERIES_GROWTH_KW_TYPES: Final[ExpectedTypeDict] = {
+    "ylabel": (str, type(None)),
+} | RAW_GROWTH_KW_TYPES
+validate_expected(SERIES_GROWTH_KW_TYPES, "growth_plot")
 
 
 # --- functions
@@ -183,10 +188,13 @@ def raw_growth_plot(
     -   ValueError if the annual and periodic series do not have the same index.
     """
 
-    # --- sanity checks
-    report_kwargs(called_from="raw_growth_plot", **kwargs)
-    validate_kwargs(GROWTH_KW_TYPES, "raw_growth_plot", **kwargs)
-    data = check_clean_timeseries(data)
+    # --- check the kwargs
+    me = "raw_growth_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(RAW_GROWTH_KW_TYPES, me, **kwargs)
+
+    # --- data checks
+    data = check_clean_timeseries(data, me)
     if len(data.columns) != 2:
         raise TypeError("The data argument must be a pandas DataFrame with two columns")
 
@@ -228,7 +236,10 @@ def raw_growth_plot(
         linestyle=kwargs.get("line_style", "-"),
     )
     _annotations(annual, periodic, axes, **kwargs)
-    axes.set_ylabel("Per cent Growth")
+
+    # --- expose the legend by default
+    legend = kwargs.get("legend", True)
+    make_legend(axes, legend)
 
     # --- fix the x-axis labels
     set_labels(axes, save_index, kwargs.get("max_ticks", 10))
@@ -251,18 +262,25 @@ def series_growth_plot(
         -   takes the same kwargs as for growth_plot()
     """
 
+    # --- check the kwargs
+    me = "series_growth_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(SERIES_GROWTH_KW_TYPES, me, **kwargs)
+
     # --- sanity checks
-    report_kwargs(called_from="series_growth_plot", **kwargs)
-    data = check_clean_timeseries(data)
-    # we will validate kwargs in raw_growth_plot()
     if not isinstance(data, Series):
         raise TypeError(
             "The data argument to series_growth_plot() must be a pandas Series"
         )
 
-    # --- calculate growth and plot
+    # --- calculate growth and plot - add ylabel
+    ylabel: str | None = kwargs.pop("ylabel", None)
+    if ylabel is not None:
+        print(f"Did you intend to specify a value for the 'ylabel' in {me}()?")
+    ylabel = "Growth (%)" if ylabel is None else ylabel
     growth = calc_growth(data)
     ax = raw_growth_plot(growth, **kwargs)
+    ax.set_ylabel(ylabel)
     return ax
 
 

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/line_plot.py

@@ -10,6 +10,7 @@ import matplotlib.pyplot as plt
 from pandas import DataFrame, Period
 
 from mgplot.settings import DataT, get_setting
+from mgplot.finalise_plot import make_legend
 from mgplot.kw_type_checking import (
     report_kwargs,
     validate_kwargs,
@@ -119,25 +120,28 @@ def line_plot(data: DataT, **kwargs) -> plt.Axes:
     - axes: plt.Axes - the axes object for the plot
     """
 
-    # sanity checks
-    report_kwargs(called_from="line_plot", **kwargs)
-    data = check_clean_timeseries(data)
-    validate_kwargs(LINE_KW_TYPES, called_from="line_plot", **kwargs)
+    # --- check the kwargs
+    me = "line_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(LINE_KW_TYPES, me, **kwargs)
 
-    # the data to be plotted:
+    # --- check the data
+    data = check_clean_timeseries(data, me)
     df = DataFrame(data)  # really we are only plotting DataFrames
     df, kwargs = constrain_data(df, **kwargs)
-    if df.empty:
+
+    # --- Let's plot
+    axes, kwargs = get_axes(**kwargs)  # get the axes to plot on
+    if df.empty or df.isna().all().all():
+        # Note: finalise plot will ignore an empty axes object
         print("Warning: No data to plot.")
+        return axes
 
-    # get the arguments for each line we will plot ...
+    # --- get the arguments for each line we will plot ...
     item_count = len(df.columns)
     num_data_points = len(df)
     swce, kwargs = _get_style_width_color_etc(item_count, num_data_points, **kwargs)
 
-    # Let's plot
-    axes, kwargs = get_axes(**kwargs)  # get the axes to plot on
-
     for i, column in enumerate(df.columns):
         series = df[column]
         series = series.dropna() if DROPNA in swce and swce[DROPNA][i] else series
@@ -169,10 +173,8 @@ def line_plot(data: DataT, **kwargs) -> plt.Axes:
     # add a legend if requested
     if len(df.columns) > 1:
         kwargs[LEGEND] = kwargs.get(LEGEND, get_setting("legend"))
-    if LEGEND in kwargs and kwargs[LEGEND] is not None:
-        legend = kwargs[LEGEND]
-        if isinstance(legend, bool):
-            legend = get_setting("legend")
-        axes.legend(**legend)
+
+    if LEGEND in kwargs:
+        make_legend(axes, kwargs[LEGEND])
 
     return axes

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/multi_plot.py

@@ -45,11 +45,11 @@ from mgplot.kw_type_checking import (
     limit_kwargs,
     ExpectedTypeDict,
     report_kwargs,
+    validate_kwargs,
 )
 from mgplot.finalise_plot import finalise_plot, FINALISE_KW_TYPES
 from mgplot.settings import DataT
 from mgplot.test import prepare_for_test
-from mgplot.utilities import check_clean_timeseries
 
 from mgplot.line_plot import line_plot, LINE_KW_TYPES
 from mgplot.bar_plot import bar_plot, BAR_KW_TYPES
@@ -58,8 +58,12 @@ from mgplot.postcovid_plot import postcovid_plot, POSTCOVID_KW_TYPES
 from mgplot.revision_plot import revision_plot, REVISION_KW_TYPES
 from mgplot.run_plot import run_plot, RUN_KW_TYPES
 from mgplot.summary_plot import summary_plot, SUMMARY_KW_TYPES
-from mgplot.growth_plot import series_growth_plot, raw_growth_plot, GROWTH_KW_TYPES
-
+from mgplot.growth_plot import (
+    series_growth_plot,
+    raw_growth_plot,
+    RAW_GROWTH_KW_TYPES,
+    SERIES_GROWTH_KW_TYPES,
+)
 
 # --- constants
 EXPECTED_CALLABLES: Final[dict[Callable, ExpectedTypeDict]] = {
@@ -73,8 +77,8 @@ EXPECTED_CALLABLES: Final[dict[Callable, ExpectedTypeDict]] = {
     revision_plot: REVISION_KW_TYPES,
     run_plot: RUN_KW_TYPES,
     summary_plot: SUMMARY_KW_TYPES,
-    series_growth_plot: GROWTH_KW_TYPES,
-    raw_growth_plot: GROWTH_KW_TYPES,
+    series_growth_plot: SERIES_GROWTH_KW_TYPES,
+    raw_growth_plot: RAW_GROWTH_KW_TYPES,
 }
 
 
@@ -139,9 +143,13 @@ def plot_then_finalise(
     Returns None.
     """
 
-    # --- sanity checks
-    report_kwargs(called_from="plot_then_finalise", **kwargs)
-    data = check_clean_timeseries(data)
+    # --- checks
+    me = "plot_then_finalise"
+    report_kwargs(called_from=me, **kwargs)
+    # validate once we have established the first function
+
+    # data is not checked here, assume it is checked by the called
+    # plot function.
 
     # --- check the function argument
     first, kwargs_ = first_unchain(function, **kwargs)
@@ -152,14 +160,21 @@ def plot_then_finalise(
     else:
         # this is an unexpected Callable, so we will give it a try
         print(f"Unknown proposed function: {first}; nonetheless, will give it a try.")
+        expected = {}
         plot_kwargs = kwargs_
+    validate_kwargs(expected | FINALISE_KW_TYPES, me, **plot_kwargs)
 
     # --- call the first function with the data and kwargs
-
     axes = first(data, **plot_kwargs)
 
-    # --- finalise the plot
+    # --- remove potentially overlapping kwargs
     fp_kwargs = limit_kwargs(FINALISE_KW_TYPES, **kwargs)
+    overlapping = expected.keys() & FINALISE_KW_TYPES.keys()
+    if overlapping:
+        for key in overlapping:
+            fp_kwargs.pop(key, None)  # remove overlapping keys from kwargs
+
+    # --- finalise the plot
     finalise_plot(axes, **fp_kwargs)
 
 
@@ -191,10 +206,12 @@ def multi_start(
     """
 
     # --- sanity checks
-    report_kwargs(called_from="multi_start", **kwargs)
-    data = check_clean_timeseries(data)
+    me = "multi_start"
+    report_kwargs(called_from=me, **kwargs)
     if not isinstance(starts, Iterable):
         raise ValueError("starts must be an iterable of None, Period or int")
+    # data not checked here, assume it is checked by the called
+    # plot function.
 
     # --- check the function argument
     original_tag: Final[str] = kwargs.get("tag", "")
@@ -219,7 +236,7 @@ def multi_column(
     The plot title will be the column name.
 
     Parameters
-    - data: DataFrame - The data to be plotted.
+    - data: DataFrame - The data to be plotted
     - function: Callable - The plotting function to be used.
     - **kwargs: Additional keyword arguments to be passed to
       the plotting function.
@@ -228,8 +245,12 @@ def multi_column(
     """
 
     # --- sanity checks
-    report_kwargs(called_from="multi_column", **kwargs)
-    data = check_clean_timeseries(data)
+    me = "multi_column"
+    report_kwargs(called_from=me, **kwargs)
+    if not isinstance(data, DataFrame):
+        raise TypeError("data must be a pandas DataFrame for multi_column()")
+    # Otherwise, the data is assumed to be checked by the called
+    # plot function, so we do not check it here.
 
     # --- check the function argument
     title_stem = kwargs.get("title", "")

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/postcovid_plot.py

@@ -4,29 +4,31 @@ Plot the pre-COVID trajectory against the current trend.
 """
 
 # --- imports
-from collections.abc import Sequence
 from pandas import DataFrame, Series, Period, PeriodIndex
 from matplotlib.pyplot import Axes
 from numpy import arange, polyfit
 
 from mgplot.settings import DataT, get_setting
-from mgplot.line_plot import line_plot
+from mgplot.line_plot import line_plot, LINE_KW_TYPES
 from mgplot.utilities import check_clean_timeseries
-from mgplot.kw_type_checking import report_kwargs, ExpectedTypeDict, validate_expected
+from mgplot.kw_type_checking import (
+    ExpectedTypeDict,
+    validate_kwargs,
+    validate_expected,
+    report_kwargs,
+)
 
 
 # --- constants
-WIDTH = "width"
-STYLE = "style"
 START_R = "start_r"
 END_R = "end_r"
+WIDTH = "width"
+STYLE = "style"
 
 POSTCOVID_KW_TYPES: ExpectedTypeDict = {
-    WIDTH: (Sequence, (int, float), int, float),
-    STYLE: (Sequence, (str,), str),
     START_R: Period,
     END_R: Period,
-}
+} | LINE_KW_TYPES
 validate_expected(POSTCOVID_KW_TYPES, "postcovid_plot")
 
 
@@ -64,9 +66,13 @@ def postcovid_plot(data: DataT, **kwargs) -> Axes:
     - ValueError if regression start is after regression end
     """
 
-    # --- sanity checks
-    report_kwargs(called_from="postcovid_plot", **kwargs)
-    data = check_clean_timeseries(data)
+    # --- check the kwargs
+    me = "postcovid_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(POSTCOVID_KW_TYPES, me, **kwargs)
+
+    # --- check the data
+    data = check_clean_timeseries(data, me)
     if not isinstance(data, Series):
         raise TypeError("The series argument must be a pandas Series")
     series: Series = data
@@ -103,11 +109,14 @@ def postcovid_plot(data: DataT, **kwargs) -> Axes:
     projection.name = "Pre-COVID projection"
     data_set = DataFrame([projection, recent]).T
 
+    # --- activate plot settings
     kwargs[WIDTH] = kwargs.pop(
-        WIDTH, [get_setting("line_normal"), get_setting("line_wide")]
-    )
-    kwargs[STYLE] = kwargs.pop(STYLE, ["--", "-"])
-    kwargs["legend"] = kwargs.pop("legend", True)
+        WIDTH, (get_setting("line_normal"), get_setting("line_wide"))
+    )  # series line is thicker than projection
+    kwargs[STYLE] = kwargs.pop(STYLE, ("--", "-"))  # dashed regression line
+    kwargs["legend"] = kwargs.pop("legend", True)  # show legend by default
+    kwargs["annotate"] = kwargs.pop("annotate", (False, True))  # annotate series only
+    kwargs["color"] = kwargs.pop("color", ("darkblue", "#dd0000"))
 
     return line_plot(
         data_set,

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/revision_plot.py

@@ -40,13 +40,15 @@ def revision_plot(data: DataT, **kwargs) -> Axes:
             apply int rounding.
     """
 
-    # --- sanity checks
-    data = check_clean_timeseries(data)
-    report_kwargs(called_from="revision_plot", **kwargs)
-    validate_kwargs(REVISION_KW_TYPES, "revision_plot", **kwargs)
+    # --- check the kwargs and data
+    me = "revision_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(REVISION_KW_TYPES, me, **kwargs)
+
+    data = check_clean_timeseries(data, me)
 
     # --- critical defaults
-    kwargs["plot_from"] = kwargs.get("plot_from", -18)
+    kwargs["plot_from"] = kwargs.get("plot_from", -19)
 
     # --- plot
     axes = line_plot(data, **kwargs)

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/run_plot.py

@@ -6,7 +6,7 @@ the 'runs' in a series.
 
 # --- imports
 from collections.abc import Sequence
-from pandas import Series, concat
+from pandas import Series, concat, period_range
 from matplotlib.pyplot import Axes
 from matplotlib import patheffects as pe
 
@@ -105,17 +105,17 @@ def _plot_runs(
             ),
             va=vert_align,
             ha="left",
-            fontsize="small",
+            fontsize="x-small",
             rotation=90,
         )
         text.set_path_effects([pe.withStroke(linewidth=5, foreground="w")])
 
 
-def run_plot(series: DataT, **kwargs) -> Axes:
+def run_plot(data: DataT, **kwargs) -> Axes:
     """Plot a series of percentage rates, highlighting the increasing runs.
 
     Arguments
-     - series - ordered pandas Series of percentages, with PeriodIndex
+     - data - ordered pandas Series of percentages, with PeriodIndex
      - **kwargs
         - threshold - float - used to ignore micro noise near zero
           (for example, threshhold=0.01)
@@ -129,17 +129,17 @@ def run_plot(series: DataT, **kwargs) -> Axes:
     Return
      - matplotlib Axes object"""
 
-    # --- sanity checks
-    series = check_clean_timeseries(series)
+    # --- check the kwargs
+    me = "run_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(RUN_KW_TYPES, me, **kwargs)
+
+    # --- check the data
+    series = check_clean_timeseries(data, me)
     if not isinstance(series, Series):
         raise TypeError("series must be a pandas Series for run_plot()")
     series, kwargs = constrain_data(series, **kwargs)
 
-    # --- check the kwargs
-    report_kwargs(called_from="run_plot", **kwargs)
-    expected = RUN_KW_TYPES
-    validate_kwargs(expected, "run_plot", **kwargs)
-
     # --- default arguments - in **kwargs
     kwargs[THRESHOLD] = kwargs.get(THRESHOLD, 0.1)
     kwargs[ROUND] = kwargs.get(ROUND, 2)
@@ -162,7 +162,7 @@ def run_plot(series: DataT, **kwargs) -> Axes:
 
     # plot the line
     kwargs["drawstyle"] = kwargs.get("drawstyle", "steps-post")
-    lp_kwargs = limit_kwargs(RUN_KW_TYPES, **kwargs)
+    lp_kwargs = limit_kwargs(LINE_KW_TYPES, **kwargs)
     axes = line_plot(series, **lp_kwargs)
 
     # plot the runs
@@ -180,3 +180,12 @@ def run_plot(series: DataT, **kwargs) -> Axes:
                 "Expected 'up', 'down', or 'both'."
             )
     return axes
+
+
+# test ---
+if __name__ == "__main__":
+    N_PERIODS = 25
+    periods = period_range(start="2020Q1", periods=N_PERIODS, freq="Q")
+    dataset = Series([1] * N_PERIODS, index=periods).cumsum()
+
+    ax = run_plot(data=dataset, junk="should generate a warning")

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/seastrend_plot.py

@@ -9,7 +9,7 @@ from matplotlib.pyplot import Axes
 from mgplot.settings import DataT
 from mgplot.line_plot import line_plot, LINE_KW_TYPES
 from mgplot.utilities import get_color_list, get_setting, check_clean_timeseries
-from mgplot.kw_type_checking import report_kwargs
+from mgplot.kw_type_checking import report_kwargs, validate_kwargs
 
 
 # --- constants
@@ -44,14 +44,17 @@ def seastrend_plot(data: DataT, **kwargs) -> Axes:
     # Note: we will rely on the line_plot() function to do most of the work.
     # including constraining the data to the plot_from keyword argument.
 
-    # --- sanity checks
-    report_kwargs(called_from="seastrend_plot", **kwargs)
-    data = check_clean_timeseries(data)
+    # --- check the kwargs
+    me = "seastrend_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(SEASTREND_KW_TYPES, me, **kwargs)
+
+    # --- check the data
+    data = check_clean_timeseries(data, me)
     if len(data.columns) < 2:
         raise ValueError(
             "seas_trend_plot() expects a DataFrame data item with at least 2 columns."
         )
-    # let line_plot() handle validate_kwargs()
 
     # --- defaults if not in kwargs
     colors = kwargs.pop(COLOR, get_color_list(2))

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/summary_plot.py

@@ -17,6 +17,7 @@ from pandas import DataFrame, Period
 
 # local imports
 from mgplot.settings import DataT
+from mgplot.finalise_plot import make_legend
 from mgplot.utilities import constrain_data, check_clean_timeseries
 from mgplot.kw_type_checking import (
     report_kwargs,
@@ -35,6 +36,7 @@ SUMMARY_KW_TYPES: ExpectedTypeDict = {
     "middle": float,
     "plot_type": str,
     "plot_from": (int, Period, type(None)),
+    "legend": (type(None), bool, dict, (str, object)),
 }
 validate_expected(SUMMARY_KW_TYPES, "summary_plot")
 
@@ -213,20 +215,31 @@ def summary_plot(
     Returns Axes.
     """
 
-    # --- sanity checks
-    data = check_clean_timeseries(data)
+    # --- check the kwargs
+    me = "summary_plot"
+    report_kwargs(called_from=me, **kwargs)
+    validate_kwargs(SUMMARY_KW_TYPES, me, **kwargs)
+
+    # --- check the data
+    data = check_clean_timeseries(data, me)
     if not isinstance(data, DataFrame):
         raise TypeError("data must be a pandas DataFrame for summary_plot()")
     df = DataFrame(data)  # syntactic sugar for type hinting
 
-    # --- check the arguments
-    report_kwargs("summary_plot", **kwargs)
-    validate_kwargs(SUMMARY_KW_TYPES, "summary_plot", **kwargs)
-
     # --- optional arguments
     verbose = kwargs.pop("verbose", False)
     middle = float(kwargs.pop("middle", 0.8))
     plot_type = kwargs.pop("plot_type", ZSCORES)
+    kwargs["legend"] = kwargs.get(
+        "legend",
+        {
+            # put the legend below the x-axis label
+            "loc": "upper center",
+            "fontsize": "xx-small",
+            "bbox_to_anchor": (0.5, -0.125),
+            "ncol": 4,
+        },
+    )
 
     # get the data, calculate z-scores and scaled scores based on the start period
     subset, kwargs = constrain_data(df, **kwargs)
@@ -236,5 +249,7 @@ def summary_plot(
     adjusted = z_scores if plot_type == ZSCORES else z_scaled
     ax = _horizontal_bar_plot(subset, adjusted, middle, plot_type, kwargs)
     ax.tick_params(axis="y", labelsize="small")
+    make_legend(ax, kwargs["legend"])
     ax.set_xlim(kwargs.get("xlim", None))  # provide space for the labels
+
     return ax

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot/utilities.py

@@ -25,7 +25,7 @@ from mgplot.settings import DataT
 
 
 # --- functions
-def check_clean_timeseries(data: DataT) -> DataT:
+def check_clean_timeseries(data: DataT, called_by: str) -> DataT:
     """
     Check timeseries data for the following:
     - That the data is a Series or DataFrame.
@@ -71,7 +71,10 @@ def check_clean_timeseries(data: DataT) -> DataT:
     missing = complete.difference(data_index)
     if not missing.empty:
         plural = "s" if len(missing) > 1 else ""
-        print(f"Warning: {len(missing)} period{plural} missing from data index. ")
+        print(
+            f"Warning: {len(missing)} period{plural} missing from data index. "
+            + f"Found by {called_by}."
+        )
 
     # --- return the final data
     return data
@@ -79,7 +82,7 @@ def check_clean_timeseries(data: DataT) -> DataT:
 
 def constrain_data(data: DataT, **kwargs) -> tuple[DataT, dict[str, Any]]:
     """
-    Constrain the data to start after a certain point.
+    Constrain the data to start after a certain point - kwargs["plot_from"].
 
     Args:
         data: the data to be constrained
@@ -234,7 +237,7 @@ if __name__ == "__main__":
     my_list = [np.nan, np.nan, 1.12345, 2.12345, 3.12345, 4.12345, 5.12345]
     _ = Series(my_list, period_range(start="2023-01", periods=len(my_list), freq="M"))
     _ = _.drop(index=[_.index[3]])
-    clean = check_clean_timeseries(_)
+    clean = check_clean_timeseries(_, "test")
     print(f"Cleaned data:\n{clean}")
 
     # --- test annotate_series()

{mgplot-0.1.1 → mgplot-0.1.3/src/mgplot.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mgplot
-Version: 0.1.1
-Summary: mgplot is a frontend for matplotlib
+Version: 0.1.3
+Summary: mgplot is a time-series/PeriodIndex frontend for matplotlib
 Project-URL: Homepage, https://github.com/bpalmer4/mgplot
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -18,6 +18,7 @@ Requires-Dist: pdoc
 Requires-Dist: pylint
 Requires-Dist: ruff
 Requires-Dist: pandas-stubs
+Requires-Dist: numpy-typing
 Requires-Dist: types-tabulate
 Provides-Extra: build
 Requires-Dist: setuptools; extra == "build"
@@ -64,7 +65,7 @@ The remaining arrguments are passed as keyword arguments:
 - summary_plot() -- plots the latest data in a summary-format against
   the range of previous data. 
 
-Once a plot has been generated and am Axes object is available. The
+Once a plot has been generated and an Axes object is available. The
 plot can be finalised or published, with appropriate titles and
 axis labels using
 - finalise_plot()

{mgplot-0.1.1 → mgplot-0.1.3}/src/mgplot.egg-info/requires.txt

@@ -10,6 +10,7 @@ pdoc
 pylint
 ruff
 pandas-stubs
+numpy-typing
 types-tabulate
 
 [build]