MatplotLibAPI 3.2.21__py3-none-any.whl → 4.0.0__py3-none-any.whl

MatplotLibAPI/{Treemap.py → treemap.py}

@@ -1,18 +1,18 @@
 """Treemap plotting utilities."""
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
 import pandas as pd
 import plotly.graph_objects as go
 from pandas import BooleanDtype, CategoricalDtype
 
-from .StyleTemplate import (
-    TREEMAP_STYLE_TEMPLATE,
-    StyleTemplate,
-    percent_formatter,
-    string_formatter,
-    validate_dataframe,
-)
+from .style_template import TREEMAP_STYLE_TEMPLATE, StyleTemplate, validate_dataframe
+
+__all__ = [
+    "TREEMAP_STYLE_TEMPLATE",
+    "aplot_treemap",
+    "fplot_treemap",
+]
 
 
 def aplot_treemap(
@@ -25,43 +25,44 @@ def aplot_treemap(
     sort_by: Optional[str] = None,
     ascending: bool = False,
     max_values: int = 100,
-) -> go.Trace:
-    """Create a treemap trace from the data frame.
+    **kwargs: Any,
+) -> go.Treemap:
+    """Create a treemap trace from the provided dataframe.
 
     Parameters
     ----------
     pd_df : pd.DataFrame
         DataFrame containing the data to plot.
     path : str
-        Column representing hierarchical path.
+        Column representing the hierarchical path.
     values : str
         Column containing values for each treemap block.
     style : StyleTemplate, optional
         Style configuration. The default is `TREEMAP_STYLE_TEMPLATE`.
     title : str, optional
-        Plot title.
+        Plot title. The default is None.
     color : str, optional
-        Column used for coloring.
+        Column used for coloring. The default is None.
     sort_by : str, optional
-        Column used to sort data.
+        Column used to sort data. The default is None.
     ascending : bool, optional
-        Sort order for the data. The default is `False`.
+        Sort order for the data. The default is False.
     max_values : int, optional
         Maximum number of rows to plot. The default is 100.
 
     Returns
     -------
-    go.Trace
+    go.Treemap
         Plotly treemap trace.
     """
     cols = [path, values]
     if color:
         cols.append(color)
     validate_dataframe(pd_df, cols=cols, sort_by=sort_by)
-    if not sort_by:
-        sort_by = values
-    df = pd_df.sort_values(by=sort_by, ascending=ascending)[cols].head(max_values)
-    data = {
+
+    sort_col = sort_by or values
+    df = pd_df.sort_values(by=sort_col, ascending=ascending)[cols].head(max_values)
+    data: Dict[str, Any] = {
         "labels": df[path],
         "parents": [""] * len(df),
         "values": df[values],
@@ -74,22 +75,17 @@ def aplot_treemap(
         },
     }
 
-    if color and color in pd_df.columns:
-        color_data = pd_df[color]
+    if color and color in df.columns:
+        color_data = cast(pd.Series, df[color])
         if isinstance(
             color_data.dtype, CategoricalDtype
         ) or pd.api.types.is_object_dtype(color_data.dtype):
             color_data = color_data.astype("category").cat.codes
         elif isinstance(color_data.dtype, BooleanDtype):
             color_data = color_data.astype(int)
-        data["marker"] = dict(colorscale="Viridis", colors=color_data.to_list())
-
-    g = go.Treemap(
-        data,
-        root_color=style.background_color,
-    )
+        data["marker"] = dict(colorscale="Viridis", colors=color_data.tolist())
 
-    return g  # type: ignore
+    return go.Treemap(data, root_color=style.background_color)
 
 
 def fplot_treemap(
@@ -103,40 +99,42 @@ def fplot_treemap(
     ascending: bool = False,
     max_values: int = 100,
     fig: Optional[go.Figure] = None,
-    save_path: Optional[str] = None,
-    savefig_kwargs: Optional[Dict[str, Any]] = None,
 ) -> go.Figure:
-    """Return a figure containing the treemap plot.
+    """Return a figure containing a treemap plot.
 
     Parameters
     ----------
     pd_df : pd.DataFrame
         DataFrame containing the data to plot.
     path : str
-        Column representing hierarchical path.
+        Column representing the hierarchical path.
     values : str
         Column containing values for each treemap block.
     style : StyleTemplate, optional
         Style configuration. The default is `TREEMAP_STYLE_TEMPLATE`.
     title : str, optional
-        Plot title.
+        Plot title. The default is None.
     color : str, optional
-        Column used for coloring.
+        Column used for coloring. The default is None.
     sort_by : str, optional
-        Column used to sort data.
+        Column used to sort data. The default is None.
     ascending : bool, optional
-        Sort order for the data. The default is `False`.
+        Sort order for the data. The default is False.
     max_values : int, optional
         Maximum number of rows to plot. The default is 100.
     fig : go.Figure, optional
-        Existing figure to add the treemap to.
+        Existing figure to add the treemap to. If None, create a new figure.
+    save_path : str, optional
+        Path to save the figure as HTML or static image. The default is None.
+    savefig_kwargs : dict[str, Any], optional
+        Extra keyword arguments passed to Plotly save methods.
 
     Returns
     -------
     go.Figure
         Figure containing the treemap plot.
     """
-    g = aplot_treemap(
+    treemap_trace = aplot_treemap(
         pd_df=pd_df,
         path=path,
         values=values,
@@ -148,25 +146,15 @@ def fplot_treemap(
         max_values=max_values,
     )
 
-    if not fig:
-        fig = go.Figure(g)
-    else:
-        fig.add_trace(g)
+    figure = go.Figure(treemap_trace) if fig is None else fig
+    if fig is not None:
+        figure.add_trace(treemap_trace)
 
-    fig.update_layout(
+    figure.update_layout(
         title=title,
         plot_bgcolor=style.background_color,
         paper_bgcolor=style.background_color,
         font=dict(family=style.font_name, size=style.font_size, color=style.font_color),
-        showlegend=style.legend if style else True,
+        showlegend=style.legend,
     )
-
-    # Apply color scale
-    fig.update_traces(marker=dict(colorscale=style.palette))
-
-    if save_path:
-        if save_path.lower().endswith((".html", ".htm")):
-            fig.write_html(save_path, **(savefig_kwargs or {}))
-        else:
-            fig.write_image(save_path, **(savefig_kwargs or {}))
-    return fig
+    return figure

MatplotLibAPI/typing.py

@@ -0,0 +1,12 @@
+"""Internal type aliases used across MatplotLibAPI."""
+
+from typing import Callable, Literal, Sequence, Union
+
+from typing_extensions import TypeAlias
+
+# ``DataFrame.corr`` supports the three built-in correlation methods or a callable
+# that operates on two array-like inputs and returns a float.
+CorrelationMethod: TypeAlias = Union[
+    Literal["pearson", "kendall", "spearman"],
+    Callable[[Sequence[float], Sequence[float]], float],
+]

MatplotLibAPI/{_visualization_utils.py → utils.py}

@@ -8,6 +8,8 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from typing_extensions import Protocol
 
+from .style_template import StyleTemplate
+
 
 class _AplotFunc(Protocol):
     def __call__(self, *, pd_df: Any, ax: Axes, **kwargs: Any) -> Axes: ...
@@ -22,9 +24,8 @@ def _wrap_aplot(
     plot_func: _AplotFunc,
     pd_df: Any,
     figsize: Tuple[float, float],
+    style: StyleTemplate,
     ax_args: Optional[Dict[str, Any]] = None,
-    save_path: Optional[str] = None,
-    savefig_kwargs: Optional[Dict[str, Any]] = None,
     **kwargs: Any,
 ) -> Figure:
     """Create a new figure and delegate plotting to an axis-level function.
@@ -39,30 +40,23 @@ def _wrap_aplot(
         Size of the created figure.
     ax_args : dict, optional
         Additional keyword arguments forwarded to ``plt.subplots``.
-    save_path : str, optional
-        File path where the figure should be saved. The default is ``None``
-        and no file is written.
-    savefig_kwargs : dict, optional
-        Extra keyword arguments forwarded to ``Figure.savefig`` when
-        ``save_path`` is provided. Defaults to ``None``.
     **kwargs : Any
         Additional arguments forwarded to ``plot_func``.
 
     Returns
     -------
     Figure
-        Figure containing the rendered plot. If ``save_path`` is supplied the
-        figure is saved before being returned.
+        Figure containing the rendered plot.
     """
     ax_args = ax_args or {}
     fig, axes_obj = plt.subplots(figsize=figsize, **ax_args)
+    fig_obj: Figure = cast(Figure, fig)
+    fig_obj.patch.set_facecolor(style.background_color)
     ax: Axes
     if isinstance(axes_obj, Axes):
         ax = axes_obj
     else:
         ax = cast(Axes, axes_obj.flat[0] if isinstance(axes_obj, ndarray) else axes_obj)
     plot_func(pd_df=pd_df, ax=ax, **kwargs)
-    fig_obj: Figure = cast(Figure, fig)
-    if save_path:
-        fig_obj.savefig(save_path, **(savefig_kwargs or {}))
+
     return fig_obj

MatplotLibAPI/waffle.py

@@ -0,0 +1,173 @@
+"""Waffle chart helpers."""
+
+from typing import Any, Optional, Tuple, cast
+
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from matplotlib.patches import Rectangle
+
+from .base_plot import BasePlot
+
+from .style_template import PIE_STYLE_TEMPLATE, StyleTemplate, validate_dataframe
+from .utils import _get_axis
+
+
+class WaffleChart(BasePlot):
+    """Plot waffle charts from categorical proportions.
+
+    Methods
+    -------
+    aplot
+        Plot a waffle chart on an existing Matplotlib axes.
+    fplot
+        Plot a waffle chart on a new Matplotlib figure.
+    """
+
+    def __init__(self, pd_df: pd.DataFrame, category: str, value: str):
+        validate_dataframe(pd_df, cols=[category, value])
+        super().__init__(pd_df=pd_df)
+        self.category = category
+        self.value = value
+
+    def aplot(
+        self,
+        rows: int = 10,
+        title: Optional[str] = None,
+        style: StyleTemplate = PIE_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot a waffle chart on the provided axis.
+
+        Parameters
+        ----------
+        rows : int, optional
+            Number of rows and columns in the waffle grid. The default is 10.
+        title : str, optional
+            Title for the plot. The default is None.
+        style : StyleTemplate, optional
+            Style template for the plot. The default is PIE_STYLE_TEMPLATE.
+        ax : Axes, optional
+            Matplotlib axes to plot on. If None, use the current axes.
+        **kwargs : Any
+            Additional keyword arguments reserved for compatibility.
+
+        Returns
+        -------
+        Axes
+            The Matplotlib axes containing the waffle chart.
+        """
+        value_series = cast(pd.Series, self._obj[self.value])
+        category_series = cast(pd.Series, self._obj[self.category])
+        total = float(value_series.sum())
+        squares = rows * rows
+        colors = sns.color_palette(style.palette, n_colors=len(self._obj))
+        plot_ax = _get_axis(ax)
+        plot_ax.set_aspect("equal")
+
+        start = 0
+        for idx, (label, val) in enumerate(zip(category_series, value_series)):
+            count = int(round((val / total) * squares))
+            for square in range(start, min(start + count, squares)):
+                row = square // rows
+                col = square % rows
+                plot_ax.add_patch(
+                    Rectangle(
+                        (col, rows - row),
+                        1,
+                        1,
+                        facecolor=colors[idx],
+                        edgecolor=style.background_color,
+                    )
+                )
+            start += count
+
+        plot_ax.set_xlim(0, rows)
+        plot_ax.set_ylim(0, rows + 1)
+        plot_ax.axis("off")
+        if title:
+            plot_ax.set_title(title)
+        legend_handles = [Rectangle((0, 0), 1, 1, color=color) for color in colors]
+        plot_ax.legend(
+            legend_handles, category_series, loc="upper center", ncol=3, frameon=False
+        )
+        return plot_ax
+
+    def fplot(
+        self,
+        rows: int = 10,
+        title: Optional[str] = None,
+        style: StyleTemplate = PIE_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (8, 8),
+    ) -> Figure:
+        """Plot a waffle chart on a new figure.
+
+        Parameters
+        ----------
+        rows : int, optional
+            Number of rows and columns in the waffle grid. The default is 10.
+        title : str, optional
+            Title for the plot. The default is None.
+        style : StyleTemplate, optional
+            Style template for the plot. The default is PIE_STYLE_TEMPLATE.
+        figsize : tuple[float, float], optional
+            Figure size. The default is (8, 8).
+
+        Returns
+        -------
+        Figure
+            The Matplotlib figure containing the waffle chart.
+        """
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = Axes(fig=fig, facecolor=style.background_color)
+        self.aplot(
+            title=title,
+            style=style,
+            rows=rows,
+            ax=ax,
+        )
+        return fig
+
+
+def aplot_waffle(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    rows: int = 10,
+    title: Optional[str] = None,
+    style: StyleTemplate = PIE_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot a waffle chart on the provided axis."""
+    return WaffleChart(pd_df=pd_df, category=category, value=value).aplot(
+        title=title,
+        style=style,
+        rows=rows,
+        ax=ax,
+    )
+
+
+def fplot_waffle(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    rows: int = 10,
+    title: Optional[str] = None,
+    style: StyleTemplate = PIE_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (8, 8),
+) -> Figure:
+    """Plot waffle charts on a new figure."""
+    return WaffleChart(pd_df=pd_df, category=category, value=value).fplot(
+        title=title,
+        style=style,
+        rows=rows,
+        figsize=figsize,
+    )