mgplot 0.1.0__tar.gz

mgplot-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,25 @@
+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/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "mgplot"
+version = "0.1.0"
+description = "mgplot is a frontend for matplotlib"
+readme = "README.md"
+requires-python = ">=3.11"
+
+dependencies = [
+    # - system
+    "typing",
+
+    # - data science 
+    "numpy",
+    "matplotlib",
+    "numpy",
+    "pandas",
+    "pathlib",
+    "tabulate",
+
+    # - code
+    "black",
+    "mypy",
+    "ruff",
+    "pylint",
+    "pdoc",
+    "twine",
+
+    # - typing
+    "pandas-stubs",
+    "types-tabulate",
+]
+
+[project.optional-dependencies]
+build = ["setuptools", "cython"]
+
+[project.urls]
+Homepage = "https://github.com/bpalmer4/mgplot"
+
+

mgplot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mgplot-0.1.0/src/mgplot/__init__.py

@@ -0,0 +1,121 @@
+"""
+mgplot
+------
+
+Package to provide a frontend to matplotlib for working
+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"
+__author__ = "Bryan Palmer"
+
+
+# --- local imports
+#    Do not import the utilities, test nor type-checking modules here.
+from mgplot.finalise_plot import finalise_plot
+from mgplot.bar_plot import bar_plot
+from mgplot.line_plot import line_plot
+from mgplot.seastrend_plot import seastrend_plot
+from mgplot.postcovid_plot import postcovid_plot
+from mgplot.revision_plot import revision_plot
+from mgplot.run_plot import run_plot
+from mgplot.summary_plot import summary_plot
+from mgplot.growth_plot import (
+    calc_growth,
+    raw_growth_plot,
+    series_growth_plot,
+)
+from mgplot.multi_plot import (
+    multi_start,
+    multi_column,
+    plot_then_finalise,
+)
+from mgplot.colors import (
+    get_color,
+    get_party_palette,
+    colorise_list,
+    contrast,
+    abbreviate_state,
+    state_names,
+    state_abbrs,
+)
+from mgplot.settings import (
+    get_setting,
+    set_setting,
+    set_chart_dir,
+    clear_chart_dir,
+)
+from mgplot.finalisers import (
+    line_plot_finalise,
+    bar_plot_finalise,
+    seastrend_plot_finalise,
+    postcovid_plot_finalise,
+    revision_plot_finalise,
+    summary_plot_finalise,
+    raw_growth_plot_finalise,
+    series_growth_plot_finalise,
+    run_plot_finalise,
+)
+
+
+# --- version and author
+__version__ = "0.0.1"
+__author__ = "Bryan Palmer"
+
+
+# --- public API
+__all__ = (
+    "__version__",
+    "__author__",
+    # --- settings
+    "get_setting",
+    "set_setting",
+    "set_chart_dir",
+    "clear_chart_dir",
+    # --- colors
+    "get_color",
+    "get_party_palette",
+    "colorise_list",
+    "contrast",
+    "abbreviate_state",
+    "state_names",
+    "state_abbrs",
+    # --- finalise_plot
+    "finalise_plot",
+    # --- line_plot
+    "line_plot",
+    # --- bar plot
+    "bar_plot",
+    # --- seastrend_plot
+    "seastrend_plot",
+    # --- postcovid_plot
+    "postcovid_plot",
+    # --- revision_plot
+    "revision_plot",
+    # --- run_plot
+    "run_plot",
+    # --- summary_plot
+    "summary_plot",
+    # --- growth_plot
+    "calc_growth",
+    "raw_growth_plot",
+    "series_growth_plot",
+    # --- multi_plot
+    "multi_start",
+    "multi_column",
+    "plot_then_finalise",
+    # --- finaliser functions
+    "line_plot_finalise",
+    "bar_plot_finalise",
+    "seastrend_plot_finalise",
+    "postcovid_plot_finalise",
+    "revision_plot_finalise",
+    "summary_plot_finalise",
+    "raw_growth_plot_finalise",
+    "series_growth_plot_finalise",
+    "run_plot_finalise",
+    # --- The rest are internal use only
+)
+# __pdoc__: dict[str, Any] = {"test": False}  # hide submodules from documentation

mgplot-0.1.0/src/mgplot/bar_plot.py

@@ -0,0 +1,107 @@
+"""
+bar_plot.py
+This module contains functions to create bar plots using Matplotlib.
+Note: bar plots in Matplotlib are not the same as bar charts in other
+libraries. Bar plots are used to represent categorical data with
+rectangular bars. As a result, bar plots and line plots typically
+cannot be plotted on the same axes.
+"""
+
+# --- imports
+from typing import Any
+from collections.abc import Sequence
+from pandas import DataFrame, period_range, PeriodIndex
+import matplotlib.pyplot as plt
+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.date_utils import set_labels
+
+
+# --- constants
+BAR_PLOT_KW_TYPES: ExpectedTypeDict = {
+    "color": (str, Sequence, (str,)),
+    "width": float,
+    "stacked": bool,
+    "rotation": (int, float),
+    "bar_legend": bool,
+    "max_ticks": int,
+    "plot_from": (int, PeriodIndex, type(None)),
+}
+validate_expected(BAR_PLOT_KW_TYPES, "bar_plot")
+
+
+# --- functions
+def bar_plot(
+    data: DataT,
+    **kwargs,
+) -> Axes:
+    """
+    Create a bar plot from the given data. Each column in the DataFrame
+    will be stacked on top of each other, with positive values above
+    zero and negative values below zero.
+
+    Parameters
+    - data: Series - The data to plot. Can be a DataFrame or a Series.
+    - **kwargs: dict Additional keyword arguments for customization.
+        - color: list - A list of colors for the each series (column) in  the DataFrame.
+        - width: float - The width of the bars.
+        - stacked: bool - If True, the bars will be stacked.
+        - rotation: int - The rotation angle in degrees for the x-axis labels.
+        - bar_legend: bool - If True, show the legend. Defaults to True
+          if more than one bar being plotted for each category.
+        - "max_ticks": int - The maximum number of ticks on the x-axis,
+          (this option only applies to PeriodIndex data.).
+
+    Note: This function does not assume all data is timeseries with a PeriodIndex,
+
+    Returns
+    - axes: Axes - The axes for the plot.
+    """
+
+    # --- validate the kwargs
+    validate_kwargs(BAR_PLOT_KW_TYPES, "bar_plot", **kwargs)
+    # note data may not be time-series or have a period index.
+
+    # --- get the data
+    df = DataFrame(data)  # really we are only plotting DataFrames
+    df, kwargs = constrain_data(df, **kwargs)
+    item_count = len(df.columns)
+
+    defaults: dict[str, Any] = {
+        "color": get_color_list(item_count),
+        "width": get_setting("bar_width"),
+        "stacked": False,
+        "rotation": 90,
+        "bar_legend": (item_count > 1),
+        "max_ticks": 10,
+    }
+    bar_args, remaining_kwargs = apply_defaults(item_count, defaults, kwargs)
+
+    # --- plot the data
+    axes, _rkwargs = get_axes(**remaining_kwargs)
+
+    df.plot.bar(
+        ax=axes,
+        color=bar_args["color"],
+        stacked=bar_args["stacked"][0],
+        width=bar_args["width"][0],
+        legend=bar_args["bar_legend"][0],
+    )
+
+    rotate_labels = True
+    if isinstance(df.index, PeriodIndex):
+        complete = period_range(
+            start=df.index.min(), end=df.index.max(), freq=df.index.freqstr
+        )
+        if complete.equals(df.index):
+            # if the index is complete, we can set the labels
+            set_labels(axes, df.index, bar_args["max_ticks"][0])
+            rotate_labels = False
+
+    if rotate_labels:
+        plt.xticks(rotation=bar_args["rotation"][0])
+
+    return axes

mgplot-0.1.0/src/mgplot/colors.py

@@ -0,0 +1,199 @@
+"""
+colors.py
+This module provides a set of color palettes and functions to generate colors
+for Australian states and territories and major political parties.
+It also provides Australian state names and their abbreviations.
+"""
+
+# --- Imports
+from typing import Iterable
+
+
+# --- Functions
+def get_party_palette(party_text: str) -> str:
+    """
+    Return a matplotlib color-map name based on party_text.
+    Works for Australian major political parties.
+    """
+
+    # Note: light to dark maps work best
+    match party_text.lower():
+        case "alp" | "labor":
+            return "Reds"
+        case "l/np" | "coalition":
+            return "Blues"
+        case "grn" | "green" | "greens":
+            return "Greens"
+        case "oth" | "other":
+            return "YlOrBr"
+        case "onp" | "one nation":
+            return "YlGnBu"
+    return "Purples"
+
+
+def get_color(s: str) -> str:
+    """
+    Return a matplotlib color for a party label
+    or an Australian state/territory.
+    """
+
+    color_map = {
+        # --- Australian states and territories
+        ("wa", "western australia"): "gold",
+        ("sa", "south australia"): "red",
+        ("nt", "northern territory"): "#CC7722",  # ochre
+        ("nsw", "new south wales"): "deepskyblue",
+        ("act", "australian capital territory"): "blue",
+        ("vic", "victoria"): "navy",
+        ("tas", "tasmania"): "seagreen",  # bottle green #006A4E?
+        ("qld", "queensland"): "#c32148",  # a lighter maroon
+        ("australia", "aus"): "grey",
+        # --- political parties
+        ("dissatisfied",): "darkorange",  # must be before satisfied
+        ("satisfied",): "mediumblue",
+        (
+            "lnp",
+            "l/np",
+            "coalition",
+            "dutton",
+            "ley",
+        ): "royalblue",
+        (
+            "alp",
+            "labor",
+            "albanese",
+        ): "indianred",
+        (
+            "grn",
+            "green",
+            "greens",
+        ): "mediumseagreen",
+        (
+            "other",
+            "oth",
+        ): "darkorange",
+    }
+
+    for find_me, return_me in color_map.items():
+        if any(x == s.lower() for x in find_me):
+            return return_me
+
+    return "darkgrey"
+
+
+def colorise_list(party_list: Iterable) -> list[str]:
+    """
+    Return a list of party/state colors for a party_list.
+    """
+
+    return [get_color(x) for x in party_list]
+
+
+def contrast(orig_color: str) -> str:
+    """
+    Provide a constrasting color to any party color
+    generated by get_color() above.
+    """
+
+    new_color = "black"
+    match orig_color:
+        case "royalblue":
+            new_color = "indianred"
+        case "indianred":
+            new_color = "mediumblue"
+
+        case "darkorange":
+            new_color = "mediumblue"
+        case "mediumblue":
+            new_color = "darkorange"
+
+        case "mediumseagreen":
+            new_color = "darkblue"
+
+        case "darkgrey":
+            new_color = "hotpink"
+
+    return new_color
+
+
+# --- Australian state names
+_state_names: dict[str, str] = {
+    "New South Wales": "NSW",
+    "Victoria": "Vic",
+    "Queensland": "Qld",
+    "South Australia": "SA",
+    "Western Australia": "WA",
+    "Tasmania": "Tas",
+    "Northern Territory": "NT",
+    "Australian Capital Territory": "ACT",
+}
+
+# a tuple of standard state names
+state_names = tuple(_state_names.keys())
+
+# a tuple of standard state abbreviations
+state_abbrs = tuple(_state_names.values())
+
+# a map of state name to their abbreviation
+# including upper and lower case mappings
+_state_names_multi: dict[str, str] = {}
+for k, v in _state_names.items():
+    # allow for fast different case matches
+    _state_names_multi[k.lower()] = v
+    _state_names_multi[k.lower()] = v
+    _state_names_multi[v.lower()] = v
+
+
+def abbreviate_state(state: str) -> str:
+    """
+    A function to abbreviate long-form state
+    names.
+
+    Arguments
+    -   state: the long-form state name.
+
+    Return the abbreviation for a state name.
+    """
+
+    return _state_names_multi.get(state.lower(), state)
+
+
+# --- test code
+if __name__ == "__main__":
+    # Test the color functions
+    check = ["Western Australia", "L/NP", "ALP", "Greens", "Dissatisfied", "Ley"]
+    for party in check:
+        print(f"{party} -> {get_color(party)}")
+
+    # Test the party palette function
+    print()
+    check = ["ALP", "L/NP", "Greens"]
+    for party in check:
+        print(f"{party} -> {get_party_palette(party)}")
+
+    # Test the abbreviate_state function
+    print()
+    check = [
+        "New South Wales",
+        "nsw",
+        "Victoria",
+        "victoria",
+        "VICTORIA",
+        "VIC",
+        "rubbish",
+        "Queensland",
+        "South Australia",
+        "Western Australia",
+        "Tasmania",
+        "Northern Territory",
+        "Australian Capital Territory",
+        "ACT",
+    ]
+
+    for state_ in check:
+        print(f"{state_} -> {abbreviate_state(state_)}")
+
+    # Test the get_color function for states
+    print()
+    for state_ in check:
+        print(f"{state_} -> {get_color(state_)}")