openretailscience 0.45.0__py3-none-any.whl

openretailscience/plots/styles/styling_helpers.py

@@ -0,0 +1,155 @@
+"""PlotStyler class that applies styling using the options system."""
+
+from matplotlib.axes import Axes
+from matplotlib.text import Text
+
+from openretailscience.options import PlotStyleHelper
+from openretailscience.plots.styles.font_utils import get_font_properties
+
+
+class PlotStyler:
+    """Helper class for applying all styling using the options system."""
+
+    def __init__(self) -> None:
+        """Initialize the PlotStyler."""
+        self._style = PlotStyleHelper()
+
+    def apply_base_styling(self, ax: Axes) -> None:
+        """Apply base plot styling (spines, grid, background) using options."""
+        ax.set_facecolor(self._style.background_color)
+        ax.set_axisbelow(True)
+
+        # Configure spines based on options
+        ax.spines["top"].set_visible(self._style.show_top_spine)
+        ax.spines["right"].set_visible(self._style.show_right_spine)
+        ax.spines["bottom"].set_visible(self._style.show_bottom_spine)
+        ax.spines["left"].set_visible(self._style.show_left_spine)
+
+        # Configure grid based on options
+        ax.grid(which="major", axis="x", color=self._style.grid_color, alpha=self._style.grid_alpha, zorder=1)
+        ax.grid(which="major", axis="y", color=self._style.grid_color, alpha=self._style.grid_alpha, zorder=1)
+
+    def apply_title(self, ax: Axes, title: str, pad: int | None = None) -> None:
+        """Apply title styling using options."""
+        effective_pad = pad if pad is not None else self._style.title_pad
+
+        ax.set_title(
+            title,
+            fontproperties=get_font_properties(self._style.title_font),
+            fontsize=self._style.title_size,
+            pad=effective_pad,
+        )
+
+    def apply_label(self, ax: Axes, label: str, axis: str, pad: int | None = None) -> None:
+        """Apply axis label styling using options."""
+        # Use appropriate default padding based on axis
+        if pad is None:
+            pad = self._style.x_label_pad if axis == "x" else self._style.y_label_pad
+
+        font_props = get_font_properties(self._style.label_font)
+
+        axis_fn = ax.set_xlabel if axis == "x" else ax.set_ylabel
+        axis_fn(label, fontproperties=font_props, fontsize=self._style.label_size, labelpad=pad)
+
+    def apply_ticks(self, ax: Axes) -> None:
+        """Apply tick styling using options."""
+        ax.tick_params(axis="both", which="both", labelsize=self._style.tick_size)
+
+        tick_font_props = get_font_properties(self._style.tick_font)
+        for tick in [
+            *ax.xaxis.get_major_ticks(),
+            *ax.xaxis.get_minor_ticks(),
+            *ax.yaxis.get_major_ticks(),
+            *ax.yaxis.get_minor_ticks(),
+        ]:
+            tick.label1.set_fontproperties(tick_font_props)
+            tick.label2.set_fontproperties(tick_font_props)
+
+    def apply_source_text(
+        self,
+        ax: Axes,
+        text: str,
+        font_size: float | None = None,
+        vertical_padding: float = 2,
+        is_venn_diagram: bool = False,
+        **kwargs: object,
+    ) -> Text:
+        """Apply source text styling using options.
+
+        Args:
+            ax (Axes): The graph to add the source text to.
+            text (str): The source text.
+            font_size (float, optional): The font size of the source text. If None, uses options default.
+            vertical_padding (float, optional): The padding in ems below the x-axis label. Defaults to 2.
+            is_venn_diagram (bool, optional): Flag to indicate if the diagram is a Venn diagram.
+                If True, `x_norm` and `y_norm` will be set to fixed values. Defaults to False.
+            **kwargs: Additional keyword arguments for positioning (x, y coordinates)
+
+        Returns:
+            Text: The source text object.
+        """
+        effective_font_size = font_size or self._style.source_size
+
+        # Calculate position if not provided in kwargs
+        if "x" not in kwargs or "y" not in kwargs:
+            ax.figure.canvas.draw()
+
+            if is_venn_diagram:
+                x_norm, y_norm = 0.01, 0.02
+            else:
+                # Get y coordinate of the text
+                xlabel_box = ax.xaxis.label.get_window_extent(renderer=ax.figure.canvas.get_renderer())
+
+                top_of_label_px = xlabel_box.y0
+                padding_px = vertical_padding * effective_font_size
+                y_disp = top_of_label_px - padding_px - (xlabel_box.height)
+
+                # Convert display coordinates to normalized figure coordinates
+                y_norm = y_disp / ax.figure.bbox.height
+
+                # Get x coordinate of the text
+                ylabel_box = ax.yaxis.label.get_window_extent(renderer=ax.figure.canvas.get_renderer())
+                title_box = ax.title.get_window_extent(renderer=ax.figure.canvas.get_renderer())
+                min_x0 = min(ylabel_box.x0, title_box.x0)
+                x_norm = ax.figure.transFigure.inverted().transform((min_x0, 0))[0]
+
+            # Use calculated positions if not provided
+            x_pos = kwargs.get("x", x_norm)
+            y_pos = kwargs.get("y", y_norm)
+        else:
+            x_pos = kwargs.get("x", 0.01)
+            y_pos = kwargs.get("y", 0.02)
+
+        return ax.figure.text(
+            x_pos,
+            y_pos,
+            text,
+            ha="left",
+            va="bottom",
+            transform=ax.figure.transFigure,
+            fontsize=effective_font_size,
+            fontproperties=get_font_properties(self._style.source_font),
+            color="dimgray",
+        )
+
+    def apply_legend(self, ax: Axes, title: str | None = None, outside: bool = False) -> None:
+        """Apply legend styling using options."""
+        if outside:
+            legend = ax.legend(
+                bbox_to_anchor=self._style.legend_bbox_to_anchor,
+                loc=self._style.legend_loc,
+                frameon=False,
+            )
+        else:
+            legend = ax.legend(frameon=False)
+
+        if title:
+            legend.set_title(title)
+            legend.get_title().set_fontproperties(get_font_properties(self._style.label_font))
+            legend.get_title().set_fontsize(self._style.label_size)
+
+        # Apply styling to legend text
+        legend_font_props = get_font_properties(self._style.label_font)
+        for text in legend.get_texts():
+            text.set_fontproperties(legend_font_props)
+            text.set_fontsize(self._style.label_size - 1)

