mgplot 0.1.0__py3-none-any.whl

mgplot/utilities.py

@@ -0,0 +1,254 @@
+"""
+utilities.py:
+Utiltiy functions used by more than one mgplot module.
+These are not intended to be used directly by the user.
+
+Functions:
+- check_clean_timeseries()
+- constrain_data()
+- apply_defaults()
+- get_color_list()
+- get_axes()
+- annotate_series()
+"""
+
+# --- imports
+import math
+from typing import Any
+from pandas import Series, DataFrame, Period, PeriodIndex, period_range
+import numpy as np
+from matplotlib import cm
+from matplotlib.pyplot import Axes, subplots
+
+from mgplot.settings import get_setting
+from mgplot.settings import DataT
+
+
+# --- functions
+def check_clean_timeseries(data: DataT) -> DataT:
+    """
+    Check timeseries data for the following:
+    - That the data is a Series or DataFrame.
+    - That the index is a PeriodIndex
+    - That the index is unique and monotonic increasing
+
+    Remove any leading NAN rows or columns from the data.
+
+    Return the cleaned data.
+
+    Args:
+    - data: the data to be cleaned
+
+    Returns:
+    - The data with leading NaN values removed.
+
+    Raises TypeError/Value if problems found
+    """
+
+    # --- initial checks
+    if not isinstance(data, (Series, DataFrame)):
+        raise TypeError("Data must be a pandas Series or DataFrame.")
+    if not isinstance(data.index, PeriodIndex):
+        raise TypeError("Data index must be a PeriodIndex.")
+    if not data.index.is_unique:
+        raise ValueError("Data index must be unique.")
+    if not data.index.is_monotonic_increasing:
+        raise ValueError("Data index must be monotonic increasing.")
+
+    # --- remove any leading NaNs
+    start = data.first_valid_index()
+    if start is None:
+        return data  # no valid index, return original data
+    if not isinstance(start, Period):  # syntactic sugar for type hinting
+        raise TypeError("First valid index must be a Period.")
+    data = data.loc[data.index >= start]
+
+    # --- report and missing periods (ie. potentially incomplete data)
+    data_index = PeriodIndex(data.index)  # syntactic sugar for type hinting
+    complete = period_range(
+        start=data_index.min(), end=data_index.max(), freq=data_index.freq
+    )
+    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. ")
+
+    # --- return the final data
+    return data
+
+
+def constrain_data(data: DataT, **kwargs) -> tuple[DataT, dict[str, Any]]:
+    """
+    Constrain the data to start after a certain point.
+
+    Args:
+        data: the data to be constrained
+        kwargs: keyword arguments - uses "plot_from" in kwargs to constrain the data
+
+    Assume:
+    - that mgplot.utilitiesd.check_clean_timeseries() has already been applied
+    - that the data is a Series or DataFrame with a PeriodIndex
+    - that the index is unique and monotonic increasing
+
+    Returns:
+        A tuple of the constrained data and the modified kwargs.
+    """
+
+    plot_from = kwargs.pop("plot_from", 0)
+    if isinstance(plot_from, Period) and isinstance(data.index, PeriodIndex):
+        data = data.loc[data.index >= plot_from]
+    elif isinstance(plot_from, int):
+        data = data.iloc[plot_from:]
+    elif plot_from is None:
+        pass
+    else:
+        print(f"Warning: {plot_from=} either not a valid type or not applicable. ")
+    return data, kwargs
+
+
+def apply_defaults(
+    length: int, defaults: dict[str, Any], kwargs_d: dict[str, Any]
+) -> tuple[dict[str, Any], dict[str, list[Any] | tuple[Any]]]:
+    """
+    Get arguments from kwargs_d, and apply a default from the
+    defaults dict if not there. Remove the item from kwargs_d.
+
+    Agumenets:
+        length: the number of lines to be plotted
+        defaults: a dictionary of default values
+        kwargs_d: a dictionary of keyword arguments
+
+    Returns a tuple of two dictionaries:
+        - the first is a dictionary populated with the arguments
+          from kwargs_d or the defaults dictionary, where the values
+          are placed in lists or tuples if not already in that format
+        - the second is a modified kwargs_d dictionary, with the default
+          keys removed.
+    """
+
+    returnable = {}  # return vehicle
+
+    for option, default in defaults.items():
+        val = kwargs_d.get(option, default)
+        # make sure our return value is a list/tuple
+        returnable[option] = val if isinstance(val, (list, tuple)) else (val,)
+
+        # remove the option from kwargs
+        if option in kwargs_d:
+            del kwargs_d[option]
+
+        # repeat multi-item lists if not long enough for all lines to be plotted
+        if len(returnable[option]) < length and length > 1:
+            multiplier = math.ceil(length / len(returnable[option]))
+            returnable[option] = returnable[option] * multiplier
+
+    return returnable, kwargs_d
+
+
+def get_color_list(count: int) -> list[str]:
+    """
+    Get a list of colours for plotting.
+
+    Args:
+        count: the number of colours to return
+
+    Returns:
+        A list of colours.
+    """
+
+    colors: dict[int, list[str]] = get_setting("colors")
+    if count in colors:
+        return colors[count]
+
+    if count < max(colors.keys()):
+        options = [k for k in colors.keys() if k > count]
+        return colors[min(options)][:count]
+
+    c = cm.get_cmap("nipy_spectral")(np.linspace(0, 1, count))
+    return [f"#{int(x*255):02x}{int(y*255):02x}{int(z*255):02x}" for x, y, z, _ in c]
+
+
+def get_axes(**kwargs) -> tuple[Axes, dict[str, Any]]:
+    """
+    Get the axes to plot on.
+    If not passed in kwargs, create a new figure and axes.
+    """
+
+    ax = "ax"
+    if ax in kwargs and kwargs[ax] is not None:
+        axes: Axes = kwargs[ax]
+        if not isinstance(axes, Axes):
+            raise TypeError("The ax argument must be a matplotlib Axes object")
+        return axes, {}
+
+    figsize = kwargs.pop("figsize", get_setting("figsize"))
+    _fig, axes = subplots(figsize=figsize)
+    return axes, kwargs
+
+
+def annotate_series(
+    series: Series,
+    axes: Axes,
+    rounding: int | bool = False,
+    color: str = "#444444",
+    fontsize: int | str = "small",
+    **kwargs,
+) -> None:
+    """Annotate the right-hand end-point of a line-plotted series."""
+
+    latest = series.dropna()
+    if latest.empty:
+        return
+
+    x, y = latest.index[-1], latest.iloc[-1]
+    if y is None or math.isnan(y):
+        return
+
+    r_string = f" {y}"  # default to no rounding
+    original = rounding
+    if isinstance(rounding, bool) and rounding:
+        rounding = 0 if y >= 100 else 1 if y >= 10 else 2
+    if not isinstance(rounding, bool) and isinstance(rounding, int):
+        r_string = f" {y:.{rounding}f}"
+
+    if "test" in kwargs:
+        print(f"annotate_series: {x=}, {y=}, {original=} {rounding=} {r_string=}")
+        return
+
+    axes.text(
+        x=x,
+        y=y,
+        s=r_string,
+        ha="left",
+        va="center",
+        fontsize=fontsize,
+        color=color,
+        font="Helvetica",
+    )
+
+
+# --- test code
+if __name__ == "__main__":
+
+    # --- test check_clean_timeseries_data()
+    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(_)
+    print(f"Cleaned data:\n{clean}")
+
+    # --- test annotate_series()
+    print()
+    _fig, ax_ = subplots(figsize=(9, 4.5))
+    series2_ = Series([1.12345, 2.12345, 3.12345, 4.12345, 5.12345])
+    rounding_ = (
+        False,
+        True,
+        0,
+        1,
+        2,
+        3,
+    )
+    for r in rounding_:
+        annotate_series(series2_, ax_, rounding=r, test=True)
+    print("Done")

