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

MatplotLibAPI/bubble.py

@@ -4,11 +4,10 @@ Provides a Bubble class to create and render bubble charts using seaborn and mat
 with customizable styling via `StyleTemplate`.
 """
 
-from typing import Any, Dict, Optional, Tuple, cast
+from typing import Any, Dict, Optional, cast
 
 import matplotlib.pyplot as plt
 import pandas as pd
-from pandas.api.extensions import register_dataframe_accessor
 import seaborn as sns
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
@@ -18,7 +17,6 @@ from .base_plot import BasePlot
 
 from .style_template import (
     BUBBLE_STYLE_TEMPLATE,
-    FIG_SIZE,
     MAX_RESULTS,
     TITLE_SCALE_FACTOR,
     StyleTemplate,
@@ -29,10 +27,9 @@ from .style_template import (
     FormatterFunc,
 )
 
-__all__ = ["BUBBLE_STYLE_TEMPLATE", "Bubble"]
+__all__ = ["BUBBLE_STYLE_TEMPLATE", "Bubble", "aplot_bubble", "fplot_bubble"]
 
 
-@register_dataframe_accessor("bubble")
 class Bubble(BasePlot):
     """Bubble chart plot implementing the BasePlot interface.
 
@@ -399,26 +396,96 @@ class Bubble(BasePlot):
         """
         if not style:
             style = BUBBLE_STYLE_TEMPLATE
-        if ax is None:
-            ax = cast(Axes, plt.gca())
+        plot_ax = BasePlot.get_axis(ax)
 
         format_funcs = format_func(
             style.format_funcs, label=self.label, x=self.x, y=self.y, z=self.z
         )
 
-        Bubble._setup_axes(ax, style, self._obj, self.x, self.y, format_funcs)
+        Bubble._setup_axes(plot_ax, style, self._obj, self.x, self.y, format_funcs)
 
-        Bubble._draw_bubbles(ax, self._obj, self.x, self.y, self.z, style)
-        Bubble._draw_lines(ax, self._obj, self.x, self.y, hline, vline, style)
+        Bubble._draw_bubbles(plot_ax, self._obj, self.x, self.y, self.z, style)
+        Bubble._draw_lines(plot_ax, self._obj, self.x, self.y, hline, vline, style)
         Bubble._draw_labels(
-            ax, self._obj, self.label, self.x, self.y, style, format_funcs
+            plot_ax, self._obj, self.label, self.x, self.y, style, format_funcs
         )
 
         if title:
-            ax.set_title(
+            plot_ax.set_title(
                 title,
                 color=style.font_color,
                 fontsize=style.font_size * TITLE_SCALE_FACTOR,
             )
 
-        return ax
+        return plot_ax
+
+
+def aplot_bubble(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    max_values: int = MAX_RESULTS,
+    center_to_mean: bool = False,
+    title: Optional[str] = None,
+    style: Optional[StyleTemplate] = None,
+    hline: bool = False,
+    vline: bool = False,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot a matrix heatmap for multivariate pattern detection."""
+    return Bubble(
+        pd_df=pd_df,
+        label=label,
+        x=x,
+        y=y,
+        z=z,
+        max_values=max_values,
+        center_to_mean=center_to_mean,
+        sort_by=sort_by,
+        ascending=ascending,
+    ).aplot(
+        title=title,
+        style=style or BUBBLE_STYLE_TEMPLATE,
+        hline=hline,
+        vline=vline,
+        ax=ax,
+    )
+
+
+def fplot_bubble(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    max_values: int = MAX_RESULTS,
+    center_to_mean: bool = False,
+    title: Optional[str] = None,
+    style: Optional[StyleTemplate] = None,
+    hline: bool = False,
+    vline: bool = False,
+) -> Figure:
+    """Plot a matrix heatmap for multivariate pattern detection."""
+    return Bubble(
+        pd_df=pd_df,
+        label=label,
+        x=x,
+        y=y,
+        z=z,
+        max_values=max_values,
+        center_to_mean=center_to_mean,
+        sort_by=sort_by,
+        ascending=ascending,
+    ).fplot(
+        title=title,
+        style=style or BUBBLE_STYLE_TEMPLATE,
+        hline=hline,
+        vline=vline,
+    )

MatplotLibAPI/composite.py

@@ -7,13 +7,12 @@ import pandas as pd
 import plotly.graph_objects as go
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
-from matplotlib.gridspec import GridSpec
 from plotly.subplots import make_subplots
 
-from .base_plot import BasePlot
+from .base_plot import FIG_SIZE
 
