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

MatplotLibAPI/sunburst.py

@@ -0,0 +1,139 @@
+"""Sunburst chart plotting utilities."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from .style_template import (
+    TREEMAP_STYLE_TEMPLATE,
+    StyleTemplate,
+    validate_dataframe,
+)
+
+__all__ = ["TREEMAP_STYLE_TEMPLATE", "fplot_sunburst"]
+
+
+class SunburstData:
+    labels: list[str]
+    parents: list[str]
+    values: list[float]
+
+    def __init__(self, labels: list[str], parents: list[str], values: list[float]):
+        self.labels = labels
+        self.parents = parents
+        self.values = values
+
+    @staticmethod
+    def from_pandas(
+        edges_df: pd.DataFrame,
+        labels_col: str,
+        parents_col: str,
+        values_col: str,
+    ) -> "SunburstData":
+        """Create ``SunburstData`` from a DataFrame.
+
+        Parameters
+        ----------
+        edges_df : pd.DataFrame
+            DataFrame containing the data to plot.
+        labels_col : str
+            Column representing the labels of the sectors.
+        parents_col : str
+            Column representing the parent of each sector.
+        values_col : str
+            Column containing values for each sunburst sector.
+
+        Returns
+        -------
+        SunburstData
+            SunburstData object containing the labels, parents, and values for the sunburst plot.
+        """
+        validate_dataframe(edges_df, cols=[labels_col, parents_col, values_col])
+        return SunburstData(
+            labels=edges_df[labels_col].astype(str).tolist(),
+            parents=edges_df[parents_col].astype(str).tolist(),
+            values=edges_df[values_col].tolist(),
+        )
+
+    def fplot(
+        self,
+        style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
+        title: Optional[str] = None,
+    ) -> go.Figure:
+        """Return a figure containing the sunburst plot.
+
+        Parameters
+        ----------
+        style : StyleTemplate, optional
+            Style configuration. The default is `TREEMAP_STYLE_TEMPLATE`.
+        title : str, optional
+            Plot title.
+
+        Returns
+        -------
+        go.Figure
+            Figure containing the sunburst plot.
+        """
+        trace = go.Sunburst(
+            labels=self.labels,
+            parents=self.parents,
+            values=self.values,
+            textinfo="label+percent entry",
+        )
+
+        fig = go.Figure(trace)
+
+        fig.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,
+        )
+        return fig
+
+
+def fplot_sunburst(
+    pd_df: pd.DataFrame,
+    labels: str,
+    parents: str,
+    values: str,
+    style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
+    title: Optional[str] = None,
+) -> go.Figure:
+    """Return a figure containing the sunburst plot.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        DataFrame containing the data to plot.
+    labels : str
+        Column representing the labels of the sectors.
+    parents : str
+        Column representing the parent of each sector.
+    values : str
+        Column containing values for each sunburst sector.
+    style : StyleTemplate, optional
+        Style configuration. The default is `TREEMAP_STYLE_TEMPLATE`.
+    title : str, optional
+        Plot title.
+
+    Returns
+    -------
+    go.Figure
+        Figure containing the sunburst plot.
+    """
+    return SunburstData.from_pandas(
+        edges_df=pd_df,
+        labels_col=labels,
+        parents_col=parents,
+        values_col=values,
+    ).fplot(
+        style=style,
+        title=title,
+    )

MatplotLibAPI/{Table.py → table.py}

@@ -1,6 +1,6 @@
 """Table plotting helpers."""
 
-from typing import Any, Dict, List, Optional, Tuple, cast
+from typing import Any, List, Optional, Tuple
 import pandas as pd
 import matplotlib.pyplot as plt
 from matplotlib.axes import Axes
@@ -8,65 +8,20 @@ from matplotlib.figure import Figure
 from matplotlib.transforms import Bbox
 from matplotlib.table import Table
 
-from .StyleTemplate import StyleTemplate, string_formatter, validate_dataframe, FIG_SIZE
+from .base_plot import BasePlot
 
-TABLE_STYLE_TEMPLATE = StyleTemplate(
-    background_color="black", fig_border="darkgrey", font_color="white", palette="magma"
-)
-
-
-def _prepare_table_data(
-    pd_df: pd.DataFrame,
-    cols: List[str],
-    sort_by: Optional[str],
-    ascending: bool,
-    max_values: int,
-    style: StyleTemplate,
-) -> pd.DataFrame:
-    """Prepare data for table plotting.
-
-    Parameters
-    ----------
-    pd_df : pd.DataFrame
-        Input DataFrame.
-    cols : List[str]
-        Columns to include in the table.
-    sort_by : Optional[str]
-        Column to sort by.
-    ascending : bool
-        Sort order.
-    max_values : int
-        Maximum number of rows to display.
-    style : StyleTemplate
-        Styling for the plot.
-
-    Returns
-    -------
-    pd.DataFrame
-        Prepared DataFrame for plotting.
-
-    Raises
-    ------
-    AttributeError
-        If required columns are missing from the DataFrame.
-    """
-    validate_dataframe(pd_df, cols=cols, sort_by=sort_by)
+from .utils import _get_axis
 
-    if sort_by is None:
-        sort_by = cols[0]
-
-    plot_df = (
-        pd_df[cols]
-        .sort_values(by=[sort_by], ascending=ascending)  # type: ignore
-        .head(max_values)
-        .copy()
-    )
+from .style_template import (
+    FIG_SIZE,
+    TITLE_SCALE_FACTOR,
+    TABLE_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
 
-    if style.format_funcs:
-        for col, func in style.format_funcs.items():
-            if col in plot_df.columns and func is not None:
-                plot_df[col] = plot_df[col].apply(func)
-    return plot_df
+__all__ = ["TABLE_STYLE_TEMPLATE", "aplot_table", "fplot_table"]
 
 
 def _format_table(table: Table, style: StyleTemplate):
@@ -89,6 +44,89 @@ def _format_table(table: Table, style: StyleTemplate):
         cell.get_text().set_color(style.font_color)
 
 
+class TablePlot(BasePlot):
+    """Class for plotting tables."""
+
+    def __init__(self, pd_df: pd.DataFrame, cols: List[str]):
+        validate_dataframe(pd_df, cols=cols)
+        super().__init__(pd_df=pd_df)
+        self.cols = cols
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = TABLE_STYLE_TEMPLATE,
+        sort_by: Optional[str] = None,
+        ascending: bool = False,
+        max_values: int = 20,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        plot_ax = _get_axis(ax)
+
+        if sort_by is None:
+            sort_by = self.cols[0]
+
+        plot_df = (
+            self._obj[self.cols]
+            .sort_values(by=[sort_by], ascending=ascending)  # type: ignore
+            .head(max_values)
+            .copy()
+        )
+
+        if style.format_funcs:
+            for col, func in style.format_funcs.items():
+                if col in plot_df.columns and func is not None:
+                    plot_df[col] = plot_df[col].apply(func)
+
+        table_plot = plot_ax.table(
+            cellText=plot_df.values.tolist(),
+            colLabels=[string_formatter(colLabel) for colLabel in self.cols],
+            cellLoc="center",
+            colWidths=style.col_widths,
+            bbox=Bbox.from_bounds(0, -0.3, 1, 1.3),
+        )
+
+        _format_table(table_plot, style)
+
+        plot_ax.set_facecolor(style.background_color)
+        plot_ax.set_axis_off()
+        plot_ax.grid(False)
+        if title:
+            plot_ax.set_title(
+                title,
+                color=style.font_color,
+                fontsize=style.font_size * TITLE_SCALE_FACTOR,
+            )
+            plot_ax.title.set_position((0.5, 1.05))
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = TABLE_STYLE_TEMPLATE,
+        sort_by: Optional[str] = None,
+        ascending: bool = False,
+        max_values: int = 20,
+        figsize: Tuple[float, float] = FIG_SIZE,
+    ) -> 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,
+            max_values=max_values,
+            ax=ax,
+        )
+        return fig
+
+
 def aplot_table(
     pd_df: pd.DataFrame,
     cols: List[str],
@@ -98,6 +136,7 @@ def aplot_table(
     sort_by: Optional[str] = None,
     ascending: bool = False,
     ax: Optional[Axes] = None,
+    **kwargs: Any,
 ) -> Axes:
     """Render a table into the provided axes.
 
