MatplotLibAPI 3.2.21__tar.gz → 3.3.0__tar.gz

{matplotlibapi-3.2.21 → 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.21 → matplotlibapi-3.3.0}/MatplotLibAPI/Bubble.py

@@ -17,12 +17,10 @@ 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,
@@ -355,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
 

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

@@ -5,13 +5,19 @@ 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, FIG_SIZE, aplot_bubble
-from .Network import NETWORK_STYLE_TEMPLATE, aplot_network
-from .StyleTemplate import MAX_RESULTS, StyleTemplate, validate_dataframe
+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
@@ -122,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
 
 
@@ -200,17 +209,17 @@ def plot_composite_treemap(
 def plot_wordcloud_network(
     nodes_df: pd.DataFrame,
     edges_df: pd.DataFrame,
-    text_column: str = "node",
-    node_weight: Optional[str] = "weight",
-    source: str = "source",
-    target: str = "target",
-    edge_weight: str = "weight",
-    wordcloud_title: Optional[str] = None,
-    network_title: Optional[str] = None,
-    wordcloud_style: StyleTemplate = WORDCLOUD_STYLE_TEMPLATE,
-    network_style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    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.
@@ -221,31 +230,33 @@ def plot_wordcloud_network(
         DataFrame containing node labels and optional weights for the word cloud.
     edges_df : pd.DataFrame
         DataFrame containing edge connections for the network plot.
-    text_column : str, optional
+    node_col : str, optional
         Column in ``nodes_df`` containing the node labels. The default is ``"node"``.
-    node_weight : str, optional
+    node_weight_col : str, optional
         Column in ``nodes_df`` containing weights for sizing words. The default is
         ``"weight"``.
-    source : str, optional
+    edge_source_col : str, optional
         Column in ``edges_df`` containing source nodes. The default is ``"source"``.
-    target : str, optional
+    edge_target_col : str, optional
         Column in ``edges_df`` containing target nodes. The default is ``"target"``.
-    edge_weight : str, optional
+    edge_weight_col : str, optional
         Column in ``edges_df`` containing edge weights. The default is ``"weight"``.
-    wordcloud_title : str, optional
-        Title for the word cloud subplot. The default is ``None``.
-    network_title : str, optional
-        Title for the network subplot. The default is ``None``.
-    wordcloud_style : StyleTemplate, optional
-        Style configuration for the word cloud. The default is
-        ``WORDCLOUD_STYLE_TEMPLATE``.
-    network_style : StyleTemplate, optional
-        Style configuration for the network graph. The default is
-        ``NETWORK_STYLE_TEMPLATE``.
     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``.
 
@@ -254,35 +265,58 @@ def plot_wordcloud_network(
     Figure
         Matplotlib figure containing the word cloud on top and network below.
     """
-    validate_dataframe(nodes_df, cols=[text_column], sort_by=node_weight)
-    validate_dataframe(edges_df, cols=[source, target, edge_weight], sort_by=None)
+    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 = cast(Figure, plt.figure(figsize=figsize))
-    fig.patch.set_facecolor(wordcloud_style.background_color)
-    grid = GridSpec(2, 1, height_ratios=[1, 2])
+    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,
+        )
 
-    wordcloud_ax = fig.add_subplot(grid[0, 0])
     aplot_wordcloud(
         pd_df=nodes_df,
-        text_column=text_column,
-        weight_column=node_weight,
-        title=wordcloud_title,
+        text_column=node_col,
+        weight_column=node_weight_col,
+        title=None,
         style=wordcloud_style,
         max_words=max_words,
         stopwords=stopwords,
         ax=wordcloud_ax,
     )
 
-    network_ax = fig.add_subplot(grid[1, 0])
     aplot_network(
         pd_df=edges_df,
-        source=source,
-        target=target,
-        weight=edge_weight,
-        title=network_title,
+        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,
     )
 
-    fig.tight_layout()
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
     return fig