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

MatplotLibAPI/pie.py

@@ -0,0 +1,154 @@
+"""Pie and donut chart helpers."""
+
+from typing import Any, Dict, Optional, Tuple
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .base_plot import BasePlot
+
+from .style_template import PIE_STYLE_TEMPLATE, StyleTemplate, validate_dataframe
+from .utils import _get_axis
+
+__all__ = ["PIE_STYLE_TEMPLATE", "aplot_pie", "fplot_pie"]
+
+
+class PieChart(BasePlot):
+    """Plot pie and donut charts from categorical aggregates.
+
+    Methods
+    -------
+    aplot
+        Plot a pie or donut chart on an existing Matplotlib axes.
+    fplot
+        Plot a pie or donut 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,
+        donut: bool = False,
+        title: Optional[str] = None,
+        style: StyleTemplate = PIE_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot a pie or donut chart on the provided axis.
+
+        Parameters
+        ----------
+        donut : bool, optional
+            If True, render a donut chart. The default is False.
+        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 pie or donut chart.
+        """
+        labels = self._obj[self.category].astype(str).tolist()
+        sizes = self._obj[self.value]
+        plot_ax = _get_axis(ax)
+        wedgeprops: Optional[Dict[str, Any]] = None
+        if donut:
+            wedgeprops = {"width": 0.3}
+        plot_ax.pie(
+            sizes,
+            labels=labels,
+            autopct="%1.1f%%",
+            colors=sns.color_palette(style.palette),
+            wedgeprops=wedgeprops,
+            textprops={"color": style.font_color, "fontsize": style.font_size},
+        )
+        plot_ax.axis("equal")
+        if title:
+            plot_ax.set_title(title)
+        return plot_ax
+
+    def fplot(
+        self,
+        donut: bool = False,
+        title: Optional[str] = None,
+        style: StyleTemplate = PIE_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (8, 8),
+    ) -> Figure:
+        """Plot a pie or donut chart on a new figure.
+
+        Parameters
+        ----------
+        donut : bool, optional
+            If True, render a donut chart. The default is False.
+        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 pie or donut chart.
+        """
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = Axes(fig=fig, facecolor=style.background_color)
+        fig.set_facecolor(style.background_color)
+        self.aplot(donut=donut, title=title, style=style, ax=ax)
+        return fig
+
+
+def aplot_pie(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    donut: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = PIE_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot pie or donut charts for categorical share visualization."""
+    return PieChart(pd_df=pd_df, category=category, value=value).aplot(
+        donut=donut,
+        title=title,
+        style=style,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def fplot_pie(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    donut: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = PIE_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (8, 8),
+) -> Figure:
+    """Plot pie or donut charts on a new figure."""
+    return PieChart(pd_df=pd_df, category=category, value=value).fplot(
+        donut=donut,
+        title=title,
+        style=style,
+        figsize=figsize,
+    )

MatplotLibAPI/pivot.py

@@ -0,0 +1,274 @@
+"""Pivot chart helpers for bar and line plots."""
+
+from typing import Any, Optional, Tuple, cast
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .base_plot import BasePlot
+
+
+from .style_template import (
+    FIG_SIZE,
+    PIVOTBARS_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+
+__all__ = ["PIVOTBARS_STYLE_TEMPLATE", "aplot_pivoted_bars"]
+
+
+def _pivot_and_sort_data(
+    data: pd.DataFrame,
+    index: str,
+    columns: str,
+    values: str,
+    aggfunc: str = "sum",
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+) -> pd.DataFrame:
+    """Pivot and sort a DataFrame.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        The input DataFrame.
+    index : str
+        The column to use as the pivot table index.
+    columns : str
+        The column to use for pivot table columns.
+    values : str
+        The column to aggregate.
+    aggfunc : str, optional
+        The aggregation function, by default "sum".
+    sort_by : str, optional
+        The column to sort by.
+    ascending : bool, optional
+        The sort order, by default `False`.
+
+    Returns
+    -------
+    pd.DataFrame
+        A pivoted and sorted DataFrame.
+    """
+    pivot_df = pd.pivot_table(
+        data, values=values, index=[index], columns=[columns], aggfunc=aggfunc  # type: ignore
+    )  # type: ignore
+    if sort_by:
+        pivot_df = pivot_df.sort_values(by=sort_by, ascending=ascending)
+    return pivot_df.reset_index()
+
+
+class PivotBarChart(BasePlot):
+    """Class for plotting bar charts from pivoted data."""
+
+    def __init__(
+        self,
+        pd_df: pd.DataFrame,
+        label: str,
+        x: str,
+        y: str,
+        agg: str = "sum",
+        stacked: bool = False,
+    ):
+        cols = [label, x, y]
+        validate_dataframe(pd_df, cols=cols)
+        super().__init__(pd_df=pd_df)
+        self.label = label
+        self.x = x
+        self.y = y
+        self.agg = agg
+        self.stacked = stacked
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = PIVOTBARS_STYLE_TEMPLATE,
+        sort_by: Optional[str] = None,
+        ascending: bool = False,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        pivot_df = _pivot_and_sort_data(
+            self._obj,
+            index=self.x,
+            columns=self.label,
+            values=self.y,
+            aggfunc=self.agg,
+            sort_by=sort_by,
+            ascending=ascending,
+        )
+
+        if ax is None:
+            ax = cast(Axes, plt.gca())
+
+        if pd.api.types.is_datetime64_any_dtype(pivot_df[self.x]):
+            pivot_df[self.x] = pivot_df[self.x].dt.strftime("%Y-%m-%d")
+
+        pivot_df.plot(kind="bar", x=self.x, stacked=self.stacked, ax=ax, alpha=0.7)
+
+        ax.set_ylabel(string_formatter(self.y))
+        ax.set_xlabel(string_formatter(self.x))
+        if title:
+            ax.set_title(title)
+
+        ax.legend(
+            fontsize=style.font_size - 2,
+            title_fontsize=style.font_size + 2,
+            labelcolor="linecolor",
+            facecolor=style.background_color,
+        )
+        ax.tick_params(axis="x", rotation=90)
+        return ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = PIVOTBARS_STYLE_TEMPLATE,
+        sort_by: Optional[str] = None,
+        ascending: bool = False,
+        ax: Optional[Axes] = None,
+        figsize: Tuple[float, float] = FIG_SIZE,
+        **kwargs: Any,
+    ) -> Figure:
+
+        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, sort_by=sort_by, ascending=ascending, ax=ax
+        )
+        return fig
+
+
+def aplot_pivoted_bars(
+    data: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    agg: str = "sum",
+    style: StyleTemplate = PIVOTBARS_STYLE_TEMPLATE,
+    title: Optional[str] = None,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    ax: Optional[Axes] = None,
+    stacked: bool = False,
+    **kwargs,
+) -> Axes:
+    """Plot a bar chart from a pivot table.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        The DataFrame containing the data to plot.
+    label : str
+        The column to pivot into series.
+    x : str
+        The column for the x-axis.
+    y : str
+        The column for the y-values.
+    agg : str, optional
+        The aggregation function for the pivot. The default is "sum".
+    style : StyleTemplate, optional
+        The style configuration. The default is `PIVOTBARS_STYLE_TEMPLATE`.
+    title : str, optional
+        The plot title.
+    sort_by : str, optional
+        The column to sort by.
+    ascending : bool, optional
+        The sort order. The default is `False`.
+    ax : Axes, optional
+        The axes to draw on.
+    stacked : bool, optional
+        Whether to stack the bars. The default is `False`.
+
+    Returns
+    -------
+    Axes
+        The matplotlib axes with the bar chart.
+    """
+    return PivotBarChart(
+        pd_df=data,
+        label=label,
+        x=x,
+        y=y,
+        agg=agg,
+        stacked=stacked,
+    ).aplot(
+        title=title,
+        style=style,
+        sort_by=sort_by,
+        ascending=ascending,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def fplot_pivoted_bars(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    agg: str = "sum",
+    style: StyleTemplate = PIVOTBARS_STYLE_TEMPLATE,
+    title: Optional[str] = None,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    ax: Optional[Axes] = None,
+    stacked: bool = False,
+    figsize: Tuple[float, float] = FIG_SIZE,
+) -> Figure:
+    """Plot a bar chart from a pivot table.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        The DataFrame containing the data to plot.
+    label : str
+        The column to pivot into series.
+    x : str
+        The column for the x-axis.
+    y : str
+        The column for the y-values.
+    agg : str, optional
+        The aggregation function for the pivot. The default is "sum".
+    style : StyleTemplate, optional
+        The style configuration. The default is `PIVOTBARS_STYLE_TEMPLATE`.
+    title : str, optional
+        The plot title.
+    sort_by : str, optional
+        The column to sort by.
+    ascending : bool, optional
+        The sort order. The default is `False`.
+    ax : Axes, optional
+        The axes to draw on.
+    stacked : bool, optional
+        Whether to stack the bars. The default is `False`.
+
+    Returns
+    -------
+    Figure
+        The matplotlib figure with the bar chart.
+    """
+    return PivotBarChart(
+        pd_df=pd_df,
+        label=label,
+        x=x,
+        y=y,
+        agg=agg,
+        stacked=stacked,
+    ).fplot(
+        title=title,
+        style=style,
+        sort_by=sort_by,
+        ascending=ascending,
+        ax=ax,
+        figsize=figsize,
+    )

MatplotLibAPI/sankey.py

@@ -0,0 +1,99 @@
+"""Sankey plotting helpers."""
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, cast
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from .style_template import SANKEY_STYLE_TEMPLATE, StyleTemplate, validate_dataframe
+
+__all__ = ["SANKEY_STYLE_TEMPLATE", "fplot_sankey"]
+
+
+@dataclass
+class SankeyNode:
+    label: List[str]
+
+
+@dataclass
+class SankeyLink:
+    source: List[int]
+    target: List[int]
+    value: List[float]
+
+    def __post_init__(self) -> None:
+        """Validate that all lists have the same length."""
+        if not (len(self.source) == len(self.target) == len(self.value)):
+            raise ValueError(
+                f"All lists must have the same length. "
+                f"Got source={len(self.source)}, target={len(self.target)}, value={len(self.value)}"
+            )
+
+
+@dataclass
+class SankeyData:
+    node: SankeyNode
+    link: SankeyLink
+
+    @staticmethod
+    def from_pandas_edgelist(
+        edges_df: pd.DataFrame,
+        source: str = "source",
+        target: str = "target",
+        edge_weight_col: str = "weight",
+    ) -> "SankeyData":
+        """Create SankeyData from a DataFrame."""
+        validate_dataframe(edges_df, cols=[source, target, edge_weight_col])
+        source_series = cast(pd.Series, edges_df[source])
+        target_series = cast(pd.Series, edges_df[target])
+        labels: List[str] = list(pd.unique(pd.concat([source_series, target_series])))
+        label_to_index: Dict[str, int] = {name: idx for idx, name in enumerate(labels)}
+
+        return SankeyData(
+            node=SankeyNode(label=labels),
+            link=SankeyLink(
+                source=[label_to_index[val] for val in edges_df[source]],
+                target=[label_to_index[val] for val in edges_df[target]],
+                value=edges_df[edge_weight_col].tolist(),
+            ),
+        )
+
+    def fplot(
+        self, title: Optional[str] = None, style: StyleTemplate = SANKEY_STYLE_TEMPLATE
+    ) -> go.Figure:
+        """Plot the Sankey diagram using Plotly."""
+        sankey = go.Sankey(
+            node=dict(
+                label=self.node.label,
+                pad=15,
+                thickness=20,
+                color=style.font_color,
+            ),
+            link=dict(
+                source=self.link.source,
+                target=self.link.target,
+                value=self.link.value,
+            ),
+        )
+
+        fig = go.Figure(sankey)
+        if title:
+            fig.update_layout(
+                title_text=title,
+                font=dict(color=style.font_color, size=style.font_size),
+            )
+        return fig
+
+
+def fplot_sankey(
+    pd_df: pd.DataFrame,
+    source: str,
+    target: str,
+    value: str,
+    title: Optional[str] = None,
+    style: StyleTemplate = SANKEY_STYLE_TEMPLATE,
+) -> go.Figure:
+    """Plot a Sankey diagram showing flows between categories."""
+    sankey_data = SankeyData.from_pandas_edgelist(pd_df, source, target, value)
+    return sankey_data.fplot(title=title, style=style)

MatplotLibAPI/{StyleTemplate.py → style_template.py}

@@ -1,5 +1,6 @@
 """Common style utilities and formatters for plotting."""
 
+import math
 from dataclasses import dataclass
 from typing import Callable, Dict, List, Optional, Union, cast
 
@@ -90,10 +91,11 @@ def format_func(
 # region Style Constants
 
 FIG_SIZE = (19.2, 10.8)
-BACKGROUND_COLOR = "black"
-TEXT_COLOR = "white"
-PALETTE = "Greys_r"
+BACKGROUND_COLOR = "white"
+TEXT_COLOR = "black"
+PALETTE = "tab10"
 FONT_SIZE = 14
+TITLE_SCALE_FACTOR = 2
 MAX_RESULTS = 50
 
 
@@ -122,19 +124,23 @@ class StyleTemplate:
 
     @property
     def font_mapping(self) -> Dict[int, int]:
-        """Map font levels to adjusted font sizes.
+        """Compute progressive font sizes based on the base font.
+
+        The mapping spans five emphasis levels, centered around ``font_size``.
+        Each step is scaled to 15% of the base font (minimum step of 1) and
+        clamped to a size of at least 1 point to avoid non-readable values for
+        very small fonts.
 
         Returns
         -------
         dict[int, int]
-            Level to font size mapping.
+            Level-to-font-size mapping where keys increase with size.
         """
+        base_size = max(int(self.font_size), 1)
+        step = max(int(math.ceil(base_size * 0.15)), 1)
         return {
-            0: self.font_size - 3,
-            1: self.font_size - 1,
-            2: self.font_size,
-            3: self.font_size + 1,
-            4: self.font_size + 3,
+            idx: max(base_size + offset * step, 1)
+            for idx, offset in enumerate(range(-2, 3))
         }
 
 
@@ -209,7 +215,7 @@ def generate_ticks(
     min_val: Union[float, str, pd.Timestamp],
     max_val: Union[float, str, pd.Timestamp],
     num_ticks: int = 5,
-) -> Union[np.ndarray, pd.DatetimeIndex]:
+) -> Union[np.ndarray, pd.DatetimeIndex, pd.Timestamp]:
     """Generate evenly spaced ticks between min and max.
 
     Parameters
@@ -261,6 +267,10 @@ def generate_ticks(
 
 # region Style Presets
 
+TABLE_STYLE_TEMPLATE = StyleTemplate(
+    background_color="black", fig_border="darkgrey", font_color="white", palette="magma"
+)
+
 BUBBLE_STYLE_TEMPLATE = StyleTemplate(
     format_funcs=cast(
         Dict[str, Optional[FormatterFunc]],
@@ -286,19 +296,12 @@ TABLE_STYLE_TEMPLATE = StyleTemplate()
 TREEMAP_STYLE_TEMPLATE = StyleTemplate()
 
 PIVOTBARS_STYLE_TEMPLATE = StyleTemplate(
-    background_color="black",
-    fig_border="darkgrey",
-    font_color="white",
-    palette="magma",
     format_funcs=cast(
         Dict[str, Optional[FormatterFunc]],
         {"y": percent_formatter, "label": string_formatter},
     ),
 )
 PIVOTLINES_STYLE_TEMPLATE = StyleTemplate(
-    background_color="white",
-    fig_border="lightgrey",
-    palette="viridis",
     format_funcs=cast(
         Dict[str, Optional[FormatterFunc]],
         {"y": percent_formatter, "label": string_formatter},
@@ -306,9 +309,11 @@ PIVOTLINES_STYLE_TEMPLATE = StyleTemplate(
 )
 
 NETWORK_STYLE_TEMPLATE = StyleTemplate()
-DISTRIBUTION_STYLE_TEMPLATE = StyleTemplate(palette="magma")
-HEATMAP_STYLE_TEMPLATE = StyleTemplate(palette="viridis")
-AREA_STYLE_TEMPLATE = StyleTemplate(palette="crest")
-PIE_STYLE_TEMPLATE = StyleTemplate(palette="Set2")
+DISTRIBUTION_STYLE_TEMPLATE = StyleTemplate()
+HEATMAP_STYLE_TEMPLATE = StyleTemplate()
+AREA_STYLE_TEMPLATE = StyleTemplate()
+PIE_STYLE_TEMPLATE = StyleTemplate()
 SANKEY_STYLE_TEMPLATE = StyleTemplate()
+WORDCLOUD_STYLE_TEMPLATE = StyleTemplate()
+
 # endregion