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

MatplotLibAPI/area.py

@@ -0,0 +1,177 @@
+"""Area chart helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import matplotlib.pyplot as plt
+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
+
+__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,
+    ):
+        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 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 reserved for compatibility.
+
+        Returns
+        -------
+        Axes
+            The Matplotlib axes containing the area chart.
+        """
+        plot_ax = _get_axis(ax)
+
+        if self.label:
+            pivot_df = self._obj.pivot_table(
+                index=self.x, columns=self.label, values=self.y, aggfunc="sum"
+            ).sort_index()
+            pivot_df.plot(kind="area", stacked=self.stacked, alpha=0.7, ax=plot_ax)
+        else:
+            sorted_df = self._obj.sort_values(by=self.x)
+            plot_ax.fill_between(
+                sorted_df[self.x], sorted_df[self.y], color=style.font_color, alpha=0.4
+            )
+            plot_ax.plot(sorted_df[self.x], sorted_df[self.y], color=style.font_color)
+
+        plot_ax.set_xlabel(string_formatter(self.x))
+        plot_ax.set_ylabel(string_formatter(self.y))
+        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),
+    ) -> 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).
+
+        Returns
+        -------
+        Figure
+            The Matplotlib figure containing the area 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, ax=ax)
+        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),
+) -> 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,
+    )

MatplotLibAPI/bar.py

@@ -0,0 +1,185 @@
+"""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
+
+__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",
+            )
+            pivot_df.plot(kind="bar", stacked=self.stacked, ax=plot_ax, alpha=0.85)
+        else:
+            sns.barplot(
+                data=self._obj,
+                x=self.category,
+                y=self.value,
+                palette=style.palette,
+                ax=plot_ax,
+            )
+
+        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 = Axes(fig=fig, 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,180 @@
+"""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
+
+__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,
+        }
+
+        if self.violin:
+            sns.violinplot(**common_kwargs, hue=self.by, legend=False, ax=plot_ax)
+        else:
+            sns.boxplot(**common_kwargs, hue=self.by, legend=False, ax=plot_ax)
+
+        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 = Axes(fig=fig, facecolor=style.background_color)
+        self.aplot(
+            column=self.column,
+            by=self.by,
+            violin=self.violin,
+            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,
+    )