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

MatplotLibAPI/heatmap.py

@@ -1,24 +1,22 @@
 """Heatmap and correlation matrix helpers."""
 
-from typing import Any, Optional, Sequence, Tuple
+from typing import Any, Optional, Sequence, Tuple, cast, Literal
 
 import pandas as pd
-from pandas.api.extensions import register_dataframe_accessor
-import matplotlib.pyplot as plt
 import seaborn as sns
 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 (
     HEATMAP_STYLE_TEMPLATE,
     StyleTemplate,
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis
 from .typing import CorrelationMethod
+from .utils import _get_axis, _merge_kwargs, create_fig
 
 __all__ = [
     "HEATMAP_STYLE_TEMPLATE",
@@ -45,20 +43,30 @@ class Heatmap(BasePlot):
         self.y = y
         self.value = value
 
-    @property
-    def correlation_matrix(self) -> pd.DataFrame:
+    def correlation_matrix(
+        self,
+        correlation_method: CorrelationMethod = "pearson",
+    ) -> pd.DataFrame:
         """Compute the correlation matrix for the underlying DataFrame."""
-        return self._obj.corr()
+        return self._obj.corr(method=correlation_method)
 
     def aplot(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         ax: Optional[Axes] = None,
         **kwargs: Any,
     ) -> Axes:
+        """Plot a heatmap on an existing Matplotlib axes."""
+        if not style:
+            style = HEATMAP_STYLE_TEMPLATE
         plot_ax = _get_axis(ax)
-        sns.heatmap(self._obj, cmap=style.palette, ax=plot_ax)
+        heatmap_kwargs: dict[str, Any] = {
+            "data": self._obj,
+            "cmap": style.palette,
+            "ax": plot_ax,
+        }
+        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
 
         plot_ax.set_xlabel(string_formatter(self.x))
         plot_ax.set_ylabel(string_formatter(self.y))
@@ -66,36 +74,26 @@ class Heatmap(BasePlot):
             plot_ax.set_title(title)
         return plot_ax
 
-    def fplot(
-        self,
-        title: Optional[str] = None,
-        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
-        figsize: Tuple[float, float] = (10, 6),
-    ) -> 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, ax=ax)
-        return fig
-
     def aplot_correlation_matrix(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
+        correlation_method: CorrelationMethod = "pearson",
         ax: Optional[Axes] = None,
         **kwargs: Any,
     ) -> Axes:
+        """Plot a correlation matrix heatmap on existing axes."""
+        if not style:
+            style = HEATMAP_STYLE_TEMPLATE
         plot_ax = _get_axis(ax)
-        sns.heatmap(
-            self.correlation_matrix,
-            cmap=style.palette,
-            annot=True,
-            fmt=".2f",
-            ax=plot_ax,
-        )
+        heatmap_kwargs: dict[str, Any] = {
+            "data": self.correlation_matrix(correlation_method),
+            "cmap": style.palette,
+            "annot": True,
+            "fmt": ".2f",
+            "ax": plot_ax,
+        }
+        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
         if title:
             plot_ax.set_title(title)
         return plot_ax
@@ -103,18 +101,18 @@ class Heatmap(BasePlot):
     def fplot_correlation_matrix(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         figsize: Tuple[float, float] = (10, 6),
+        correlation_method: CorrelationMethod = "pearson",
     ) -> Figure:
-        fig = Figure(
-            figsize=figsize,
-            facecolor=style.background_color,
-            edgecolor=style.background_color,
-        )
-        ax = Axes(fig=fig, facecolor=style.background_color)
-        self.aplot(
+        """Plot a correlation matrix heatmap on a new figure."""
+        if not style:
+            style = HEATMAP_STYLE_TEMPLATE
+        fig, ax = create_fig(figsize=figsize, style=style)
+        self.aplot_correlation_matrix(
             title=title,
             style=style,
+            correlation_method=correlation_method,
             ax=ax,
         )
         return fig
@@ -126,7 +124,7 @@ def _prepare_data(
     y: str,
     value: str,
 ) -> pd.DataFrame:
-    """Prepare data for treemap plotting."""
+    """Prepare data for heatmap plotting."""
     validate_dataframe(pd_df, cols=[x, y, value])
     plot_df = pd_df[[x, y, value]].pivot_table(
         index=y, columns=x, values=value, aggfunc="mean"
@@ -134,13 +132,26 @@ def _prepare_data(
     return plot_df
 
 
+def _compute_correlation_matrix(
+    pd_df: pd.DataFrame,
+    columns: Optional[Sequence[str]],
+    method: CorrelationMethod,
+) -> pd.DataFrame:
+    """Compute a correlation matrix from numeric dataframe columns."""
+    source_df = pd_df[list(columns)] if columns else pd_df
+    numeric_df = source_df.select_dtypes(include="number")
+    if numeric_df.empty:
+        raise ValueError("No numeric columns available to compute correlation matrix.")
+    return numeric_df.corr(method=cast(Any, method))
+
+
 def aplot_heatmap(
     pd_df: pd.DataFrame,
     x: str,
     y: str,
     value: str,
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     ax: Optional[Axes] = None,
     **kwargs: Any,
 ) -> Axes:
@@ -160,26 +171,50 @@ def aplot_heatmap(
 
 def aplot_correlation_matrix(
     pd_df: pd.DataFrame,
-    columns: Optional[Sequence[str]] = None,
-    method: CorrelationMethod = "pearson",
+    x: str,
+    y: str,
+    value: str,
+    correlation_method: CorrelationMethod = "pearson",
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     ax: Optional[Axes] = None,
     **kwargs: Any,
 ) -> Axes:
-    """Plot a correlation matrix heatmap for numeric columns."""
+    """Plot a correlation matrix heatmap on existing Matplotlib axes.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        Source dataframe containing correlation inputs.
+    x : str
+        Column used for heatmap x-axis labels.
+    y : str
+        Column used for heatmap y-axis labels.
+    value : str
+        Column providing values before correlation aggregation.
+    correlation_method : CorrelationMethod, optional
+        Correlation method. The default is ``"pearson"``.
+    title : str, optional
+        Plot title. The default is ``None``.
+    style : StyleTemplate, optional
+        Style template for rendering. The default is ``None``.
+    ax : Axes, optional
+        Matplotlib axes to draw on. If ``None``, use current axes.
+    **kwargs : Any
+        Additional keyword arguments forwarded to seaborn.
+
+    Returns
+    -------
+    Axes
+        The Matplotlib axes containing the correlation heatmap.
+    """
     return Heatmap(
         pd_df=pd_df,
-        x="",  # Placeholder since correlation matrix is square
-        y="",  # Placeholder since correlation matrix is square
-        value="",  # Placeholder since correlation matrix is computed internally
+        x=x,
+        y=y,
+        value=value,
     ).aplot_correlation_matrix(
-        method=method,
-        title=title,
-        style=style,
-        ax=ax,
-        columns=columns,
-        **kwargs,
+        title=title, style=style, correlation_method=correlation_method, ax=ax
     )
 
 
@@ -189,7 +224,7 @@ def fplot_heatmap(
     y: str,
     value: str,
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = (10, 6),
 ) -> Figure:
     """Plot a matrix heatmap on a new figure."""
@@ -211,13 +246,16 @@ def fplot_correlation_matrix(
     y: str,
     value: str,
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = (10, 6),
+    correlation_method: CorrelationMethod = "pearson",
 ) -> Figure:
     """Plot a correlation matrix heatmap on a new figure."""
     return Heatmap(
         pd_df=pd_df,
-        x=x,  # Placeholder since correlation matrix is square
-        y=y,  # Placeholder since correlation matrix is square
-        value=value,  # Placeholder since correlation matrix is computed internally
-    ).fplot_correlation_matrix(title=title, style=style, figsize=figsize)
+        x=x,
+        y=y,
+        value=value,
+    ).fplot_correlation_matrix(
+        title=title, style=style, figsize=figsize, correlation_method=correlation_method
+    )

MatplotLibAPI/histogram.py

@@ -19,7 +19,7 @@ from .style_template import (
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis
+from .utils import _get_axis, _merge_kwargs
 
 __all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_histogram", "fplot_histogram"]
 
@@ -50,15 +50,16 @@ class Histogram(BasePlot):
 
         validate_dataframe(self._obj, cols=[self.column])
         plot_ax = _get_axis(ax)
-        sns.histplot(
-            data=self._obj,
-            x=self.column,
-            bins=self.bins,
-            kde=self.kde,
-            color=style.font_color,
-            edgecolor=style.background_color,
-            ax=plot_ax,
-        )
+        histplot_kwargs: dict[str, Any] = {
+            "data": self._obj,
+            "x": self.column,
+            "bins": self.bins,
+            "kde": self.kde,
+            "color": style.font_color,
+            "edgecolor": style.background_color,
+            "ax": plot_ax,
+        }
+        sns.histplot(**_merge_kwargs(histplot_kwargs, kwargs))
         plot_ax.set_facecolor(style.background_color)
         plot_ax.set_xlabel(string_formatter(self.column))
         plot_ax.set_ylabel("Frequency")
@@ -66,25 +67,6 @@ class Histogram(BasePlot):
             plot_ax.set_title(title)
         return plot_ax
 
-    def fplot(
-        self,
-        title: Optional[str] = None,
-        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
-        figsize: Tuple[float, float] = (10, 6),
-    ) -> 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,
-            ax=ax,
-        )
-        return fig
-
 
 def aplot_histogram(
     pd_df: pd.DataFrame,

MatplotLibAPI/network/__init__.py

@@ -7,6 +7,7 @@ organizing implementation details in submodules.
 from .constants import _DEFAULT, _WEIGHT_PERCENTILES
 from .core import NETWORK_STYLE_TEMPLATE, NetworkGraph
 from .plot import (
+    trim_low_degree_nodes,
     aplot_network,
     aplot_network_node,
     aplot_network_components,
@@ -17,6 +18,7 @@ from .plot import (
 from .scaling import _scale_weights, _softmax
 
 __all__ = [
+    "trim_low_degree_nodes",
     "aplot_network",
     "aplot_network_node",
     "aplot_network_components",

MatplotLibAPI/network/core.py

@@ -29,6 +29,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."""
 
@@ -520,6 +528,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 +547,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 +562,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 +573,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 +697,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 +723,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 +732,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 +750,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 +774,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,50 +818,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 = Axes(fig=fig, 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,
@@ -863,6 +850,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
@@ -911,9 +900,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.
 
@@ -933,9 +923,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,