mgplot 0.1.0__py3-none-any.whl

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/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/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_)}")