openretailscience/plots/time.py

@@ -0,0 +1,160 @@
+"""This module provides functionality for creating timeline plots.
+
+Which are essential for visualizing transactional data over time.
+By aggregating data by specified periods (e.g., daily, weekly, monthly), timeline plots help to identify
+trends, seasonal patterns, and performance variations across different timeframes. These plots are valuable tools for
+retail analysis, sales tracking, and customer behavior insights.
+
+### Features
+
+- **Timeline Plot Creation**: Plot a value column (e.g., sales, transactions) over time,
+  aggregated by a specific period (e.g., daily, weekly).
+- **Customizable Aggregation**: Supports different aggregation functions (e.g., sum, average)
+  to compute the value column's metrics.
+- **Grouping by Categories**: Optionally group data by a specific category (e.g., product,
+  region, store) and compare performance over time.
+- **Time Period Handling**: The `period` parameter allows data aggregation by different time
+  periods, such as days, weeks, or months.
+- **Graph Styling**: Customize the appearance of the plot with options to adjust titles, axis
+  labels, legend placement, and more.
+- **Color Mapping**: Use linear color gradients for category-based groupings to visually
+  differentiate between groups in the timeline.
+
+### Use Cases
+
+- **Sales and Revenue Analysis**: Track sales performance over time, either as a total or by
+  group (e.g., product category or store).
+- **Seasonal Trend Analysis**: Visualize how sales or transaction values fluctuate across
+  different periods, helping to identify seasonal trends or promotional impacts.
+- **Customer Behavior Tracking**: Examine changes in customer behavior (e.g., purchase
+  frequency, average transaction value) over time.
+- **Comparative Performance**: Compare multiple categories (e.g., different products or regions)
+  on the same timeline to evaluate relative performance.
+
+### Limitations and Handling of Data
+
+- **Time Period Grouping**: Data is aggregated by a time period defined by the `period`
+  argument, which can be adjusted to daily, weekly, monthly, etc.
+- **Grouping by Categories**: If `group_col` is specified, the plot will display performance
+  across different categories, with color differentiation for each group.
+- **Flexible Aggregation**: The aggregation function (e.g., sum, average) can be customized to
+  calculate the desired value for each period.
+
+### Functionality Details
+
+- **plot()**: Generates a timeline plot of a specified value column over time, with
+  customization options for grouping, aggregation, and styling.
+- **Helper functions**: Utilizes utility functions from the `openretailscience` package to handle
+  styling, formatting, and other plot adjustments.
+"""
+
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes, SubplotBase
+from pandas.tseries.offsets import BaseOffset
+
+import openretailscience.plots.styles.graph_utils as gu
+from openretailscience.options import get_option
+from openretailscience.plots.styles.colors import get_linear_cmap, get_named_color
+
+
+def plot(
+    df: pd.DataFrame,
+    value_col: str,
+    period: str | BaseOffset = "D",
+    agg_func: str = "sum",
+    group_col: str | None = None,
+    title: str | None = None,
+    x_label: str | None = None,
+    y_label: str | None = None,
+    legend_title: str | None = None,
+    ax: Axes | None = None,
+    source_text: str | None = None,
+    move_legend_outside: bool = False,
+    **kwargs: dict[str, any],
+) -> SubplotBase:
+    """Plots the value_col over time.
+
+    Timeline plots are a fundamental tool for interpreting transactional data within a temporal context. By presenting
+    data in a chronological sequence, these visualizations reveal patterns and trends that might otherwise remain hidden
+    in raw numbers, making them essential for both historical analysis and forward-looking insights. They are
+    particularly useful for:
+
+    - Tracking sales performance across different periods (e.g., daily, weekly, monthly)
+    - Identifying seasonal patterns or promotional impacts on sales
+    - Comparing the performance of different product categories or store locations over time
+    - Visualizing customer behavior trends, such as purchase frequency or average transaction value
+
+    Args:
+        df (pd.DataFrame): The dataframe to plot.
+        value_col (str): The column to plot.
+        period (str | BaseOffset): The period to group the data by.
+        agg_func (str, optional): The aggregation function to apply to the value_col. Defaults to "sum".
+        group_col (str, optional): The column to group the data by. Defaults to None.
+        title (str, optional): The title of the plot. Defaults to None. When None the title is set to
+            `f"{value_col.title()} by {group_col.title()}"`
+        x_label (str, optional): The x-axis label. Defaults to None. When None the x-axis label is set to blank
+        y_label (str, optional): The y-axis label. Defaults to None. When None the y-axis label is set to the title
+            case of `value_col`
+        legend_title (str, optional): The title of the legend. Defaults to None. When None the legend title is set to
+            the title case of `group_col`
+        ax (Axes, optional): The matplotlib axes object to plot on. Defaults to None.
+        source_text (str, optional): The source text to add to the plot. Defaults to None.
+        move_legend_outside (bool, optional): Whether to move the legend outside the plot. Defaults to True.
+        **kwargs: Additional keyword arguments to pass to the Pandas plot function.
+
+    Returns:
+        SubplotBase: The matplotlib axes object.
+    """
+    df["transaction_period"] = df[get_option("column.transaction_date")].dt.to_period(
+        period,
+    )
+
+    if group_col is None:
+        default_colors = get_named_color("primary")
+        df = df.groupby("transaction_period")[value_col].agg(agg_func)
+        default_title = "Total Sales"
+        show_legend = False
+    else:
+        default_colors = get_linear_cmap("green")(
+            np.linspace(0, 1, df[group_col].nunique()),
+        )
+        df = (
+            df.groupby([group_col, "transaction_period"])[value_col]
+            .agg(agg_func)
+            .reset_index()
+            .pivot(index="transaction_period", columns=group_col, values=value_col)
+        )
+        default_title = f"{value_col.title()} by {group_col.title()}"
+        show_legend = True
+
+    linewidth = kwargs.pop("linewidth", 3)
+    color = kwargs.pop("color", default_colors)
+    ax = df.plot(
+        linewidth=linewidth,
+        color=color,
+        legend=show_legend,
+        ax=ax,
+        **kwargs,
+    )
+    ax = gu.standard_graph_styles(
+        ax,
+        title=gu.not_none(title, default_title),
+        x_label=gu.not_none(x_label, ""),
+        y_label=gu.not_none(y_label, value_col.title()),
+        legend_title=legend_title,
+        move_legend_outside=move_legend_outside,
+        show_legend=show_legend,
+    )
+
+    decimals = gu.get_decimals(ax.get_ylim(), ax.get_yticks())
+    ax.yaxis.set_major_formatter(
+        lambda x, pos: gu.human_format(x, pos, decimals=decimals),
+    )
+
+    if source_text is not None:
+        gu.add_source_text(ax=ax, source_text=source_text)
+
+    gu.standard_tick_styles(ax)
+
+    return ax