@@ -140,29 +179,16 @@ def aplot_table(
     >>> fig, ax = plt.subplots()
     >>> aplot_table(df, cols=['col1', 'col2'], ax=ax)
     """
-    if ax is None:
-        ax = cast(Axes, plt.gca())
-
-    plot_df = _prepare_table_data(pd_df, cols, sort_by, ascending, max_values, style)
-
-    table_plot = ax.table(
-        cellText=plot_df.values.tolist(),
-        colLabels=[string_formatter(colLabel) for colLabel in cols],
-        cellLoc="center",
-        colWidths=style.col_widths,
-        bbox=Bbox.from_bounds(0, -0.3, 1, 1.3),
+    return TablePlot(pd_df=pd_df, cols=cols).aplot(
+        title=title,
+        style=style,
+        sort_by=sort_by,
+        ascending=ascending,
+        max_values=max_values,
+        ax=ax,
+        **kwargs,
     )
 
-    _format_table(table_plot, style)
-
-    ax.set_facecolor(style.background_color)
-    ax.set_axis_off()
-    ax.grid(False)
-    if title:
-        ax.set_title(title, color=style.font_color, fontsize=style.font_size * 2)
-        ax.title.set_position((0.5, 1.05))
-    return ax
-
 
 def fplot_table(
     pd_df: pd.DataFrame,
@@ -173,8 +199,6 @@ def fplot_table(
     sort_by: Optional[str] = None,
     ascending: bool = False,
     figsize: Tuple[float, float] = FIG_SIZE,
-    save_path: Optional[str] = None,
-    savefig_kwargs: Optional[Dict[str, Any]] = None,
 ) -> Figure:
     """Return a new figure containing a formatted table.
 
@@ -215,10 +239,11 @@ def fplot_table(
     >>> df = pd.DataFrame(data)
     >>> fig = fplot_table(df, cols=['col1', 'col2'])
     """
-    fig = cast(Figure, plt.figure(figsize=figsize))
-    fig.patch.set_facecolor(style.background_color)
-    ax = fig.add_subplot()
-    ax = aplot_table(pd_df, cols, title, style, max_values, sort_by, ascending, ax)
-    if save_path:
-        fig.savefig(save_path, **(savefig_kwargs or {}))
-    return fig
+    return TablePlot(pd_df=pd_df, cols=cols).fplot(
+        title=title,
+        style=style,
+        sort_by=sort_by,
+        ascending=ascending,
+        max_values=max_values,
+        figsize=figsize,
+    )

MatplotLibAPI/{Timeserie.py → timeserie.py}

@@ -8,11 +8,12 @@ import seaborn as sns
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 
-from .StyleTemplate import (
+from .base_plot import BasePlot
+from .utils import _get_axis
+from .style_template import (
     TIMESERIE_STYLE_TEMPLATE,
     FIG_SIZE,
     StyleTemplate,
-    bmk_formatter,
     format_func,
     string_formatter,
     validate_dataframe,
@@ -20,6 +21,11 @@ from .StyleTemplate import (
     FormatterFunc,
 )
 
+__all__ = [
+    "TIMESERIE_STYLE_TEMPLATE",
+    "aplot_timeserie",
+    "fplot_timeserie",
+]
 
 # region Line
 
@@ -179,6 +185,71 @@ def _setup_timeserie_axes(
     ax.grid(True)
 
 
+class TimeSeriePlot(BasePlot):
+    """Class for plotting time series."""
+
+    def __init__(self, pd_df: pd.DataFrame, label: str, x: str, y: str):
+        validate_dataframe(pd_df, cols=[label, x, y])
+        super().__init__(pd_df=pd_df)
+        self.label = label
+        self.x = x
+        self.y = y
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = TIMESERIE_STYLE_TEMPLATE,
+        max_values: int = 100,
+        sort_by: Optional[str] = None,
+        ascending: bool = False,
+        std: bool = False,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        df = _prepare_timeserie_data(self._obj, self.label, self.x, self.y, sort_by)
+        format_funcs = format_func(
+            style.format_funcs, label=self.label, x=self.x, y=self.y
+        )
+        plot_ax = _get_axis(ax)
+        _plot_timeserie_lines(
+            plot_ax, df, self.label, self.x, self.y, std, style, format_funcs
+        )
+        _setup_timeserie_axes(plot_ax, self.label, self.x, self.y, style, format_funcs)
+
+        if title:
+            plot_ax.set_title(
+                title, color=style.font_color, fontsize=style.font_size + 4
+            )
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = TIMESERIE_STYLE_TEMPLATE,
+        max_values: int = 100,
+        sort_by: Optional[str] = None,
+        ascending: bool = False,
+        std: bool = False,
+        figsize: Tuple[float, float] = FIG_SIZE,
+    ) -> 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,
+            max_values=max_values,
+            sort_by=sort_by,
+            ascending=ascending,
+            std=std,
+            ax=ax,
+        )
+        return fig
+
+
 def aplot_timeserie(
     pd_df: pd.DataFrame,
     label: str,
@@ -191,6 +262,7 @@ def aplot_timeserie(
     ascending: bool = False,
     std: bool = False,
     ax: Optional[Axes] = None,
+    **kwargs: Any,
 ) -> Axes:
     """Plot a time series on the provided axes.
 
@@ -243,20 +315,16 @@ def aplot_timeserie(
     >>> fig, ax = plt.subplots()
     >>> aplot_timeserie(df, label='category', x='date', y='value', ax=ax)
     """
-    if ax is None:
-        ax = cast(Axes, plt.gca())
-
-    df = _prepare_timeserie_data(pd_df, label, x, y, sort_by)
-
-    format_funcs = format_func(style.format_funcs, label=label, x=x, y=y)
-
-    _plot_timeserie_lines(ax, df, label, x, y, std, style, format_funcs)
-
-    _setup_timeserie_axes(ax, label, x, y, style, format_funcs)
-
-    if title:
-        ax.set_title(title, color=style.font_color, fontsize=style.font_size + 4)
-    return ax
+    return TimeSeriePlot(pd_df=pd_df, label=label, x=x, y=y).aplot(
+        title=title,
+        style=style,
+        max_values=max_values,
+        sort_by=sort_by,
+        ascending=ascending,
+        std=std,
+        ax=ax,
+        **kwargs,
+    )
 
 
 def fplot_timeserie(
@@ -271,10 +339,8 @@ def fplot_timeserie(
     ascending: bool = False,
     std: bool = False,
     figsize: Tuple[float, float] = FIG_SIZE,
-    save_path: Optional[str] = None,
-    savefig_kwargs: Optional[Dict[str, Any]] = None,
 ) -> Figure:
-    """Return a figure plotting the time series.
+    """Return a new figure containing a time series plot.
 
     Parameters
     ----------
@@ -287,19 +353,19 @@ def fplot_timeserie(
     y : str
         Column for the y-axis values.
     title : str, optional
-        Plot title.
+        Plot title. The default is None.
     style : StyleTemplate, optional
-        Style configuration. The default is `TIMESERIE_STYLE_TEMPLATE`.
+        Style configuration. The default is ``TIMESERIE_STYLE_TEMPLATE``.
     max_values : int, optional
         Maximum number of rows to plot. The default is 100.
     sort_by : str, optional
-        Column used to sort the data.
+        Column used to sort the 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.
     std : bool, optional
-        Whether to plot rolling standard deviation. The default is `False`.
+        Whether to plot rolling standard deviation. The default is False.
     figsize : tuple[float, float], optional
-        Size of the created figure. The default is FIG_SIZE.
+        Size of the created figure. The default is ``FIG_SIZE``.
 
     Returns
     -------
@@ -316,32 +382,22 @@ def fplot_timeserie(
     >>> import pandas as pd
     >>> from MatplotLibAPI.Timeserie import fplot_timeserie
     >>> data = {
-    ...     'date': pd.to_datetime(['2023-01-01', '2023-01-02', '2023-01-01', '2023-01-02']),
-    ...     'category': ['A', 'A', 'B', 'B'],
-    ...     'value': [10, 12, 15, 13]
+    ...     "date": pd.to_datetime(["2023-01-01", "2023-01-02", "2023-01-01", "2023-01-02"]),
+    ...     "category": ["A", "A", "B", "B"],
+    ...     "value": [10, 12, 15, 13],
     ... }
     >>> df = pd.DataFrame(data)
-    >>> fig = fplot_timeserie(df, label='category', x='date', y='value')
+    >>> fig = fplot_timeserie(df, label="category", x="date", y="value")
     """
-    fig = cast(Figure, plt.figure(figsize=figsize))
-    fig.patch.set_facecolor(style.background_color)
-    ax = fig.add_subplot()
-    ax = aplot_timeserie(
-        pd_df=pd_df,
-        label=label,
-        x=x,
-        y=y,
+    return TimeSeriePlot(pd_df=pd_df, label=label, x=x, y=y).fplot(
         title=title,
         style=style,
         max_values=max_values,
-        std=std,
         sort_by=sort_by,
         ascending=ascending,
-        ax=ax,
+        std=std,
+        figsize=figsize,
     )
-    if save_path:
-        fig.savefig(save_path, **(savefig_kwargs or {}))
-    return fig
 
 
 # endregion