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

MatplotLibAPI/network/core.py

@@ -2,7 +2,6 @@
 
 from collections import defaultdict
 from typing import Any, Dict, Iterable, List, Optional, Tuple, Union, cast
-from pandas.api.extensions import register_dataframe_accessor
 import matplotlib.pyplot as plt
 import networkx as nx
 import numpy as np
@@ -29,6 +28,14 @@ __all__ = [
 ]
 
 
+def _compute_deciles(weights: Iterable[float]) -> Optional[np.ndarray]:
+    """Return deciles for ``weights`` or ``None`` when empty."""
+    weights_arr = np.asarray(list(weights), dtype=float)
+    if weights_arr.size == 0:
+        return None
+    return np.percentile(weights_arr, _WEIGHT_PERCENTILES)
+
+
 class NodeView(nx.classes.reportviews.NodeView):
     """Extended node view with convenience helpers."""
 
@@ -235,7 +242,6 @@ class EdgeView(nx.classes.reportviews.EdgeView):
         return pd.DataFrame(data)
 
 
-@register_dataframe_accessor("network")
 class NetworkGraph(BasePlot):
     """Custom graph class based on NetworkX's ``Graph``.
 
@@ -520,6 +526,9 @@ class NetworkGraph(BasePlot):
         max_font_size: int = _DEFAULT["MAX_FONT_SIZE"],
         min_font_size: int = _DEFAULT["MIN_FONT_SIZE"],
         edge_weight_col: str = "weight",
+        *,
+        node_deciles: Optional[np.ndarray],
+        edge_deciles: Optional[np.ndarray],
     ) -> Tuple[List[float], List[float], Dict[int, List[str]]]:
         """Calculate node, edge and font sizes based on weights.
 
@@ -536,7 +545,11 @@ class NetworkGraph(BasePlot):
         min_font_size : int, optional
             Lower bound for font size. The default is `_DEFAULT["MIN_FONT_SIZE"]`.
         edge_weight_col : str, optional
-            Node attribute used for weighting. The default is "weight".
+            Edge attribute used for weighting. The default is "weight".
+        node_deciles : np.ndarray, optional
+            Node-weight deciles used to scale node and font sizes.
+        edge_deciles : np.ndarray, optional
+            Edge-weight deciles used to scale edge widths.
 
         Returns
         -------
@@ -547,11 +560,6 @@ class NetworkGraph(BasePlot):
         node_weights = [
             data.get(edge_weight_col, 1) for node, data in self.node_view(data=True)
         ]