-from .bubble import BUBBLE_STYLE_TEMPLATE, FIG_SIZE, Bubble
-from .network import aplot_network, NetworkGraph
+from .bubble import aplot_bubble, Bubble
+from .network import NetworkGraph
 from .style_template import (
     MAX_RESULTS,
     TITLE_SCALE_FACTOR,
@@ -21,8 +20,8 @@ from .style_template import (
     validate_dataframe,
 )
 from .table import aplot_table
-from .treemap import TREEMAP_STYLE_TEMPLATE, aplot_treemap
-from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, WordCloud
+from .treemap import aplot_treemap
+from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud
 
 
 def plot_composite_bubble(
@@ -80,13 +79,20 @@ def plot_composite_bubble(
         Matplotlib figure containing the composite bubble chart and tables.
     """
     validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
-    if not style:
-        style = BUBBLE_STYLE_TEMPLATE
-    fig = cast(Figure, plt.figure(figsize=figsize))
-    fig.set_facecolor(style.background_color)
-    grid = GridSpec(2, 2, height_ratios=[2, 1], width_ratios=[1, 1])
-    ax = fig.add_subplot(grid[0, 0:])
-    ax = Bubble(
+    if style is None:
+        style = WORDCLOUD_STYLE_TEMPLATE
+    fig = plt.figure(figsize=figsize)
+    gs = fig.add_gridspec(
+        2,
+        2,
+        height_ratios=[2, 1],
+        width_ratios=[1, 1],
+    )
+    ax = fig.add_subplot(gs[0, :])
+    ax2 = fig.add_subplot(gs[1, 0])
+    ax3 = fig.add_subplot(gs[1, 1])
+
+    aplot_bubble(
         pd_df=pd_df,
         label=label,
         x=x,
@@ -96,13 +102,11 @@ def plot_composite_bubble(
         center_to_mean=center_to_mean,
         sort_by=sort_by,
         ascending=ascending,
-    ).aplot(
         title=title,
         style=style,
         ax=ax,
     )
 
-    ax2 = fig.add_subplot(grid[1, 0])
     ax2 = aplot_table(
         pd_df=pd_df,
         cols=[label, z, y, x],
@@ -113,7 +117,7 @@ def plot_composite_bubble(
         max_values=table_rows,
         style=style,
     )
-    ax3 = fig.add_subplot(grid[1, 1])
+
     ax3 = aplot_table(
         pd_df=pd_df,
         cols=[label, z, y, x],
@@ -197,6 +201,219 @@ def plot_composite_treemap(
     return fig
 
 
+def fplot_bubble(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    title: Optional[str] = None,
+    style: Optional[StyleTemplate] = None,
+    max_values: int = 50,
+    center_to_mean: bool = False,
+    filter_by: Optional[str] = None,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    table_rows: int = 10,
+    figsize: Tuple[float, float] = FIG_SIZE,
+) -> Figure:
+    """Plot a composite bubble chart with summary tables.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        Data to be plotted.
+    label : str
+        Column name for bubble labels.
+    x : str
+        Column name for the x-axis values.
+    y : str
+        Column name for the y-axis values.
+    z : str
+        Column name for bubble sizes.
+    title : str, optional
+        Title of the plot. The default is ``None``.
+    style : StyleTemplate, optional
+        Style configuration. The default is `BUBBLE_STYLE_TEMPLATE`.
+    max_values : int, optional
+        Maximum number of rows to display in the chart. The default is 50.
+    center_to_mean : bool, optional
+        Whether to center the bubbles on the mean. The default is `False`.
+    filter_by : str, optional
+        Column used to filter the data.
+    sort_by : str, optional
+        Column used to sort the data.
+    ascending : bool, optional
+        Sort order for the data. The default is `False`.
+    table_rows : int, optional
+        Number of rows to display in the tables. The default is 10.
+    figsize : tuple[float, float], optional
+        Size of the created figure. The default is FIG_SIZE.
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure containing the composite bubble chart and tables.
+    """
+    validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
+    if style is None:
+        style = WORDCLOUD_STYLE_TEMPLATE
+    fig = plt.figure(figsize=figsize)
+    gs = fig.add_gridspec(
+        2,
+        2,
+        height_ratios=[2, 1],
+        width_ratios=[1, 1],
+    )
+    ax = fig.add_subplot(gs[0, :])
+    ax2 = fig.add_subplot(gs[1, 0])
+    ax3 = fig.add_subplot(gs[1, 1])
+
+    aplot_bubble(
+        pd_df=pd_df,
+        label=label,
+        x=x,
+        y=y,
+        z=z,
+        max_values=max_values,
+        center_to_mean=center_to_mean,
+        sort_by=sort_by,
+        ascending=ascending,
+        title=title,
+        style=style,
+        ax=ax,
+    )
+
+    ax2 = aplot_table(
+        pd_df=pd_df,
+        cols=[label, z, y, x],
+        title=f"Top {table_rows}",
+        ax=ax2,
+        sort_by=sort_by,
+        ascending=False,
+        max_values=table_rows,
+        style=style,
+    )
+
+    ax3 = aplot_table(
+        pd_df=pd_df,
+        cols=[label, z, y, x],
+        title=f"Last {table_rows}",
+        ax=ax3,
+        sort_by=sort_by,
+        ascending=True,
+        max_values=table_rows,
+        style=style,
+    )
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
+    return fig
+
+
+def fplot_wordcloud_network2(
+    edges_df: pd.DataFrame,
+    edge_source_col: str = "source",
+    edge_target_col: str = "target",
+    edge_weight_col: str = "weight",
+    max_words: int = MAX_RESULTS,
+    stopwords: Optional[Iterable[str]] = None,
+    title: Optional[str] = None,
+    style: Optional[StyleTemplate] = None,
+    wordcloud_style: Optional[StyleTemplate] = None,
+    network_style: Optional[StyleTemplate] = None,
+    figsize: Tuple[float, float] = FIG_SIZE,
+) -> Figure:
+    """Plot a word cloud above a network graph.
+
+    Parameters
+    ----------
+    edges_df : pd.DataFrame
+        DataFrame containing edge connections for the network plot.
+    edge_source_col : str, optional
+        Column in ``edges_df`` containing source nodes. The default is ``"source"``.
+    edge_target_col : str, optional
+        Column in ``edges_df`` containing target nodes. The default is ``"target"``.
+    edge_weight_col : str, optional
+        Column in ``edges_df`` containing edge weights. The default is ``"weight"``.
+    max_words : int, optional
+        Maximum number of words to include in the word cloud. The default is ``50``.
+    stopwords : Iterable[str], optional
+        Stopwords to exclude from the word cloud. The default is ``None``.
+    title : str, optional
+        Title for the composite figure. The default is ``None``.
+    style : StyleTemplate, optional
+        Shared style configuration applied to the composite figure and used for
+        subplots when specialized styles are not provided. The default is
+        ``WORDCLOUD_STYLE_TEMPLATE``.
+    wordcloud_style : StyleTemplate, optional
+        Optional style configuration for the word cloud subplot. When ``None``
+        the shared ``style`` is used. The default is ``None``.
+    network_style : StyleTemplate, optional
+        Optional style configuration for the network subplot. When ``None`` the
+        shared ``style`` is used. The default is ``None``.
+    figsize : tuple[float, float], optional
+        Size of the composite figure. The default is ``FIG_SIZE``.
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure containing the word cloud on top and network below.
+    """
+    if not style:
+        style = WORDCLOUD_STYLE_TEMPLATE
+    fig_raw, axes_raw = plt.subplots(
+        2,
+        1,
+        figsize=figsize,
+        gridspec_kw={"height_ratios": [1, 2]},
+    )
+    fig = cast(Figure, fig_raw)
+    wordcloud_ax, network_ax = cast(Tuple[Axes, Axes], axes_raw)
+
+    wordcloud_style = wordcloud_style or style
+    network_style = network_style or style
+
+    fig.set_facecolor(style.background_color)
+    if title:
+        fig.suptitle(
+            title,
+            color=style.font_color,
+            fontsize=style.font_size * TITLE_SCALE_FACTOR,
+            fontname=style.font_name,
+        )
+
+    network = NetworkGraph.from_pandas_edgelist(
+        edges_df=edges_df,
+        source=edge_source_col,
+        target=edge_target_col,
+        edge_weight_col=edge_weight_col,
+    )
+    network.aplot(
+        title=None,
+        style=network_style,
+        ax=network_ax,
+    )
+
+    aplot_wordcloud(
+        pd_df=network.node_view.to_dataframe(),
+        text_column="node",
+        weight_column=edge_weight_col,
+        title=None,
+        style=wordcloud_style,
+        max_words=max_words,
+        stopwords=stopwords,
+        ax=wordcloud_ax,
+    )
+
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
+    return fig
+
+
 def fplot_wordcloud_network(
     node_df: pd.DataFrame,
     edges_df: pd.DataFrame,

MatplotLibAPI/heatmap.py

@@ -1,22 +1,20 @@
 """Heatmap and correlation matrix helpers."""
 
-from typing import Any, Optional, Sequence, Tuple, cast, Literal
+from typing import Any, Optional, Sequence, Tuple, cast
 
 import pandas as pd
 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 .types import CorrelationMethod
 from .style_template import (
     HEATMAP_STYLE_TEMPLATE,
     StyleTemplate,
     string_formatter,
     validate_dataframe,
 )
-from .typing import CorrelationMethod
-from .utils import _get_axis, _merge_kwargs, create_fig
 
 __all__ = [
     "HEATMAP_STYLE_TEMPLATE",
@@ -27,7 +25,6 @@ __all__ = [
 ]
 
 
-@register_dataframe_accessor("heatmap")
 class Heatmap(BasePlot):
     """Class for plotting heatmaps and correlation matrices."""
 
@@ -60,13 +57,13 @@ class Heatmap(BasePlot):
         """Plot a heatmap on an existing Matplotlib axes."""
         if not style:
             style = HEATMAP_STYLE_TEMPLATE
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         heatmap_kwargs: dict[str, Any] = {
             "data": self._obj,
             "cmap": style.palette,
             "ax": plot_ax,
         }
-        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+        sns.heatmap(**BasePlot.merge_kwargs(heatmap_kwargs, kwargs))
 
         plot_ax.set_xlabel(string_formatter(self.x))
         plot_ax.set_ylabel(string_formatter(self.y))
@@ -85,7 +82,7 @@ class Heatmap(BasePlot):
         """Plot a correlation matrix heatmap on existing axes."""
         if not style:
             style = HEATMAP_STYLE_TEMPLATE
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         heatmap_kwargs: dict[str, Any] = {
             "data": self.correlation_matrix(correlation_method),
             "cmap": style.palette,
@@ -93,7 +90,7 @@ class Heatmap(BasePlot):
             "fmt": ".2f",
             "ax": plot_ax,
         }
-        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+        sns.heatmap(**BasePlot.merge_kwargs(heatmap_kwargs, kwargs))
         if title:
             plot_ax.set_title(title)
         return plot_ax
@@ -108,7 +105,7 @@ class Heatmap(BasePlot):
         """Plot a correlation matrix heatmap on a new figure."""
         if not style:
             style = HEATMAP_STYLE_TEMPLATE
-        fig, ax = create_fig(figsize=figsize, style=style)
+        fig, ax = BasePlot.create_fig(figsize=figsize, style=style)
         self.aplot_correlation_matrix(
             title=title,
             style=style,

MatplotLibAPI/histogram.py

@@ -3,9 +3,7 @@
 from typing import Any, Optional, Tuple
 
 import pandas as pd
-from pandas.api.extensions import register_dataframe_accessor
 import seaborn as sns
-import matplotlib.pyplot as plt
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 
@@ -19,12 +17,10 @@ from .style_template import (
     string_formatter,
     validate_dataframe,
 )
-from .utils import _get_axis, _merge_kwargs
 
 __all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_histogram", "fplot_histogram"]
 
 
-@register_dataframe_accessor("histogram")
 class Histogram(BasePlot):
     """Class for plotting histograms with optional KDE."""
 
@@ -49,7 +45,7 @@ class Histogram(BasePlot):
     ) -> Axes:
 
         validate_dataframe(self._obj, cols=[self.column])
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         histplot_kwargs: dict[str, Any] = {
             "data": self._obj,
             "x": self.column,
@@ -59,7 +55,7 @@ class Histogram(BasePlot):
             "edgecolor": style.background_color,
             "ax": plot_ax,
         }
-        sns.histplot(**_merge_kwargs(histplot_kwargs, kwargs))
+        sns.histplot(**BasePlot.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")

MatplotLibAPI/network/constants.py

@@ -19,4 +19,5 @@ _DEFAULT = {
 
 _WEIGHT_PERCENTILES = np.arange(10, 100, 10)
 
+
 __all__ = ["_DEFAULT", "_WEIGHT_PERCENTILES"]

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
@@ -243,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``.
 
@@ -455,6 +453,33 @@ class NetworkGraph(BasePlot):
         """Return the degree assortativity coefficient of the graph."""
         return nx.degree_assortativity_coefficient(self._nx_graph)
 
+    @property
+    def degree_distribution(self) -> Dict[int, int]:
+        """Return the count of nodes for each degree.
+
+        Returns
+        -------
+        dict[int, int]
+            Mapping from node degree to number of nodes with that degree.
+        """
+        distribution: Dict[int, int] = defaultdict(int)
+        for _, degree in self._nx_graph.degree():
+            distribution[int(degree)] += 1
+        return dict(sorted(distribution.items()))
+
+    @property
+    def degree_sequence(self) -> List[int]:
+        """Return node degrees sorted in descending order.
+
+        Returns
+        -------
+        list[int]
+            Degree for each node sorted from highest to lowest.
+        """
+        return sorted(
+            (int(degree) for _, degree in self._nx_graph.degree()), reverse=True
+        )
+
     def add_node(self, node: Any, **attributes: Any):
         """Add a node with optional attributes.
 

MatplotLibAPI/network/plot.py

@@ -501,6 +501,8 @@ def fplot_network(
     ).fplot(
         title=title,
         style=style,
+        edge_weight_col=edge_weight_col,
+        layout_seed=layout_seed,
         figsize=figsize,
     )
 

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,7 +73,7 @@ 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)

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,24 +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
+        plot_ax.tick_params(axis="x", rotation=90)
+        return plot_ax
 
 
 def aplot_pivoted_bars(