mgplot 0.1.6__tar.gz → 0.1.7__tar.gz

{mgplot-0.1.6 → mgplot-0.1.7}/CHANGELOG.md

@@ -1,3 +1,11 @@
+Version 0.1.7 - released 06-Jun-2025 (Canberra, Australia)
+
+* major changes
+     - reworked growth_plot so that it used the line_plot()
+       and bar_plot() functions. 
+
+---
+
 Version 0.1.6 - released 03-Jun-2025 (Canberra, Australia)
 
 * minor changes

{mgplot-0.1.6 → mgplot-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mgplot
-Version: 0.1.6
+Version: 0.1.7
 Summary: mgplot is a time-series/PeriodIndex frontend for matplotlib
 Project-URL: Repository, https://github.com/bpalmer4/mgplot
 Project-URL: Homepage, https://github.com/bpalmer4/mgplot

{mgplot-0.1.6 → mgplot-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mgplot"
-version = "0.1.6"
+version = "0.1.7"
 description = "mgplot is a time-series/PeriodIndex frontend for matplotlib"
 readme = "README.md"
 requires-python = ">=3.12"

{mgplot-0.1.6 → mgplot-0.1.7}/src/mgplot/__init__.py

@@ -21,10 +21,10 @@ 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 (
     calc_growth,
-    raw_growth_plot,
+    growth_plot,
     series_growth_plot,
     SERIES_GROWTH_KW_TYPES,
-    RAW_GROWTH_KW_TYPES,
+    GROWTH_KW_TYPES,
 )
 from mgplot.multi_plot import (
     multi_start,
@@ -53,7 +53,7 @@ from mgplot.finalisers import (
     postcovid_plot_finalise,
     revision_plot_finalise,
     summary_plot_finalise,
-    raw_growth_plot_finalise,
+    growth_plot_finalise,
     series_growth_plot_finalise,
     run_plot_finalise,
 )
@@ -102,7 +102,7 @@ __all__ = (
     "summary_plot",
     # --- growth_plot
     "calc_growth",
-    "raw_growth_plot",
+    "growth_plot",
     "series_growth_plot",
     # --- multi_plot
     "multi_start",
@@ -115,7 +115,7 @@ __all__ = (
     "postcovid_plot_finalise",
     "revision_plot_finalise",
     "summary_plot_finalise",
-    "raw_growth_plot_finalise",
+    "growth_plot_finalise",
     "series_growth_plot_finalise",
     "run_plot_finalise",
     # --- typing information
@@ -128,7 +128,7 @@ __all__ = (
     "RUN_KW_TYPES",
     "SUMMARY_KW_TYPES",
     "SERIES_GROWTH_KW_TYPES",
-    "RAW_GROWTH_KW_TYPES",
+    "GROWTH_KW_TYPES",
     # --- The rest are internal use only
 )
 # __pdoc__: dict[str, Any] = {"test": False}  # hide submodules from documentation

mgplot-0.1.6/src/mgplot/date_utils.py → mgplot-0.1.7/src/mgplot/axis_utils.py

@@ -1,16 +1,66 @@
 """
-date_utils.py
-This module contains functions to work with date-like
-(i.e. not time-like) PeriodIndex frequencies in Pandas.
-It is used to label the x-axis of a plot with the
-appropriate date-like labels.
+axis_utils.py
+
+This module contains functions to work with categorical
+axis in Matplotlib, specifically:
+1) integers
+2) date-like PeriodIndex frequencies
+3) strings
 """
 
 import calendar
 from enum import Enum
-from pandas import Period, PeriodIndex, period_range
+from pandas import Series, Index, Period, PeriodIndex, period_range
+from pandas.api.types import is_integer_dtype, is_string_dtype
 from matplotlib.pyplot import Axes
 
+from mgplot.settings import DataT
+
+
+def is_categorical(data: DataT) -> bool:
+    """
+    Check if the data.index is usefully categorical
+    (index needs to be complete, and unique).
+
+    Note: we plot categoricals using bar plots.
+    """
+
+    if data.index.has_duplicates or data.index.hasnans or data.index.empty:
+        return False
+    if is_string_dtype(data.index.dtype):
+        # unique strings are categoricals by default
+        return True
+    if (
+        not data.index.is_monotonic_increasing
+        and not data.index.is_monotonic_decreasing
+    ):
+        # these categoricals should be monotonic
+        return False
+    if is_integer_dtype(data.index.dtype):
+        # completeness check for integers
+        return data.index.max() - data.index.min() == len(data.index) - 1
+    if isinstance(data.index, PeriodIndex):
+        # completeness check for PeriodIndex
+        return (
+            data.index.max().ordinal - data.index.min().ordinal == len(data.index) - 1
+        )
+
+    return False
+
+
+def map_periodindex(data: DataT) -> None | tuple[DataT, PeriodIndex]:
+    """
+    map a PeriodIndex to an integer index.
+    """
+    if not is_categorical(data):
+        return None
+    if not isinstance(data.index, PeriodIndex):
+        return None
+    original_index = data.index
+    ordinals = tuple(p.ordinal for p in PeriodIndex(data.index))
+    data.index = Index(ordinals)
+    return data, original_index
+
 
 class DateLike(Enum):
     """Recognised date-like PeriodIndex frequencies"""
@@ -285,8 +335,7 @@ def make_ilabels(p: PeriodIndex, max_ticks: int) -> tuple[list[int], list[str]]:
     """
 
     labels = make_labels(p, max_ticks)
-    base = p.min().ordinal
-    ticks = [x.ordinal - base for x in sorted(labels.keys())]
+    ticks = [x.ordinal for x in sorted(labels.keys())]
     ticklabels = [labels[x] for x in sorted(labels.keys())]
 
     return ticks, ticklabels
@@ -322,3 +371,14 @@ if __name__ == "__main__":
         print(f"Test {index + 1}")
         print("Labels:", make_labels(test, 10), "\n")
         print("========")
+
+    N = 4
+    int_test1: Series = Series(range(N), index=range(N))
+    int_test2: Series = Series(range(N), index=[1, 2, 3, 4])
+    str_test3: Series = Series(range(N), index=[f"Item {i}" for i in range(N)])
+    pi_test4: Series = Series(
+        range(N), index=period_range(start="2020-01", periods=N, freq="M")
+    )
+    for s_test in (int_test1, int_test2, str_test3, pi_test4):
+        print(f"Testing is_categorical {s_test.index}:", is_categorical(s_test))
+        print("========")

mgplot-0.1.7/src/mgplot/bar_plot.py

@@ -0,0 +1,316 @@
+"""
+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, Final
+from collections.abc import Sequence
+
+import numpy as np
+from pandas import Series, DataFrame, PeriodIndex
+import matplotlib.pyplot as plt
+from matplotlib.pyplot import Axes
+import matplotlib.patheffects as pe
+
+
+from mgplot.settings import DataT, get_setting
+from mgplot.finalise_plot import make_legend
+from mgplot.utilities import (
+    apply_defaults,
+    get_color_list,
+    get_axes,
+    constrain_data,
+    default_rounding,
+)
+from mgplot.kw_type_checking import (
+    ExpectedTypeDict,
+    validate_expected,
+    report_kwargs,
+    validate_kwargs,
+)
+from mgplot.axis_utils import set_labels, map_periodindex, is_categorical
+
+
+# --- constants
+# - plot and data constants
+AXES = "ax"  # used to control the axes to plot on
+DROPNA = "dropna"  # used to control dropping NaN values
+STACKED = "stacked"  # used to control if the bars are stacked or grouped
+ROTATION = "rotation"  # used to control the rotation of x-axis labels
+MAX_TICKS = "max_ticks"  # used to control the maximum number of ticks on the x-axis
+PLOT_FROM = "plot_from"  # used to control the starting point of the plot
+# - bar plot constants
+LEGEND = "legend"  # used to control the legend display
+COLOR = "color"  # used to control the color of the bars
+WIDTH = "width"  # used to control the width of the bars
+LABEL_SERIES = "label_series"  # used to control the labeling of series in the legend
+# - annoptation constants
+ANNOTATE = "annotate"  # used to control the annotation of bars
+FONTSIZE = "fontsize"  # used to control the font size of annotations
+FONTNAME = "fontname"  # used to control the font name of annotations
+BAR_ROTATION = "bar_rotation"  # used to control the rotation of bar labels
+ANNO_COLOR = "annotate_color"  # used to control the color of annotations
+ROUNDING = "rounding"  # used to control the rounding of annotations
+ABOVE = "above"  # used to control the position of annotations
+
+BAR_KW_TYPES: Final[ExpectedTypeDict] = {
+    # --- options for the entire bar plot
+    AXES: (Axes, type(None)),  # axes to plot on, or None for new axes
+    STACKED: bool,  # if True, the bars will be stacked. If False, they will be grouped.
+    ROTATION: (int, float),  # rotation of x-axis labels in degrees
+    MAX_TICKS: int,
+    PLOT_FROM: (int, PeriodIndex, type(None)),
+    LEGEND: (bool, dict, (str, object), type(None)),
+    # --- options for each bar ...
+    COLOR: (str, Sequence, (str,)),
+    LABEL_SERIES: (bool, Sequence, (bool,)),
+    WIDTH: (float, Sequence, (float,)),
+    # - options for bar annotations
+    ANNOTATE: (type(None), bool),  # None, True
+    FONTSIZE: (int, float, str),
+    FONTNAME: (str),
+    BAR_ROTATION: (int, float),  # rotation of bar labels
+    ROUNDING: int,
+    ANNO_COLOR: (str, type(None)),  # color of annotations
+    ABOVE: bool,  # if True, annotations are above the bar
+    # - other bar attributes
+}
+validate_expected(BAR_KW_TYPES, "bar_plot")
+
+
+# --- functions
+def annotate_bars(
+    series: Series,
+    offset: float,
+    base: np.ndarray[tuple[int, ...], np.dtype[Any]],
+    axes: Axes,
+    **kwargs,
+) -> None:
+    """Bar plot annotations."""
+
+    # --- only annotate in limited circumstances
+    if ANNOTATE not in kwargs or kwargs[ANNOTATE] is None or kwargs[ANNOTATE] is False:
+        return
+    max_annotations = 30
+    if len(series) > max_annotations:
+        return
+
+    # --- internal logic check
+    if len(base) != len(series):
+        print(
+            f"Warning: base array length {len(base)} does not match series length {len(series)}."
+        )
+        return
+
+    # --- assemble the annotation parameters
+    above: Final[bool | None] = kwargs.get(ABOVE, False)  # None is also False-ish
+    annotate_style = {
+        "fontsize": kwargs.get(FONTSIZE),
+        "fontname": kwargs.get(FONTNAME),
+        "color": kwargs.get(ANNO_COLOR),
+        "rotation": kwargs.get(BAR_ROTATION),
+    }
+    rounding = default_rounding(series=series, provided=kwargs.get(ROUNDING, None))
+    adjustment = (series.max() - series.min()) * 0.01
+    rebase = series.index.min()
+
+    # --- annotate each bar
+    for index, value in zip(series.index.astype(int), series):  # mypy syntactic sugar
+        position = base[index - rebase] + (adjustment if value >= 0 else -adjustment)
+        if above:
+            position += value
+        text = axes.text(
+            x=index + offset,
+            y=position,
+            s=f"{value:.{rounding}f}",
+            ha="center",
+            va="bottom" if value >= 0 else "top",
+            **annotate_style,
+        )
+        if not above and "foreground" in kwargs:
+            # apply a stroke-effect to within bar annotations
+            # to make them more readable with very small bars.
+            text.set_path_effects(
+                [pe.withStroke(linewidth=2, foreground=kwargs.get("foreground"))]
+            )
+
+
+def grouped(axes, df: DataFrame, anno_args, **kwargs) -> None:
+    """
+    plot a grouped bar plot
+    """
+
+    series_count = len(df.columns)
+
+    for i, col in enumerate(df.columns):
+        series = df[col]
+        if series.isnull().all():
+            continue
+        width = kwargs["width"][i]
+        if width < 0 or width > 1:
+            width = 0.8
+        adjusted_width = width / series_count  # 0.8
+        # far-left + margin + halfway through one grouped column
+        left = -0.5 + ((1 - width) / 2.0) + (adjusted_width / 2.0)
+        offset = left + (i * adjusted_width)
+        foreground = kwargs["color"][i]
+        axes.bar(
+            x=series.index + offset,
+            height=series,
+            color=foreground,
+            width=adjusted_width,
+            label=col if kwargs["label_series"][i] else "_not_in_legend_",
+        )
+        annotate_bars(
+            series,
+            offset,
+            np.zeros(len(series)),
+            axes,
+            foreground=foreground,
+            **anno_args,
+        )
+
+
+def stacked(axes, df: DataFrame, anno_args, **kwargs) -> None:
+    """
+    plot a stacked bar plot
+    """
+
+    series_count = len(df)
+    base_plus: np.ndarray[tuple[int, ...], np.dtype[np.float64]] = np.zeros(
+        shape=series_count, dtype=np.float64
+    )
+    base_minus: np.ndarray[tuple[int, ...], np.dtype[np.float64]] = np.zeros(
+        shape=series_count, dtype=np.float64
+    )
+    for i, col in enumerate(df.columns):
+        series = df[col]
+        base = np.where(series >= 0, base_plus, base_minus)
+        foreground = kwargs["color"][i]
+        axes.bar(
+            x=series.index,
+            height=series,
+            bottom=base,
+            color=foreground,
+            width=kwargs["width"][i],
+            label=col if kwargs["label_series"][i] else "_not_in_legend_",
+        )
+        annotate_bars(series, 0, base, axes, foreground=foreground, **anno_args)
+        base_plus += np.where(series >= 0, series, 0)
+        base_minus += np.where(series < 0, series, 0)
+
+
+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.
+        /* affects the entire bar plot */
+        - ax: Axes | None - The axes to plot on. If None, a new figure and axes will be created.
+        - stacked: bool - If True, the bars will be stacked. If False, they will be grouped.
+        - rotation: int | float - The rotation of the x-axis labels in degrees.
+        - max_ticks: int - The maximum number of ticks on the x-axis (for PeriodIndex only)
+        - plot_from: int | PeriodIndex | None - The starting point of the plot.
+          If None, the entire data will be plotted.
+        - legend: bool | dict | (str, object) | None - If True, a legend will be created.
+        /* affects the bars in the bar plot */
+        - color: str | Sequence[str] - The color of the bars. If a sequence is provided,
+          it should match the number of columns in the DataFrame.
+        - label_series: bool | Sequence[bool] - If True, the series will be labeled in
+          the legend. If a sequence is provided, it should match the number of columns
+          in the DataFrame.
+        /* options for bar annotations */
+        - annotate: None | bool - If True, the bars will be annotated with their values.
+        - fontsize: int | float | str - The font size of the annotations.
+        - fontname: str - The font name of the annotations.
+        - bar_rotation: int | float - The rotation of the bar labels in degrees.
+        - rounding: int | bool - The number of decimal places to round the annotations.
+          If True, a default between 0 and 2 is used.
+        - annotate_color: str - The color of the annotations.
+        - above: bool - If True, the annotations will be placed above the bars.
+
+    Note: This function does not assume all data is timeseries with a PeriodIndex,
+
+    Returns
+    - axes: Axes - The axes for the plot.
+    """
+
+    # --- 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)
+
+    # --- deal with complete PeriodIdex indicies
+    if not is_categorical(df):
+        print(
+            "Warning: bar_plot is not designed for incomplete or non-categorical data indexes."
+        )
+    saved_pi = map_periodindex(df)
+    if saved_pi is not None:
+        df = saved_pi[0]  # extract the reindexed DataFrame from the PeriodIndex
+
+    # --- set up the default arguments
+    bar_defaults: dict[str, Any] = {
+        "color": get_color_list(item_count),
+        "width": get_setting("bar_width"),
+        "label_series": (item_count > 1),
+    }
+    anno_args = {
+        ANNOTATE: kwargs.get(ANNOTATE, False),
+        FONTSIZE: kwargs.get(FONTSIZE, "small"),
+        FONTNAME: kwargs.get(FONTNAME, "Helvetica"),
+        BAR_ROTATION: kwargs.get(BAR_ROTATION, 0),
+        ROUNDING: kwargs.get(ROUNDING, True),
+        ANNO_COLOR: kwargs.get(ANNO_COLOR, "white"),
+        ABOVE: kwargs.get(ABOVE, False),
+    }
+    bar_args, remaining_kwargs = apply_defaults(item_count, bar_defaults, kwargs)
+    chart_defaults: dict[str, Any] = {
+        STACKED: False,
+        ROTATION: 90,
+        MAX_TICKS: 10,
+        LEGEND: item_count > 1,
+    }
+    chart_args = {k: kwargs.get(k, v) for k, v in chart_defaults.items()}
+
+    # --- plot the data
+    axes, _rkwargs = get_axes(**remaining_kwargs)
+    if chart_args["stacked"]:
+        stacked(axes, df, anno_args, **bar_args)
+    else:
+        grouped(axes, df, anno_args, **bar_args)
+
+    # --- handle complete periodIndex data and label rotation
+    rotate_labels = True
+    if saved_pi is not None:
+        set_labels(axes, saved_pi[1], chart_args["max_ticks"])
+        rotate_labels = False
+
+    if rotate_labels:
+        plt.xticks(rotation=chart_args["rotation"])
+
+    # --- add a legend if requested
+    if "LEGEND" in chart_args:
+        make_legend(axes, chart_args["LEGEND"])
+
+    return axes