-        node_deciles = (
-            np.percentile(np.array(node_weights), _WEIGHT_PERCENTILES)
-            if node_weights
-            else None
-        )
         node_size = _scale_weights(
             weights=node_weights,
             scale_max=max_node_size,
@@ -563,7 +571,11 @@ class NetworkGraph(BasePlot):
         edge_weights = [
             data.get(edge_weight_col, 1) for _, _, data in self.edge_view(data=True)
         ]
-        edges_width = _scale_weights(weights=edge_weights, scale_max=max_edge_width)
+        edges_width = _scale_weights(
+            weights=edge_weights,
+            scale_max=max_edge_width,
+            deciles=edge_deciles,
+        )
 
         # Scale the normalized node weights within the desired range of font sizes
         node_size_dict = dict(
@@ -683,7 +695,7 @@ class NetworkGraph(BasePlot):
     def aplot(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         edge_weight_col: str = "weight",
         layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
         ax: Optional[Axes] = None,
@@ -709,6 +721,8 @@ class NetworkGraph(BasePlot):
         Axes
             Matplotlib axes with the plotted network.
         """
+        if not style:
+            style = NETWORK_STYLE_TEMPLATE
         sns.set_palette(style.palette)
         if ax is None:
             ax = cast(Axes, plt.gca())
@@ -716,6 +730,7 @@ class NetworkGraph(BasePlot):
         isolated_nodes = list(nx.isolates(self._nx_graph))
         graph_nx = self._nx_graph
         if isolated_nodes:
+
             graph_nx = graph_nx.copy()
             graph_nx.remove_nodes_from(isolated_nodes)
 
@@ -733,6 +748,14 @@ class NetworkGraph(BasePlot):
 
         mapped_min_font_size = style.font_mapping.get(0)
         mapped_max_font_size = style.font_mapping.get(4)
+        node_weights = [
+            data.get(edge_weight_col, 1) for _, data in graph.node_view(data=True)
+        ]
+        edge_weights = [
+            data.get(edge_weight_col, 1) for _, _, data in graph.edge_view(data=True)
+        ]
+        node_deciles = _compute_deciles(node_weights)
+        edge_deciles = _compute_deciles(edge_weights)
 
         node_sizes, edge_widths, font_sizes = graph.layout(
             min_node_size=_DEFAULT["MIN_NODE_SIZE"],
@@ -749,6 +772,8 @@ class NetworkGraph(BasePlot):
                 else _DEFAULT["MAX_FONT_SIZE"]
             ),
             edge_weight_col=edge_weight_col,
+            node_deciles=node_deciles,
+            edge_deciles=edge_deciles,
         )
         pos = graph.compute_positions(seed=layout_seed)
         # nodes
@@ -791,51 +816,10 @@ class NetworkGraph(BasePlot):
 
         return ax
 
-    def fplot(
-        self,
-        title: Optional[str] = None,
-        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
-        layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
-        figsize: Tuple[float, float] = FIG_SIZE,
-    ) -> Figure:
-        """Plot the graph using node and edge weights.
-
-        Parameters
-        ----------
-        title : str, optional
-            Plot title.
-        style : StyleTemplate, optional
-            Style configuration. The default is `NETWORK_STYLE_TEMPLATE`.
-        edge_weight_col : str, optional
-            Edge attribute used for weighting. The default is "weight".
-        layout_seed : int, optional
-            Seed for the spring layout used to place nodes. The default is ``_DEFAULT["SPRING_LAYOUT_SEED"]``.
-
-        Returns
-        -------
-        Figure
-            Matplotlib figure with the plotted network.
-        """
-        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,
-            edge_weight_col="",
-            layout_seed=layout_seed,
-            ax=ax,
-        )
-        return fig
-
     def aplot_connected_components(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         edge_weight_col: str = "weight",
         layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
         axes: Optional[np.ndarray] = None,
@@ -864,6 +848,8 @@ class NetworkGraph(BasePlot):
             or created, the flattened array of axes is returned; otherwise, a
             single Axes is returned.
         """
+        if not style:
+            style = NETWORK_STYLE_TEMPLATE
         sns.set_palette(style.palette)
 
         graph = self
@@ -912,9 +898,10 @@ class NetworkGraph(BasePlot):
     def fplot_connected_components(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         edge_weight_col: str = "weight",
         layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
+        figsize: Tuple[float, float] = FIG_SIZE,
     ) -> Figure:
         """Plot all connected components of the graph.
 
@@ -934,9 +921,11 @@ class NetworkGraph(BasePlot):
         Figure
             Matplotlib figure with the plotted network.
         """
-        fig, ax = plt.subplots(figsize=FIG_SIZE)
-        fig = cast(Figure, fig)
-        fig.set_facecolor(style.background_color)
+        if not style:
+            style = NETWORK_STYLE_TEMPLATE
+
+        fig, ax = BasePlot.create_fig(figsize=figsize, style=style)
+
         self.aplot_connected_components(
             title=title,
             style=style,

MatplotLibAPI/network/plot.py

@@ -20,6 +20,7 @@ from ..style_template import (
 )
 
 __all__ = [
+    "trim_low_degree_nodes",
     "aplot_network",
     "aplot_network_node",
     "aplot_network_components",
@@ -29,6 +30,90 @@ __all__ = [
 ]
 
 
+def trim_low_degree_nodes(
+    pandas_df: pd.DataFrame,
+    source: str = "source",
+    target: str = "target",
+    min_degree: int = 2,
+    recursive: bool = True,
+) -> pd.DataFrame:
+    """Return an edge list filtered by minimum undirected node degree.
+
+    The function preserves all original columns and only filters rows (edges).
+    Degree is computed from the edge list as an undirected multigraph:
+    duplicate edges contribute repeatedly, and self-loops contribute ``2`` to
+    the node degree (once from ``source`` and once from ``target``).
+
+    Parameters
+    ----------
+    pandas_df : pd.DataFrame
+        Edge list DataFrame.
+    source : str, optional
+        Source node column name. The default is ``"source"``.
+    target : str, optional
+        Target node column name. The default is ``"target"``.
+    min_degree : int, optional
+        Minimum undirected degree required for each endpoint. The default is ``2``.
+        Use ``0`` to disable filtering.
+    recursive : bool, optional
+        Whether to recursively prune until stable. The default is ``True``.
+        If ``False``, the filter is applied in a single pass using degrees
+        from the original edge list.
+
+    Returns
+    -------
+    pd.DataFrame
+        Filtered copy of ``pandas_df``.
+
+    Raises
+    ------
+    AttributeError
+        If required columns are missing.
+    ValueError
+        If ``min_degree`` is negative.
+
+    Examples
+    --------
+    >>> trim_low_degree_nodes(df, source="src", target="dst", min_degree=2)
+    """
+    validate_dataframe(pandas_df, cols=[source, target])
+    if min_degree < 0:
+        raise ValueError("min_degree must be greater than or equal to 0.")
+
+    result = pandas_df.copy()
+    if result.empty or min_degree == 0:
+        return result
+
+    def _filter_once(edges_df: pd.DataFrame) -> pd.DataFrame:
+        valid_endpoints = edges_df[source].notna() & edges_df[target].notna()
+        valid_edges = edges_df.loc[valid_endpoints]
+        if valid_edges.empty:
+            return valid_edges.copy()
+
+        degree = cast(
+            pd.Series,
+            pd.concat(
+                [valid_edges[source], valid_edges[target]], ignore_index=True
+            ).value_counts(),
+        )
+        keep_nodes = {
+            node for node, node_degree in degree.items() if node_degree >= min_degree
+        }
+        keep_mask = valid_edges[source].isin(keep_nodes) & valid_edges[target].isin(
+            keep_nodes
+        )
+        return valid_edges.loc[keep_mask].copy()
+
+    if not recursive:
+        return _filter_once(result)
+
+    while True:
+        filtered = _filter_once(result)
+        if len(filtered) == len(result):
+            return filtered
+        result = filtered
+
+
 def _sanitize_node_dataframe(
     node_df: Optional[pd.DataFrame],
     edge_df: pd.DataFrame,
@@ -182,7 +267,7 @@ def aplot_network(
     edge_target_col: str = "target",
     edge_weight_col: str = "weight",
     title: Optional[str] = None,
-    style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
     ax: Optional[Axes] = None,
 ) -> Axes:
@@ -233,7 +318,7 @@ def aplot_network_node(
     edge_target_col: str = "target",
     edge_weight_col: str = "weight",
     title: Optional[str] = None,
-    style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     ax: Optional[Axes] = None,
     layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
 ) -> Axes:
@@ -308,7 +393,7 @@ def aplot_network_components(
     ascending: bool = False,
     node_df: Optional[pd.DataFrame] = None,
     title: Optional[str] = None,
-    style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
     axes: Optional[np.ndarray] = None,
 ) -> None:
@@ -368,7 +453,7 @@ def fplot_network(
     edge_target_col: str = "target",
     edge_weight_col: str = "weight",
     title: Optional[str] = None,
-    style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
     figsize: Tuple[float, float] = FIG_SIZE,
 ) -> Figure:
@@ -427,7 +512,7 @@ def fplot_network_node(
     edge_target_col: str = "target",
     edge_weight_col: str = "weight",
     title: Optional[str] = None,
-    style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = FIG_SIZE,
     layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
 ) -> Figure:
@@ -478,6 +563,8 @@ def fplot_network_node(
     ValueError
         If ``node`` is not present in the prepared graph.
     """
+    if not style:
+        style = NETWORK_STYLE_TEMPLATE
     fig = cast(Figure, plt.figure(figsize=figsize))
     fig.set_facecolor(style.background_color)
     ax = fig.add_subplot(111)
@@ -501,7 +588,7 @@ def fplot_network_components(
     edge_target_col: str = "target",
     edge_weight_col: str = "weight",
     title: Optional[str] = None,
-    style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     layout_seed: Optional[int] = _DEFAULT["SPRING_LAYOUT_SEED"],
     figsize: Tuple[float, float] = FIG_SIZE,
     n_cols: Optional[int] = None,
@@ -554,6 +641,8 @@ def fplot_network_components(
         If ``node_df`` is provided but none of its nodes appear as sources or
         targets in ``pd_df``.
     """
+    if not style:
+        style = NETWORK_STYLE_TEMPLATE
     graph = NetworkGraph(
         pd_df=pd_df,
         source=edge_source_col,

MatplotLibAPI/pie.py

@@ -11,7 +11,6 @@ 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, _merge_kwargs
 
 __all__ = ["PIE_STYLE_TEMPLATE", "aplot_pie", "fplot_pie"]
 
@@ -63,7 +62,7 @@ class PieChart(BasePlot):
         """
         labels = self._obj[self.category].astype(str).tolist()
         sizes = self._obj[self.value]
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         wedgeprops: Optional[Dict[str, Any]] = None
         if donut:
             wedgeprops = {"width": 0.3}
@@ -74,48 +73,12 @@ class PieChart(BasePlot):
             "wedgeprops": wedgeprops,
             "textprops": {"color": style.font_color, "fontsize": style.font_size},
         }
-        plot_ax.pie(sizes, **_merge_kwargs(pie_kwargs, kwargs))
+        plot_ax.pie(sizes, **BasePlot.merge_kwargs(pie_kwargs, kwargs))
         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 = fig.add_subplot(111)
-        ax.set_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,

MatplotLibAPI/pivot.py

@@ -9,7 +9,6 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 
 from .base_plot import BasePlot
-from .utils import _merge_kwargs
 
 from .style_template import (
     FIG_SIZE,
@@ -103,8 +102,7 @@ class PivotBarChart(BasePlot):
             ascending=ascending,
         )
 
-        if ax is None:
-            ax = cast(Axes, plt.gca())
+        plot_ax = BasePlot.get_axis(ax)
 
         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")
@@ -113,47 +111,24 @@ class PivotBarChart(BasePlot):
             "kind": "bar",
             "x": self.x,
             "stacked": self.stacked,
-            "ax": ax,
+            "ax": plot_ax,
             "alpha": 0.7,
         }
-        pivot_df.plot(**_merge_kwargs(plot_kwargs, kwargs))
+        pivot_df.plot(**BasePlot.merge_kwargs(plot_kwargs, kwargs))
 
-        ax.set_ylabel(string_formatter(self.y))
-        ax.set_xlabel(string_formatter(self.x))
+        plot_ax.set_ylabel(string_formatter(self.y))
+        plot_ax.set_xlabel(string_formatter(self.x))
         if title:
-            ax.set_title(title)
+            plot_ax.set_title(title)
 
-        ax.legend(
+        plot_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 = fig.add_subplot(111)
-        ax.set_facecolor(style.background_color)
-        self.aplot(
-            title=title, style=style, sort_by=sort_by, ascending=ascending, ax=ax
-        )
-        return fig
+        plot_ax.tick_params(axis="x", rotation=90)
+        return plot_ax
 
 
 def aplot_pivoted_bars(

MatplotLibAPI/table.py

@@ -2,7 +2,6 @@
 
 from typing import Any, List, Optional, Tuple
 import pandas as pd
-import matplotlib.pyplot as plt
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from matplotlib.transforms import Bbox
@@ -10,7 +9,6 @@ from matplotlib.table import Table
 
 from .base_plot import BasePlot
 
-from .utils import _get_axis
 
 from .style_template import (
     FIG_SIZE,
@@ -62,7 +60,7 @@ class TablePlot(BasePlot):
         ax: Optional[Axes] = None,
         **kwargs: Any,
     ) -> Axes:
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
 
         if sort_by is None:
             sort_by = self.cols[0]
@@ -101,32 +99,6 @@ class TablePlot(BasePlot):
             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 = fig.add_subplot(111)
-        ax.set_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,

MatplotLibAPI/timeserie.py

@@ -9,7 +9,7 @@ from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 
 from .base_plot import BasePlot
-from .utils import _get_axis
+
 from .style_template import (
     TIMESERIE_STYLE_TEMPLATE,
     FIG_SIZE,
@@ -210,7 +210,7 @@ class TimeSeriePlot(BasePlot):
         format_funcs = format_func(
             style.format_funcs, label=self.label, x=self.x, y=self.y
         )
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         _plot_timeserie_lines(
             plot_ax, df, self.label, self.x, self.y, std, style, format_funcs
         )
@@ -222,34 +222,6 @@ class TimeSeriePlot(BasePlot):
             )
         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 = fig.add_subplot(111)
-        ax.set_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,

MatplotLibAPI/treemap.py

@@ -19,7 +19,7 @@ def aplot_treemap(
     pd_df: pd.DataFrame,
     path: str,
     values: str,
-    style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     title: Optional[str] = None,
     color: Optional[str] = None,
     sort_by: Optional[str] = None,
@@ -62,6 +62,8 @@ def aplot_treemap(
 
     sort_col = sort_by or values
     df = pd_df.sort_values(by=sort_col, ascending=ascending)[cols].head(max_values)
+    if not style:
+        style = TREEMAP_STYLE_TEMPLATE
     data: Dict[str, Any] = {
         "labels": df[path],
         "parents": [""] * len(df),

MatplotLibAPI/types.py

@@ -0,0 +1,6 @@
+"""Shared type aliases for MatplotLibAPI."""
+
+from typing import Literal
+from typing_extensions import TypeAlias
+
+CorrelationMethod: TypeAlias = Literal["pearson", "kendall", "spearman"]