MatplotLibAPI 3.2.18__py3-none-any.whl → 3.2.20__py3-none-any.whl

MatplotLibAPI/BoxViolin.py

@@ -33,10 +33,12 @@ def aplot_box_violin(
     validate_dataframe(pd_df, cols=cols)
     plot_ax = _get_axis(ax)
 
+    common_kwargs = {"data": pd_df, "x": by, "y": column, "palette": style.palette}
+
     if violin:
-        sns.violinplot(data=pd_df, x=by, y=column, palette=style.palette, ax=plot_ax)
+        sns.violinplot(**common_kwargs, hue=by, legend=False, ax=plot_ax)
     else:
-        sns.boxplot(data=pd_df, x=by, y=column, palette=style.palette, ax=plot_ax)
+        sns.boxplot(**common_kwargs, hue=by, legend=False, ax=plot_ax)
 
     plot_ax.set_facecolor(style.background_color)
     plot_ax.set_ylabel(string_formatter(column))

MatplotLibAPI/Wordcloud.py

@@ -25,33 +25,6 @@ WORDCLOUD_STYLE_TEMPLATE = StyleTemplate(
 )
 
 
-def _normalize_weights(weights: Sequence[float], base_size: int) -> np.ndarray:
-    """Normalize weights to a range of font sizes.
-
-    Parameters
-    ----------
-    weights : Sequence[float]
-        Sequence of weights representing word importance.
-    base_size : int
-        Base font size used as the lower bound for scaling.
-
-    Returns
-    -------
-    numpy.ndarray
-        Array of font sizes corresponding to the provided weights.
-    """
-    numeric_weights = np.asarray(weights, dtype=float)
-    if numeric_weights.size == 0:
-        return np.array([], dtype=float)
-    min_weight = numeric_weights.min()
-    max_weight = numeric_weights.max()
-    if min_weight == max_weight:
-        return np.full_like(numeric_weights, fill_value=base_size, dtype=float)
-
-    min_size, max_size = base_size, base_size * 4
-    return np.interp(numeric_weights, (min_weight, max_weight), (min_size, max_size))
-
-
 def _filter_stopwords(
     words: Iterable[str], stopwords: Optional[Iterable[str]]
 ) -> np.ndarray:
@@ -131,6 +104,40 @@ def _prepare_word_frequencies(
     return words, weights
 
 
+def create_circular_mask(size: int = 300, radius: Optional[int] = None) -> np.ndarray:
+    """Construct a binary mask with a circular opening for a word cloud.
+
+    Parameters
+    ----------
+    size : int, optional
+        Width and height of the mask in pixels. Defaults to ``300``.
+    radius : int, optional
+        Radius of the circular opening in pixels. Defaults to ``size // 2``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Two-dimensional array suitable for the ``mask`` argument of
+        ``wordcloud.WordCloud`` where ``0`` values define the drawable region.
+
+    Raises
+    ------
+    ValueError
+        If ``size`` or ``radius`` are non-positive.
+    """
+    if size <= 0:
+        raise ValueError("size must be a positive integer.")
+
+    resolved_radius = radius if radius is not None else size // 2
+    if resolved_radius <= 0:
+        raise ValueError("radius must be a positive integer.")
+
+    center = (size - 1) / 2
+    x, y = np.ogrid[:size, :size]
+    mask_region = (x - center) ** 2 + (y - center) ** 2 > resolved_radius**2
+    return 255 * mask_region.astype(np.uint8)
+
+
 def _plot_words(
     ax: Axes,
     words: Sequence[str],
@@ -138,6 +145,7 @@ def _plot_words(
     style: StyleTemplate,
     title: Optional[str],
     random_state: Optional[int],
+    mask: Optional[np.ndarray],
 ) -> Axes:
     """Render words on the provided axes with sizes proportional to weights.
 
@@ -179,25 +187,39 @@ def _plot_words(
 
     canvas.draw()
     ax_bbox = ax.get_window_extent()
-    width = max(int(ax_bbox.width), 1)
-    height = max(int(ax_bbox.height), 1)
+    resolved_mask = create_circular_mask() if mask is None else np.asarray(mask)
+    if resolved_mask is not None and resolved_mask.ndim != 2:
+        raise ValueError("mask must be a 2D array.")
+
+    width = (
+        max(int(ax_bbox.width), 1)
+        if resolved_mask is None
+        else max(int(resolved_mask.shape[1]), 1)
+    )
+    height = (
+        max(int(ax_bbox.height), 1)
+        if resolved_mask is None
+        else max(int(resolved_mask.shape[0]), 1)
+    )
 
     frequency_map = {
         string_formatter(word): weight for word, weight in zip(words, weights)
     }
+    min_font_size = style.font_mapping[min(style.font_mapping.keys())]
+    max_font_size = style.font_mapping[max(style.font_mapping.keys())]
 
-    font_sizes = _normalize_weights(weights, base_size=style.font_size)
     wc = WordCloud(
         width=width,
         height=height,
         background_color=style.background_color,
         colormap=colormaps.get_cmap(style.palette),
-        min_font_size=int(font_sizes.min(initial=style.font_size)),
-        max_font_size=int(font_sizes.max(initial=style.font_size * 4)),
+        min_font_size=min_font_size,
+        max_font_size=max_font_size,
         random_state=random_state,
+        mask=resolved_mask,
     ).generate_from_frequencies(frequency_map)
 
-    ax.imshow(wc, interpolation="bilinear")
+    ax.imshow(wc.to_array(), interpolation="bilinear")
 
     if title:
         ax.set_title(title, color=style.font_color, fontsize=style.font_size * 1.5)
@@ -213,7 +235,8 @@ def aplot_wordcloud(
     max_words: int = MAX_RESULTS,
     stopwords: Optional[Iterable[str]] = None,
     random_state: Optional[int] = None,
-    ax: Optional[Axes] = None,
+    ax: Optional[Axes | np.ndarray[Any, np.dtype[Any]]] = None,
+    mask: Optional[np.ndarray] = None,
 ) -> Axes:
     """Plot a word cloud on the provided axes.
 
@@ -235,8 +258,11 @@ def aplot_wordcloud(
         Words to exclude from the visualization. Defaults to ``None``.
     random_state : int, optional
         Seed for word placement. Defaults to ``None``.
-    ax : matplotlib.axes.Axes, optional
+    ax : matplotlib.axes.Axes or numpy.ndarray, optional
         Axes to draw on. Defaults to ``None`` which uses the current axes.
+    mask : numpy.ndarray, optional
+        Two-dimensional mask array defining the drawable region of the word cloud.
+        Defaults to a circular mask generated by :func:`create_circular_mask`.
 
     Returns
     -------
@@ -247,9 +273,15 @@ def aplot_wordcloud(
     ------
     AttributeError
         If required columns are missing from the DataFrame.
+    TypeError
+        If ``ax`` is not a ``matplotlib.axes.Axes`` instance.
     """
     if ax is None:
         ax = cast(Axes, plt.gca())
+    elif isinstance(ax, np.ndarray):
+        raise TypeError("ax must be a single matplotlib Axes instance, not an array.")
+    elif not isinstance(ax, Axes):
+        raise TypeError("ax must be a matplotlib Axes instance.")
 
     words, weights = _prepare_word_frequencies(
         pd_df=pd_df,
@@ -259,7 +291,13 @@ def aplot_wordcloud(
         stopwords=stopwords,
     )
     return _plot_words(
-        ax, words, weights, style=style, title=title, random_state=random_state
+        ax,
+        words,
+        weights,
+        style=style,
+        title=title,
+        random_state=random_state,
+        mask=mask,
     )
 
 
@@ -275,6 +313,7 @@ def fplot_wordcloud(
     figsize: Tuple[float, float] = FIG_SIZE,
     save_path: Optional[str] = None,
     savefig_kwargs: Optional[Dict[str, Any]] = None,
+    mask: Optional[np.ndarray] = None,
 ) -> Figure:
     """Create a new figure with a word cloud.
 
@@ -298,6 +337,9 @@ def fplot_wordcloud(
         Seed for word placement. Defaults to ``None``.
     figsize : tuple of float, optional
         Figure size. Defaults to ``FIG_SIZE``.
+    mask : numpy.ndarray, optional
+        Two-dimensional mask array defining the drawable region of the word cloud.
+        Defaults to a circular mask generated by :func:`create_circular_mask`.
 
     Returns
     -------
@@ -325,6 +367,7 @@ def fplot_wordcloud(
         style=style,
         title=title,
         random_state=random_state,
+        mask=mask,
     )
     fig.patch.set_facecolor(style.background_color)
     fig.tight_layout()

MatplotLibAPI/__init__.py

@@ -35,7 +35,12 @@ from .Timeserie import TIMESERIE_STYLE_TEMPLATE, aplot_timeserie, fplot_timeseri
 from .Sunburst import fplot_sunburst
 from .Treemap import TREEMAP_STYLE_TEMPLATE, fplot_treemap
 from .Waffle import aplot_waffle, fplot_waffle
-from .Wordcloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, fplot_wordcloud
+from .Wordcloud import (
+    WORDCLOUD_STYLE_TEMPLATE,
+    aplot_wordcloud,
+    create_circular_mask,
+    fplot_wordcloud,
+)
 from .accessor import DataFrameAccessor
 
 __all__ = [
@@ -54,6 +59,7 @@ __all__ = [
     "aplot_correlation_matrix",
     "aplot_area",
     "aplot_pie_donut",
+    "create_circular_mask",
     "aplot_waffle",
     "fplot_bubble",
     "fplot_network",

{matplotlibapi-3.2.18.dist-info → matplotlibapi-3.2.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MatplotLibAPI
-Version: 3.2.18
+Version: 3.2.20
 License-File: LICENSE
 Requires-Python: >=3.8
 Requires-Dist: kaleido

{matplotlibapi-3.2.18.dist-info → matplotlibapi-3.2.20.dist-info}/RECORD

@@ -1,6 +1,6 @@
 MatplotLibAPI/Area.py,sha256=Y-tk6Di3Foj3yOGVbbOwDnPtL9rDh-VV2XTeaZcybgk,2095
 MatplotLibAPI/Bar.py,sha256=Y8mP_UWyU2h5T38L7j-Vnt0t9WSeCbV6Gw_-_48x3Bw,2243
-MatplotLibAPI/BoxViolin.py,sha256=zsyfUKYp6wKD30i-LWmwPxtOA7ljjh874xxES_GHZ8M,1947
+MatplotLibAPI/BoxViolin.py,sha256=8nnXGyDwrjiNJOiJHEYEcJMqD6JIF5JT8aZ0y4AXgLY,2008
 MatplotLibAPI/Bubble.py,sha256=xByA6J89L1ye8oiinGQx1jd4PC0vPcBQhxFrKCEXtVM,12814
 MatplotLibAPI/Composite.py,sha256=k4elPk2mucw5oOH2S2GZV6mbHI9N4Nhpnte4mWLHObg,5902
 MatplotLibAPI/Heatmap.py,sha256=SRT8pCKtEaJ1PivxxzCuXp-OBu4ljno2PGB_XXvFxzY,3369
@@ -15,12 +15,12 @@ MatplotLibAPI/Table.py,sha256=jRdnQ0LNA5op65QJhXnXv_v7tBv1JEPLX7qHNd07_is,6448
 MatplotLibAPI/Timeserie.py,sha256=vN8Ed9eC6TcN02LAiSJRzbIW3ZNoBo8ip7lznnK5eG0,10198
 MatplotLibAPI/Treemap.py,sha256=VBBk6MpNXoQtnxFzR1YPhIx6Lz9b7yJNHBMbQDhvefM,4848
 MatplotLibAPI/Waffle.py,sha256=uplRhUBDWUhSwPnI_GzU1O2D_RQXW_0OJ51m01PFKLg,2517
-MatplotLibAPI/Wordcloud.py,sha256=sE6P8vCh8H6bQnaIr4LPW7fd3-OQootfOuM-9-htgv4,10016
-MatplotLibAPI/__init__.py,sha256=6Z51NTmLCoM7P-XPDGVQdtcXtz8S1zZzoByuX_nCpyw,2233
+MatplotLibAPI/Wordcloud.py,sha256=uYH8amxRpMm0y60Ch9nkOl2yXNX-l01NZe2VGIwdZw8,11581
+MatplotLibAPI/__init__.py,sha256=jyMVtJq3rGJ9GmM7mX1dhJcNCCJHJ2-IwtDClRgKBFg,2304
 MatplotLibAPI/_typing.py,sha256=Or3IPNceWKdyEk3CGXJb09FZR_fvT732oF0iWrx1ex8,598
 MatplotLibAPI/_visualization_utils.py,sha256=qIv7c0Mi3qK-saGxmKngw23uWxKFSAYjiH3uYTSr5Po,2215
 MatplotLibAPI/accessor.py,sha256=Wsje4q6bNa_-WAkljqTDWfbWpKcbAy2JKaHir9qZ9Ho,53038
-matplotlibapi-3.2.18.dist-info/METADATA,sha256=75mgiIyrEAbZsWAhIVTl6OzJax5iW6dANKSMdV1a4yE,5888
-matplotlibapi-3.2.18.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-matplotlibapi-3.2.18.dist-info/licenses/LICENSE,sha256=hMErKLb6YZR3lRR5zr-vxeFkvY69QAaafgSpZ5-P1dQ,1067
-matplotlibapi-3.2.18.dist-info/RECORD,,
+matplotlibapi-3.2.20.dist-info/METADATA,sha256=ocDaj9BvTZvdA3hs30komzhrlyfspk6MaZEVmq2q0Xw,5888
+matplotlibapi-3.2.20.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+matplotlibapi-3.2.20.dist-info/licenses/LICENSE,sha256=hMErKLb6YZR3lRR5zr-vxeFkvY69QAaafgSpZ5-P1dQ,1067
+matplotlibapi-3.2.20.dist-info/RECORD,,