MatplotLibAPI 3.3.0__py3-none-any.whl → 4.0.1__py3-none-any.whl

MatplotLibAPI/area.py

@@ -0,0 +1,235 @@
+"""Area chart helpers for Matplotlib-based area visualizations."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .base_plot import BasePlot
+
+from .style_template import (
+    AREA_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from .utils import _get_axis, _merge_kwargs
+
+__all__ = ["AREA_STYLE_TEMPLATE", "aplot_area", "fplot_area"]
+
+
+class AreaChart(BasePlot):
+    """Plot area charts from tabular data.
+
+    Methods
+    -------
+    aplot
+        Plot an area chart on an existing Matplotlib axes.
+    fplot
+        Plot an area chart on a new Matplotlib figure.
+    """
+
+    def __init__(
+        self,
+        pd_df: pd.DataFrame,
+        x: str,
+        y: str,
+        label: Optional[str] = None,
+        stacked: bool = True,
+    ):
+        """Initialize an area chart plotter.
+
+        Parameters
+        ----------
+        pd_df : pd.DataFrame
+            DataFrame containing the data to visualize.
+        x : str
+            Column name used for the x-axis.
+        y : str
+            Column name used for the y-axis values.
+        label : str, optional
+            Column used to split the area into groups. The default is None.
+        stacked : bool, optional
+            Whether grouped areas are stacked. The default is True.
+        """
+        super().__init__(pd_df=pd_df)
+        self.x = x
+        self.y = y
+        self.label = label
+        self.stacked = stacked
+
+        cols = [self.x, self.y]
+        if self.label:
+            cols.append(self.label)
+        validate_dataframe(self._obj, cols=cols)
+
+    def _plot_grouped_area(
+        self,
+        plot_ax: Axes,
+        **kwargs: Any,
+    ) -> None:
+        """Plot grouped area data using a pivoted dataframe."""
+        pivot_df = self._obj.pivot_table(
+            index=self.x,
+            columns=self.label,
+            values=self.y,
+            aggfunc="sum",
+        ).sort_index()
+
+        plot_kwargs: dict[str, Any] = {
+            "kind": "area",
+            "stacked": self.stacked,
+            "alpha": 0.7,
+            "ax": plot_ax,
+        }
+        pivot_df.plot(**_merge_kwargs(plot_kwargs, kwargs))
+
+        legend = plot_ax.get_legend()
+        if legend is not None:
+            legend.set_title(string_formatter(self.label or ""))
+
+    def _plot_single_area(
+        self,
+        plot_ax: Axes,
+        style: StyleTemplate,
+        **kwargs: Any,
+    ) -> None:
+        """Plot a single-series area chart."""
+        sorted_df = self._obj.sort_values(by=self.x)
+        fill_between_kwargs: dict[str, Any] = {
+            "color": style.font_color,
+            "alpha": 0.4,
+        }
+        merged_fill_between_kwargs = _merge_kwargs(fill_between_kwargs, kwargs)
+
+        plot_ax.fill_between(
+            sorted_df[self.x],
+            sorted_df[self.y],
+            **merged_fill_between_kwargs,
+        )
+        plot_ax.plot(sorted_df[self.x], sorted_df[self.y], color=style.font_color)
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = AREA_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot an area chart on the provided axis.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title for the plot. The default is None.
+        style : StyleTemplate, optional
+            Style template for the plot. The default is AREA_STYLE_TEMPLATE.
+        ax : Axes, optional
+            Matplotlib axes to plot on. If None, use the current axes.
+        **kwargs : Any
+            Additional keyword arguments forwarded to the area plotting call.
+
+        Returns
+        -------
+        Axes
+            The Matplotlib axes containing the area chart.
+        """
+        plot_ax = _get_axis(ax)
+        plot_ax.set_facecolor(style.background_color)
+
+        if self.label:
+            self._plot_grouped_area(plot_ax=plot_ax, **kwargs)
+        else:
+            self._plot_single_area(plot_ax=plot_ax, style=style, **kwargs)
+
+        plot_ax.set_xlabel(string_formatter(self.x))
+        plot_ax.set_ylabel(string_formatter(self.y))
+        plot_ax.tick_params(axis="x", labelrotation=45)
+        if title:
+            plot_ax.set_title(title)
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = AREA_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (10, 6),
+        **kwargs: Any,
+    ) -> Figure:
+        """Plot an area chart on a new figure.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title for the plot. The default is None.
+        style : StyleTemplate, optional
+            Style template for the plot. The default is AREA_STYLE_TEMPLATE.
+        figsize : tuple[float, float], optional
+            Figure size. The default is (10, 6).
+
+        **kwargs : Any
+            Additional keyword arguments forwarded to ``aplot``.
+
+        Returns
+        -------
+        Figure
+            The Matplotlib figure containing the area chart.
+        """
+        fig = Figure(figsize=figsize)
+        fig.set_facecolor(style.background_color)
+        ax = fig.add_subplot(111)
+        self.aplot(title=title, style=style, ax=ax, **kwargs)
+        return fig
+
+
+def aplot_area(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    label: Optional[str] = None,
+    stacked: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = AREA_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot area charts, optionally stacked for part-to-whole trends."""
+    return AreaChart(
+        pd_df=pd_df,
+        x=x,
+        y=y,
+        label=label,
+        stacked=stacked,
+    ).aplot(
+        title=title,
+        style=style,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def fplot_area(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    label: Optional[str] = None,
+    stacked: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = AREA_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+    **kwargs: Any,
+) -> Figure:
+    """Plot area charts on a new figure."""
+    return AreaChart(
+        pd_df=pd_df,
+        x=x,
+        y=y,
+        label=label,
+        stacked=stacked,
+    ).fplot(
+        title=title,
+        style=style,
+        figsize=figsize,
+        **kwargs,
+    )

MatplotLibAPI/bar.py

@@ -0,0 +1,193 @@
+"""Bar and stacked bar chart helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .base_plot import BasePlot
+
+from .style_template import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from .utils import _get_axis, _merge_kwargs
+
+__all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_bar", "fplot_bar"]
+
+
+class BarChart(BasePlot):
+    """Plot grouped and stacked bar charts from tabular data.
+
+    Methods
+    -------
+    aplot
+        Plot a bar chart on an existing Matplotlib axes.
+    fplot
+        Plot a bar chart on a new Matplotlib figure.
+    """
+
+    def __init__(
+        self,
+        pd_df: pd.DataFrame,
+        category: str,
+        value: str,
+        group: Optional[str] = None,
+        stacked: bool = False,
+    ):
+        cols = [category, value]
+        if group:
+            cols.append(group)
+        validate_dataframe(pd_df, cols=cols)
+        super().__init__(pd_df=pd_df)
+        self.category = category
+        self.value = value
+        self.group = group
+        self.stacked = stacked
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot bar or stacked bar charts for categorical comparisons.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title for the plot, by default None.
+        style : StyleTemplate, optional
+            Style template for the plot, by default DISTRIBUTION_STYLE_TEMPLATE.
+        ax : Axes, optional
+            Matplotlib Axes to plot on, by default None which uses the current Axes.
+        **kwargs : Any
+            Additional keyword arguments forwarded to the plotting function.
+
+        Returns
+        -------
+        Axes
+            The Matplotlib Axes object containing the plot.
+        """
+        plot_ax = _get_axis(ax)
+
+        if self.group:
+            pivot_df = self._obj.pivot_table(
+                index=self.category,
+                columns=self.group,
+                values=self.value,
+                aggfunc="sum",
+            )
+            plot_kwargs: dict[str, Any] = {
+                "kind": "bar",
+                "stacked": self.stacked,
+                "ax": plot_ax,
+                "alpha": 0.85,
+            }
+            pivot_df.plot(**_merge_kwargs(plot_kwargs, kwargs))
+        else:
+            barplot_kwargs: dict[str, Any] = {
+                "data": self._obj,
+                "x": self.category,
+                "y": self.value,
+                "palette": style.palette,
+                "ax": plot_ax,
+            }
+            sns.barplot(**_merge_kwargs(barplot_kwargs, kwargs))
+
+        plot_ax.set_facecolor(style.background_color)
+        plot_ax.set_xlabel(string_formatter(self.category))
+        plot_ax.set_ylabel(string_formatter(self.value))
+        if title:
+            plot_ax.set_title(title)
+        plot_ax.tick_params(axis="x", labelrotation=45)
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (10, 6),
+    ) -> Figure:
+        """Plot bar or stacked bar charts on a new figure.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title for the plot, by default None.
+        style : StyleTemplate, optional
+            Style template for the plot, by default DISTRIBUTION_STYLE_TEMPLATE.
+        figsize : tuple[float, float], optional
+            The size of the figure, by default (10, 6).
+
+        Returns
+        -------
+        Figure
+            The Matplotlib Figure object containing the plot.
+        """
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = fig.add_subplot(111)
+        ax.set_facecolor(style.background_color)
+        fig.set_facecolor(style.background_color)
+        self.aplot(title=title, style=style, ax=ax)
+        return fig
+
+
+def aplot_bar(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    group: Optional[str] = None,
+    stacked: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot bar or stacked bar charts for categorical comparisons."""
+    return BarChart(
+        pd_df=pd_df,
+        category=category,
+        value=value,
+        group=group,
+        stacked=stacked,
+    ).aplot(
+        title=title,
+        style=style,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def fplot_bar(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    group: Optional[str] = None,
+    stacked: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot bar or stacked bar charts on a new figure."""
+    return BarChart(
+        pd_df=pd_df,
+        category=category,
+        value=value,
+        group=group,
+        stacked=stacked,
+    ).fplot(
+        title=title,
+        style=style,
+        figsize=figsize,
+    )

MatplotLibAPI/base_plot.py

@@ -0,0 +1,88 @@
+"""Abstract base class for all plot types."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .style_template import StyleTemplate
+
+
+class BasePlot(ABC):
+    """Base class defining the interface for all plot types.
+
+    This abstract base class ensures consistency across all plot implementations
+    by requiring both accessor-based (aplot_*) and figure-based (fplot_*) methods.
+
+    Methods
+    -------
+    aplot
+        Plot on an existing Matplotlib axes.
+    fplot
+        Plot on a new Matplotlib figure.
+    """
+
+    def __init__(self, pd_df: pd.DataFrame):
+        """Initialize the BasePlot."""
+        super().__init__()
+        self._obj = pd_df
+
+    @abstractmethod
+    def aplot(self, *args: Any, **kwargs: Any) -> Axes:
+        """Plot on an existing Matplotlib axes.
+
+        Subclasses should implement plot-specific parameters as needed.
+        Common parameters include title, style, and ax.
+
+        Parameters
+        ----------
+        pd_df : pd.DataFrame
+            The input DataFrame to plot.
+        *args : Any
+            Plot-specific positional arguments.
+        **kwargs : Any
+            Plot-specific keyword arguments. May include:
+            - title : str, optional
+                Chart title.
+            - style : StyleTemplate, optional
+                Styling template.
+            - ax : Axes, optional
+                Matplotlib axes to plot on. If None, uses the current axes.
+            - Additional plot-specific parameters.
+
+        Returns
+        -------
+        Axes
+            The Matplotlib axes object with the plot.
+        """
+
+    @abstractmethod
+    def fplot(self, *args: Any, **kwargs: Any) -> Figure:
+        """Plot on a new Matplotlib figure.
+
+        Subclasses should implement plot-specific parameters as needed.
+        Common parameters include title, style, and figsize.
+
+        Parameters
+        ----------
+        pd_df : pd.DataFrame
+            The input DataFrame to plot.
+        *args : Any
+            Plot-specific positional arguments.
+        **kwargs : Any
+            Plot-specific keyword arguments. May include:
+            - title : str, optional
+                Chart title.
+            - style : StyleTemplate, optional
+                Styling template.
+            - figsize : tuple, optional
+                Figure size as (width, height).
+            - Additional plot-specific parameters.
+
+        Returns
+        -------
+        Figure
+            The Matplotlib figure object with the plot.
+        """

MatplotLibAPI/box_violin.py

@@ -0,0 +1,186 @@
+"""Box and violin plot helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .base_plot import BasePlot
+
+from .style_template import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from .utils import _get_axis, _merge_kwargs
+
+__all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_box_violin", "fplot_box_violin"]
+
+
+class BoxViolinPlot(BasePlot):
+    """Plot box and violin distribution charts from tabular data.
+
+    Methods
+    -------
+    aplot
+        Plot a box or violin chart on an existing Matplotlib axes.
+    fplot
+        Plot a box or violin chart on a new Matplotlib figure.
+    """
+
+    def __init__(
+        self,
+        pd_df: pd.DataFrame,
+        column: str,
+        by: Optional[str] = None,
+        violin: bool = False,
+    ):
+        cols = [column]
+        if by:
+            cols.append(by)
+        validate_dataframe(pd_df=pd_df, cols=cols)
+        super().__init__(pd_df=pd_df)
+        self.column = column
+        self.by = by
+        self.violin = violin
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot a box or violin chart on the provided axis.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title for the plot. The default is None.
+        style : StyleTemplate, optional
+            Style template for the plot. The default is DISTRIBUTION_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 distribution chart.
+        """
+        plot_ax = _get_axis(ax)
+
+        common_kwargs = {
+            "data": self._obj,
+            "x": self.by,
+            "y": self.column,
+            "palette": style.palette,
+        }
+
+        plot_kwargs: dict[str, Any] = {
+            **common_kwargs,
+            "hue": self.by,
+            "legend": False,
+            "ax": plot_ax,
+        }
+        merged_plot_kwargs = _merge_kwargs(plot_kwargs, kwargs)
+
+        if self.violin:
+            sns.violinplot(**merged_plot_kwargs)
+        else:
+            sns.boxplot(**merged_plot_kwargs)
+
+        plot_ax.set_facecolor(style.background_color)
+        plot_ax.set_ylabel(string_formatter(self.column))
+        if self.by:
+            plot_ax.set_xlabel(string_formatter(self.by))
+        if title:
+            plot_ax.set_title(title)
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (10, 6),
+    ) -> Figure:
+        """Plot a box or violin chart on a new figure.
+
+        Parameters
+        ----------
+        title : str, optional
+            Title for the plot. The default is None.
+        style : StyleTemplate, optional
+            Style template for the plot. The default is DISTRIBUTION_STYLE_TEMPLATE.
+        figsize : tuple[float, float], optional
+            Figure size. The default is (10, 6).
+
+        Returns
+        -------
+        Figure
+            The Matplotlib figure containing the distribution chart.
+        """
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = fig.add_subplot(111)
+        ax.set_facecolor(style.background_color)
+        self.aplot(
+            title=title,
+            style=style,
+            ax=ax,
+        )
+        return fig
+
+
+def aplot_box_violin(
+    pd_df: pd.DataFrame,
+    column: str,
+    by: Optional[str] = None,
+    violin: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot box or violin charts to summarize distributions."""
+    return BoxViolinPlot(
+        pd_df=pd_df,
+        column=column,
+        by=by,
+        violin=violin,
+    ).aplot(
+        title=title,
+        style=style,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def fplot_box_violin(
+    pd_df: pd.DataFrame,
+    column: str,
+    by: Optional[str] = None,
+    violin: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot box or violin charts on a new figure."""
+    return BoxViolinPlot(
+        pd_df=pd_df,
+        column=column,
+        by=by,
+        violin=violin,
+    ).fplot(
+        title=title,
+        style=style,
+        figsize=figsize,
+    )