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

MatplotLibAPI/Wordcloud.py

@@ -131,6 +131,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 +172,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,8 +214,20 @@ 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)
@@ -195,6 +242,7 @@ def _plot_words(
         min_font_size=int(font_sizes.min(initial=style.font_size)),
         max_font_size=int(font_sizes.max(initial=style.font_size * 4)),
         random_state=random_state,
+        mask=resolved_mask,
     ).generate_from_frequencies(frequency_map)
 
     ax.imshow(wc, interpolation="bilinear")
@@ -214,6 +262,7 @@ def aplot_wordcloud(
     stopwords: Optional[Iterable[str]] = None,
     random_state: Optional[int] = None,
     ax: Optional[Axes] = None,
+    mask: Optional[np.ndarray] = None,
 ) -> Axes:
     """Plot a word cloud on the provided axes.
 
@@ -237,6 +286,9 @@ def aplot_wordcloud(
         Seed for word placement. Defaults to ``None``.
     ax : matplotlib.axes.Axes, 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
     -------
@@ -259,7 +311,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 +333,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 +357,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 +387,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.19.dist-info}/METADATA

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

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

@@ -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=lxBeB61dPbjc2WulZawCiCmjf_s7KiPib1zW70V9nH8,12123
+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.19.dist-info/METADATA,sha256=0VPbE_llP391GgQWHC2DK99Gkl5E1xZQzPcPxC1WjEM,5888
+matplotlibapi-3.2.19.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+matplotlibapi-3.2.19.dist-info/licenses/LICENSE,sha256=hMErKLb6YZR3lRR5zr-vxeFkvY69QAaafgSpZ5-P1dQ,1067
+matplotlibapi-3.2.19.dist-info/RECORD,,