MatplotLibAPI 3.2.20__tar.gz → 3.3.0__tar.gz

{matplotlibapi-3.2.20 → matplotlibapi-3.3.0}/AGENTS.md

@@ -60,7 +60,7 @@ pytest -q --cov=MatplotLibAPI --cov-report=term-missing --cov-fail-under=70
 
 Each pull request should include:
 
-1. **Summary** – brief description of the change.
+1. **Summary** – brief description of the change. Mention breaking changes.
 2. **Testing** – commands run and confirmation that the tests passed.
 
 Example PR body:

{matplotlibapi-3.2.20 → matplotlibapi-3.3.0}/MatplotLibAPI/Bubble.py

@@ -15,13 +15,12 @@ from matplotlib.ticker import NullLocator
 
 from .StyleTemplate import (
     BUBBLE_STYLE_TEMPLATE,
+    FIG_SIZE,
     MAX_RESULTS,
+    TITLE_SCALE_FACTOR,
     StyleTemplate,
-    bmk_formatter,
     format_func,
     generate_ticks,
-    percent_formatter,
-    string_formatter,
     validate_dataframe,
     DynamicFuncFormatter,
     FormatterFunc,
@@ -354,7 +353,11 @@ def aplot_bubble(
     _draw_bubble_labels(ax, plot_df, label, x, y, style, format_funcs)
 
     if title:
-        ax.set_title(title, color=style.font_color, fontsize=style.font_size * 2)
+        ax.set_title(
+            title,
+            color=style.font_color,
+            fontsize=style.font_size * TITLE_SCALE_FACTOR,
+        )
 
     return ax
 
@@ -373,7 +376,7 @@ def fplot_bubble(
     ascending: bool = False,
     hline: bool = False,
     vline: bool = False,
-    figsize: Tuple[float, float] = (19.2, 10.8),
+    figsize: Tuple[float, float] = FIG_SIZE,
     save_path: Optional[str] = None,
     savefig_kwargs: Optional[Dict[str, Any]] = None,
 ) -> Figure:
@@ -408,7 +411,7 @@ def fplot_bubble(
     vline : bool, optional
         Draw vertical line at mean x. The default is `False`.
     figsize : tuple[float, float], optional
-        Size of the figure. The default is (19.2, 10.8).
+        Size of the figure. The default is FIG_SIZE.
 
     Returns
     -------

{matplotlibapi-3.2.20 → matplotlibapi-3.3.0}/MatplotLibAPI/Composite.py

@@ -1,18 +1,26 @@
 """Composite plotting routines combining multiple charts."""
 
-from typing import Dict, Optional, Tuple, cast
+from typing import Dict, Iterable, Optional, Tuple, cast
 
 import matplotlib.pyplot as plt
 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 .Bubble import BUBBLE_STYLE_TEMPLATE, aplot_bubble
-from .StyleTemplate import StyleTemplate, validate_dataframe
+from .Bubble import BUBBLE_STYLE_TEMPLATE, FIG_SIZE, aplot_bubble
+from .Network import aplot_network
+from .StyleTemplate import (
+    MAX_RESULTS,
+    TITLE_SCALE_FACTOR,
+    StyleTemplate,
+    validate_dataframe,
+)
 from .Table import aplot_table
 from .Treemap import TREEMAP_STYLE_TEMPLATE, aplot_treemap
+from .Wordcloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud
 
 
 def plot_composite_bubble(
@@ -29,7 +37,7 @@ def plot_composite_bubble(
     sort_by: Optional[str] = None,
     ascending: bool = False,
     table_rows: int = 10,
-    figsize: Tuple[float, float] = (19.2, 10.8),
+    figsize: Tuple[float, float] = FIG_SIZE,
 ) -> Figure:
     """Plot a composite bubble chart with summary tables.
 
@@ -62,7 +70,7 @@ def plot_composite_bubble(
     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 (19.2, 10.8).
+        Size of the created figure. The default is FIG_SIZE.
 
     Returns
     -------
@@ -120,7 +128,10 @@ def plot_composite_bubble(
         max_values=table_rows,
         style=style,
     )
-    fig.tight_layout()
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
     return fig
 
 
@@ -193,3 +204,119 @@ def plot_composite_treemap(
             current_row += 1
         return fig
     return None
+
+
+def plot_wordcloud_network(
+    nodes_df: pd.DataFrame,
+    edges_df: pd.DataFrame,
+    node_col: str = "node",
+    node_weight_col: str = "weight",
+    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: StyleTemplate = WORDCLOUD_STYLE_TEMPLATE,
+    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
+    ----------
+    nodes_df : pd.DataFrame
+        DataFrame containing node labels and optional weights for the word cloud.
+    edges_df : pd.DataFrame
+        DataFrame containing edge connections for the network plot.
+    node_col : str, optional
+        Column in ``nodes_df`` containing the node labels. The default is ``"node"``.
+    node_weight_col : str, optional
+        Column in ``nodes_df`` containing weights for sizing words. The default is
+        ``"weight"``.
+    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.
+    """
+    validate_dataframe(nodes_df, cols=[node_col], sort_by=node_weight_col)
+    validate_dataframe(
+        edges_df, cols=[edge_source_col, edge_target_col, edge_weight_col], sort_by=None
+    )
+
+    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.patch.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,
+        )
+
+    aplot_wordcloud(
+        pd_df=nodes_df,
+        text_column=node_col,
+        weight_column=node_weight_col,
+        title=None,
+        style=wordcloud_style,
+        max_words=max_words,
+        stopwords=stopwords,
+        ax=wordcloud_ax,
+    )
+
+    aplot_network(
+        pd_df=edges_df,
+        node_df=nodes_df,
+        node_col=node_col,
+        node_weight_col=node_weight_col,
+        edge_source_col=edge_source_col,
+        edge_target_col=edge_target_col,
+        edge_weight_col=edge_weight_col,
+        title=None,
+        style=network_style,
+        ax=network_ax,
+    )
+
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
+    return fig