mgplot-0.1.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: mgplot
+Version: 0.1.0
+Summary: mgplot is a frontend for matplotlib
+Project-URL: Homepage, https://github.com/bpalmer4/mgplot
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pathlib
+Requires-Dist: tabulate
+Requires-Dist: black
+Requires-Dist: mypy
+Requires-Dist: ruff
+Requires-Dist: pylint
+Requires-Dist: pdoc
+Requires-Dist: twine
+Requires-Dist: pandas-stubs
+Requires-Dist: types-tabulate
+Provides-Extra: build
+Requires-Dist: setuptools; extra == "build"
+Requires-Dist: cython; extra == "build"
+Dynamic: license-file
+
+mgplot
+======
+
+Description
+-----------
+mgplot is an open-source python frontend for the matplotlib 
+package to:
+1. produce time-series charts that can be a little difficult or 
+   tricky to produce directly, 
+2. finalise (or publish) charts with titles, xlabels, ylabels,
+   etc., all while 
+3. minimising code duplication, and maintaining a common plot
+   style or look-and-feel.
+
+Import
+------
+```
+import mgplot as mg
+```
+
+For more information
+--------------------
+- See the dicumentation folder
+
+---

mgplot-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+mgplot/__init__.py,sha256=RJclV9vC_sv5--PRr3AOM_cPZM5yFwxd-0__OnaB1KQ,2787
+mgplot/bar_plot.py,sha256=lNo4pgLsjL7AwEy-ZzLn3zs2O2BQMAlzb9X8m5bWYlA,3604
+mgplot/colors.py,sha256=0cAbC5pqZO2dCCPnRRG2x9xas9TQXwIuI_OgC0JaFNE,5066
+mgplot/date_utils.py,sha256=5ZSaXmwtfPyDKObeO69uoEzzeAgpwBYPYut_7TFsmz4,9285
+mgplot/finalise_plot.py,sha256=_fPioM5WpWni5QyPsm5gEhiImn0tpzZx4AW58VI0i4k,11636
+mgplot/finalisers.py,sha256=DU5MKAZ2MFv4iZqm4ea4k9U_oHKjJGP3_hdFznpmLco,10287
+mgplot/growth_plot.py,sha256=isE1olT94se2brcSQ919X5yyC00K4XptUxEhSA_6nOw,9151
+mgplot/kw_type_checking.py,sha256=zS_KAzaNdnaa1xl0EhLaSLsAPzF7DP9qrydYBQ9q5RM,14699
+mgplot/line_plot.py,sha256=BjdbkY5v70_qes6NBGUGyDsVXUpuUS7iP5MF3eeOagc,5589
+mgplot/multi_plot.py,sha256=3HI93vNBF5HD94Hm7WyRqPm86wUQqjZpcYNupiY6TZI,10412
+mgplot/postcovid_plot.py,sha256=ZzYIMdZCrECaVQNMkHo1nuB9Sx6hIy4m_hffYPSNX-Q,3622
+mgplot/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+mgplot/revision_plot.py,sha256=kOp4CSo2UMFLpc0XL2v3PBehNj2tdOpKaPCdPP5uBH4,1809
+mgplot/run_plot.py,sha256=JlCxEVJjXXmBkuvqZKoUalTlMxs8vCftr1deawCjek8,5871
+mgplot/seastrend_plot.py,sha256=SWMxUVfDV2QhfRCttSlRmloM5Zyh0XbZXpZa67FJO0M,2124
+mgplot/settings.py,sha256=52yTecdnjUSGQ9NNb3X-rPSkBg8poH1rzDSrAYG0Pws,4716
+mgplot/summary_plot.py,sha256=ze4TFksPHf-oVLC-IwIfCKy5q64z2XOOCBaV4acnLKk,7318
+mgplot/test.py,sha256=ZOlsltSC8E6vRfQ70tXz6CDkWyDpJZ2e9DNYcCxAsMs,709
+mgplot/utilities.py,sha256=vjHaKxQU5o0ehuFTAtM65bpv4ljz4iS_eDkXEhPTaF0,7682
+mgplot-0.1.0.dist-info/licenses/LICENSE,sha256=6ZyruOwF8J7mY25-vZHdOibtY8cSNLz0vWeH59TLhtw,1082
+mgplot-0.1.0.dist-info/METADATA,sha256=425bBf2LSHqpeb7O3JcR6VRvCJtwp8ZMB9lUrYo28DI,1212
+mgplot-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mgplot-0.1.0.dist-info/top_level.txt,sha256=qv2cns5Wdn4prddz5KkfsMZc50nwh8clzbIkkLaQV3E,7
+mgplot-0.1.0.dist-info/RECORD,,

mgplot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mgplot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2025 Bryan Palmer (Canberra Australia)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

mgplot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mgplot