MatplotLibAPI 4.0.2__py3-none-any.whl → 4.0.4__py3-none-any.whl

MatplotLibAPI/__init__.py

@@ -1,7 +1,6 @@
 """Public API and pandas accessor for MatplotLibAPI."""
 
-from . import accessor as _accessor  # noqa: F401
-from .base_plot import BasePlot
-from .bubble import Bubble
+from .accessor import DataFrameAccessor
+from .types import CorrelationMethod
 
-__all__ = ["BasePlot", "Bubble"]
+__all__ = ["DataFrameAccessor", "CorrelationMethod"]

MatplotLibAPI/accessor.py

@@ -10,7 +10,6 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from pandas.api.extensions import register_dataframe_accessor
 
-from .base_plot import BasePlot
 from .style_template import (
     FIG_SIZE,
     AREA_STYLE_TEMPLATE,
@@ -21,148 +20,13 @@ from .style_template import (
     TREEMAP_STYLE_TEMPLATE,
     StyleTemplate,
 )
-from .typing import CorrelationMethod
+
+from .types import CorrelationMethod
 
 if TYPE_CHECKING:
     import plotly.graph_objects as go
 
 
-def _heatmap_imports() -> tuple[StyleTemplate, Any, Any, Any, Any]:
-    from .heatmap import (
-        HEATMAP_STYLE_TEMPLATE,
-        aplot_correlation_matrix,
-        aplot_heatmap,
-        fplot_correlation_matrix,
-        fplot_heatmap,
-    )
-
-    return (
-        HEATMAP_STYLE_TEMPLATE,
-        aplot_correlation_matrix,
-        aplot_heatmap,
-        fplot_correlation_matrix,
-        fplot_heatmap,
-    )
-
-
-def _network_imports() -> tuple[StyleTemplate, Any, Any, Any, Any, Any, Any]:
-    from .network import (
-        NETWORK_STYLE_TEMPLATE,
-        aplot_network,
-        aplot_network_node,
-        aplot_network_components,
-        fplot_network,
-        fplot_network_node,
-        fplot_network_components,
-    )
-
-    return (
-        NETWORK_STYLE_TEMPLATE,
-        aplot_network,
-        aplot_network_node,
-        aplot_network_components,
-        fplot_network,
-        fplot_network_node,
-        fplot_network_components,
-    )
-
-
-def _wordcloud_imports() -> tuple[StyleTemplate, Any, Any]:
-    from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, fplot_wordcloud
-
-    return WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, fplot_wordcloud
-
-
-def _sankey_imports() -> tuple[StyleTemplate, Any]:
-    from .sankey import SANKEY_STYLE_TEMPLATE, fplot_sankey
-
-    return SANKEY_STYLE_TEMPLATE, fplot_sankey
-
-
-def aplot_histogram(*args: Any, **kwargs: Any) -> Axes:
-    from .histogram import aplot_histogram as _aplot_histogram
-
-    return _aplot_histogram(*args, **kwargs)
-
-
-def fplot_histogram(*args: Any, **kwargs: Any) -> Figure:
-    from .histogram import fplot_histogram as _fplot_histogram
-
-    return _fplot_histogram(*args, **kwargs)
-
-
-def aplot_pie_donut(*args: Any, **kwargs: Any) -> Axes:
-    from .pie import aplot_pie as _aplot_pie_donut
-
-    return _aplot_pie_donut(*args, **kwargs)
-
-
-def fplot_pie_donut(*args: Any, **kwargs: Any) -> Figure:
-    from .pie import fplot_pie as _fplot_pie_donut
-
-    return _fplot_pie_donut(*args, **kwargs)
-
-
-def aplot_table(*args: Any, **kwargs: Any) -> Axes:
-    from .table import aplot_table as _aplot_table
-
-    return _aplot_table(*args, **kwargs)
-
-
-def fplot_table(*args: Any, **kwargs: Any) -> Figure:
-    from .table import fplot_table as _fplot_table
-
-    return _fplot_table(*args, **kwargs)
-
-
-def aplot_timeserie(*args: Any, **kwargs: Any) -> Axes:
-    from .timeserie import aplot_timeserie as _aplot_timeserie
-
-    return _aplot_timeserie(*args, **kwargs)
-
-
-def fplot_timeserie(*args: Any, **kwargs: Any) -> Figure:
-    from .timeserie import fplot_timeserie as _fplot_timeserie
-
-    return _fplot_timeserie(*args, **kwargs)
-
-
-def aplot_waffle(*args: Any, **kwargs: Any) -> Axes:
-    from .waffle import aplot_waffle as _aplot_waffle
-
-    return _aplot_waffle(*args, **kwargs)
-
-
-def fplot_waffle(*args: Any, **kwargs: Any) -> Figure:
-    from .waffle import fplot_waffle as _fplot_waffle
-
-    return _fplot_waffle(*args, **kwargs)
-
-
-def fplot_treemap(*args: Any, **kwargs: Any) -> go.Figure:
-    from .treemap import fplot_treemap as _fplot_treemap
-
-    return _fplot_treemap(*args, **kwargs)
-
-
-def fplot_sunburst(*args: Any, **kwargs: Any) -> go.Figure:
-    from .sunburst import fplot_sunburst as _fplot_sunburst
-
-    return _fplot_sunburst(*args, **kwargs)
-
-
-def plot_composite_bubble(*args: Any, **kwargs: Any) -> Figure:
-    from .composite import plot_composite_bubble as _plot_composite_bubble
-
-    return _plot_composite_bubble(*args, **kwargs)
-
-
-def plot_composite_treemap(*args: Any, **kwargs: Any) -> Optional[go.Figure]:
-    from .composite import plot_composite_treemap as _plot_composite_treemap
-
-    return _plot_composite_treemap(*args, **kwargs)
-
-
 @register_dataframe_accessor("mpl")
 class DataFrameAccessor:
     """Expose MatplotLibAPI plotting helpers as a pandas accessor.
@@ -490,7 +354,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the histogram.
         """
-        return aplot_histogram(
+        from .histogram import aplot_histogram as _aplot_histogram
+
+        return _aplot_histogram(
             pd_df=self._obj,
             column=column,
             bins=bins,
@@ -531,7 +397,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the histogram.
         """
-        return fplot_histogram(
+        from .histogram import fplot_histogram as _fplot_histogram
+
+        return _fplot_histogram(
             pd_df=self._obj,
             column=column,
             bins=bins,
@@ -844,7 +712,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the pie or donut chart.
         """
-        return aplot_pie_donut(
+        from .pie import aplot_pie as _aplot_pie_donut
+
+        return _aplot_pie_donut(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -885,7 +755,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the pie or donut chart.
         """
-        return fplot_pie_donut(
+        from .pie import fplot_pie as _fplot_pie_donut
+
+        return _fplot_pie_donut(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -926,7 +798,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the waffle chart.
         """
-        return aplot_waffle(
+        from .waffle import aplot_waffle as _aplot_waffle
+
+        return _aplot_waffle(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -967,7 +841,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the waffle chart.
         """
-        return fplot_waffle(
+        from .waffle import fplot_waffle as _fplot_waffle
+
+        return _fplot_waffle(
             pd_df=self._obj,
             category=category,
             value=value,
@@ -1005,7 +881,7 @@ class DataFrameAccessor:
         go.Figure
             The Plotly Sankey figure.
         """
-        sankey_style_template, fplot_sankey = _sankey_imports()
+        from .sankey import SANKEY_STYLE_TEMPLATE, fplot_sankey
 
         return fplot_sankey(
             pd_df=self._obj,
@@ -1013,7 +889,7 @@ class DataFrameAccessor:
             target=target,
             value=value,
             title=title,
-            style=style or sankey_style_template,
+            style=style or SANKEY_STYLE_TEMPLATE,
         )
 
     def aplot_table(
@@ -1050,7 +926,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the plot.
         """
-        return aplot_table(
+        from .table import aplot_table as _aplot_table
+
+        return _aplot_table(
             pd_df=self._obj,
             cols=cols,
             title=title,
@@ -1095,7 +973,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the table.
         """
-        return fplot_table(
+        from .table import fplot_table as _fplot_table
+
+        return _fplot_table(
             pd_df=self._obj,
             cols=cols,
             title=title,
@@ -1149,7 +1029,9 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the plot.
         """
-        return aplot_timeserie(
+        from .timeserie import aplot_timeserie as _aplot_timeserie
+
+        return _aplot_timeserie(
             pd_df=self._obj,
             label=label,
             x=x,
@@ -1206,7 +1088,9 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the plot.
         """
-        return fplot_timeserie(
+        from .timeserie import fplot_timeserie as _fplot_timeserie
+
+        return _fplot_timeserie(
             pd_df=self._obj,
             label=label,
             x=x,
@@ -1257,14 +1141,14 @@ class DataFrameAccessor:
         Axes
             The Matplotlib axes object with the plot.
         """
-        wordcloud_style_template, aplot_wordcloud, _ = _wordcloud_imports()
+        from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud
 
         return aplot_wordcloud(
             pd_df=self._obj,
             text_column=text_column,
             weight_column=weight_column,
             title=title,
-            style=style or wordcloud_style_template,
+            style=style or WORDCLOUD_STYLE_TEMPLATE,
             max_words=max_words,
             stopwords=stopwords,
             random_state=random_state,
@@ -1308,14 +1192,14 @@ class DataFrameAccessor:
         Figure
             The new Matplotlib figure with the plot.
         """
-        wordcloud_style_template, _, fplot_wordcloud = _wordcloud_imports()
+        from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, fplot_wordcloud
 
         return fplot_wordcloud(
             pd_df=self._obj,
             text_column=text_column,
             weight_column=weight_column,
             title=title,
-            style=style or wordcloud_style_template,
+            style=style or WORDCLOUD_STYLE_TEMPLATE,
             max_words=max_words,
             stopwords=stopwords,
             random_state=random_state,
@@ -1377,21 +1261,74 @@ class DataFrameAccessor:
         kwargs: Dict[str, Any] = {}
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
+        from .network import (
+            NETWORK_STYLE_TEMPLATE,
+            aplot_network_node as _aplot_network_node,
+        )
 
-        network_style_template, _, aplot_network_node, _, _, _, _ = _network_imports()
-
-        return aplot_network_node(
+        return _aplot_network_node(
             pd_df=self._obj,
             node=node,
             edge_source_col=edge_source_col,
             edge_target_col=edge_target_col,
             edge_weight_col=edge_weight_col,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             ax=ax,
             **kwargs,
         )
 
+    def fplot_network(
+        self,
+        edge_source_col: str = "source",
+        edge_target_col: str = "target",
+        edge_weight_col: str = "weight",
+        title: Optional[str] = None,
+        style: Optional[StyleTemplate] = None,
+        layout_seed: Optional[int] = None,
+        figsize: Tuple[float, float] = FIG_SIZE,
+    ) -> Figure:
+        """Plot a network graph on a new figure.
+
+        Parameters
+        ----------
+        edge_source_col : str, optional
+            Column for source nodes. The default is "source".
+        edge_target_col : str, optional
+            Column for target nodes. The default is "target".
+        edge_weight_col : str, optional
+            Column for edge weights. The default is "weight".
+        title : str, optional
+            Chart title.
+        style : StyleTemplate, optional
+            Styling template. The default is `NETWORK_STYLE_TEMPLATE`.
+        layout_seed : int, optional
+            Seed forwarded to the spring layout. The default is ``_DEFAULT["SPRING_LAYOUT_SEED"]``.
+        figsize : tuple[float, float], optional
+            Figure size. The default is FIG_SIZE.
+
+        Returns
+        -------
+        Figure
+            The new Matplotlib figure with the plot.
+        """
+        kwargs: Dict[str, Any] = {}
+        if layout_seed is not None:
+            kwargs["layout_seed"] = layout_seed
+
+        from .network import NETWORK_STYLE_TEMPLATE, fplot_network
+
+        return fplot_network(
+            pd_df=self._obj,
+            edge_source_col=edge_source_col,
+            edge_target_col=edge_target_col,
+            edge_weight_col=edge_weight_col,
+            title=title,
+            style=style or NETWORK_STYLE_TEMPLATE,
+            figsize=figsize,
+            **kwargs,
+        )
+
     def aplot_network_components(
         self,
         edge_source_col: str = "source",
@@ -1437,9 +1374,7 @@ class DataFrameAccessor:
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
 
-        network_style_template, _, _, aplot_network_components, _, _, _ = (
-            _network_imports()
-        )
+        from .network import NETWORK_STYLE_TEMPLATE, aplot_network_components
 
         aplot_network_components(
             pd_df=self._obj,
@@ -1449,7 +1384,7 @@ class DataFrameAccessor:
             sort_by=sort_by,
             ascending=ascending,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             axes=axes,
             **kwargs,
         )
@@ -1510,7 +1445,7 @@ class DataFrameAccessor:
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
 
-        network_style_template, _, _, _, _, fplot_network_node, _ = _network_imports()
+        from .network import NETWORK_STYLE_TEMPLATE, fplot_network_node
 
         return fplot_network_node(
             pd_df=self._obj,
@@ -1519,7 +1454,7 @@ class DataFrameAccessor:
             edge_target_col=edge_target_col,
             edge_weight_col=edge_weight_col,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             figsize=figsize,
             **kwargs,
         )
@@ -1575,9 +1510,7 @@ class DataFrameAccessor:
         if layout_seed is not None:
             kwargs["layout_seed"] = layout_seed
 
-        network_style_template, _, _, _, _, _, fplot_network_components = (
-            _network_imports()
-        )
+        from .network import NETWORK_STYLE_TEMPLATE, fplot_network_components
 
         return fplot_network_components(
             pd_df=self._obj,
@@ -1585,7 +1518,7 @@ class DataFrameAccessor:
             edge_target_col=edge_target_col,
             edge_weight_col=edge_weight_col,
             title=title,
-            style=style or network_style_template,
+            style=style or NETWORK_STYLE_TEMPLATE,
             figsize=figsize,
             n_cols=n_cols,
             **kwargs,
@@ -1631,6 +1564,8 @@ class DataFrameAccessor:
         go.Figure
             The Plotly figure with the treemap.
         """
+        from .treemap import fplot_treemap
+
         return fplot_treemap(
             pd_df=self._obj,
             path=path,
@@ -1680,6 +1615,8 @@ class DataFrameAccessor:
         go.Figure
             The Plotly figure with the sunburst chart.
         """
+        from .sunburst import fplot_sunburst
+
         return fplot_sunburst(
             pd_df=self._obj,
             labels=labels,
@@ -1729,6 +1666,8 @@ class DataFrameAccessor:
         go.Figure, optional
             The Plotly figure with the composite treemap, or None if the input data is empty.
         """
+        from .composite import plot_composite_treemap
+
         pd_dfs: Dict[str, pd.DataFrame] = {}
         for path in paths:
             pd_dfs[path] = self._obj

MatplotLibAPI/area.py

@@ -14,7 +14,6 @@ from .style_template import (
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis, _merge_kwargs, create_fig
 
 __all__ = ["AREA_STYLE_TEMPLATE", "aplot_area", "fplot_area"]
 
@@ -83,7 +82,7 @@ class AreaChart(BasePlot):
             "alpha": 0.7,
             "ax": plot_ax,
         }
-        pivot_df.plot(**_merge_kwargs(plot_kwargs, kwargs))
+        pivot_df.plot(**BasePlot.merge_kwargs(plot_kwargs, kwargs))
 
         legend = plot_ax.get_legend()
         if legend is not None:
@@ -101,7 +100,7 @@ class AreaChart(BasePlot):
             "color": style.font_color,
             "alpha": 0.4,
         }
-        merged_fill_between_kwargs = _merge_kwargs(fill_between_kwargs, kwargs)
+        merged_fill_between_kwargs = BasePlot.merge_kwargs(fill_between_kwargs, kwargs)
 
         plot_ax.fill_between(
             sorted_df[self.x],
@@ -137,7 +136,7 @@ class AreaChart(BasePlot):
         """
         if not style:
             style = AREA_STYLE_TEMPLATE
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         plot_ax.set_facecolor(style.background_color)
 
         if self.label:

MatplotLibAPI/bar.py

@@ -15,7 +15,6 @@ from .style_template import (
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis, _merge_kwargs
 
 __all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_bar", "fplot_bar"]
 
@@ -74,7 +73,7 @@ class BarChart(BasePlot):
         Axes
             The Matplotlib Axes object containing the plot.
         """
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
 
         if self.group:
             pivot_df = self._obj.pivot_table(
@@ -89,7 +88,7 @@ class BarChart(BasePlot):
                 "ax": plot_ax,
                 "alpha": 0.85,
             }
-            pivot_df.plot(**_merge_kwargs(plot_kwargs, kwargs))
+            pivot_df.plot(**BasePlot.merge_kwargs(plot_kwargs, kwargs))
         else:
             barplot_kwargs: dict[str, Any] = {
                 "data": self._obj,
@@ -98,7 +97,7 @@ class BarChart(BasePlot):
                 "palette": style.palette,
                 "ax": plot_ax,
             }
-            sns.barplot(**_merge_kwargs(barplot_kwargs, kwargs))
+            sns.barplot(**BasePlot.merge_kwargs(barplot_kwargs, kwargs))
 
         plot_ax.set_facecolor(style.background_color)
         plot_ax.set_xlabel(string_formatter(self.category))

MatplotLibAPI/base_plot.py

@@ -1,7 +1,7 @@
 """Abstract base class for all plot types."""
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Tuple, cast
+from typing import Any, Optional, Tuple, cast, Dict
 
 import pandas as pd
 import matplotlib.pyplot as plt
@@ -85,9 +85,38 @@ class BasePlot(ABC):
 
         return fig
 
-    @classmethod
+    def filter(
+        self, order_by: str, sort_ascending: bool = False, max_values: int = 10
+    ) -> pd.DataFrame:
+        """Filter and sort the underlying DataFrame.
+
+        Parameters
+        ----------
+        order_by : str
+            Column name to sort by.
+        sort_ascending : bool, optional
+            Sort direction. Defaults to False (descending).
+        max_values : int, optional
+            Maximum number of rows to return. Defaults to 10.
+
+        Returns
+        -------
+        pd.DataFrame
+            Filtered, sorted DataFrame head by the provided limits.
+
+        Raises
+        ------
+        ValueError
+            If the `order_by` column is not present in the DataFrame.
+        """
+        if order_by not in self._obj.columns:
+            raise ValueError(f"Column '{order_by}' not found in DataFrame")
+        df = self._obj.sort_values(by=order_by, ascending=sort_ascending)
+        return df.head(max_values)
+
+    @staticmethod
     def create_fig(
-        cls, figsize: Tuple[float, float], style: StyleTemplate
+        figsize: Tuple[float, float], style: StyleTemplate
     ) -> Tuple[Figure, Axes]:
         """Create a figure and axis configured from the provided style.
 
@@ -110,3 +139,31 @@ class BasePlot(ABC):
         fig.set_edgecolor(style.background_color)
         ax.set_facecolor(style.background_color)
         return fig, ax
+
+    @staticmethod
+    def get_axis(ax: Optional[Axes] = None) -> Axes:
+        """Return a Matplotlib axes, defaulting to the current one."""
+        return ax if ax is not None else plt.gca()
+
+    @staticmethod
+    def merge_kwargs(
+        defaults: Dict[str, Any], overrides: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Return a merged kwargs dictionary with caller overrides taking precedence.
+
+        Parameters
+        ----------
+        defaults : dict[str, Any]
+            Default keyword arguments.
+        overrides : dict[str, Any], optional
+            Caller-provided keyword arguments that should override defaults.
+
+        Returns
+        -------
+        dict[str, Any]
+            Merged keyword arguments.
+        """
+        merged = defaults.copy()
+        if overrides:
+            merged.update(overrides)
+        return merged

MatplotLibAPI/box_violin.py

@@ -15,7 +15,6 @@ from .style_template import (
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis, _merge_kwargs
 
 __all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_box_violin", "fplot_box_violin"]
 
@@ -74,7 +73,7 @@ class BoxViolinPlot(BasePlot):
         """
         if not style:
             style = DISTRIBUTION_STYLE_TEMPLATE
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
 
         common_kwargs = {
             "data": self._obj,
@@ -89,7 +88,7 @@ class BoxViolinPlot(BasePlot):
             "legend": False,
             "ax": plot_ax,
         }
-        merged_plot_kwargs = _merge_kwargs(plot_kwargs, kwargs)
+        merged_plot_kwargs = BasePlot.merge_kwargs(plot_kwargs, kwargs)
 
         if self.violin:
             sns.violinplot(**merged_plot_kwargs)