MatplotLibAPI 3.2.18__tar.gz → 3.2.20__tar.gz

{matplotlibapi-3.2.18 → matplotlibapi-3.2.20}/.github/workflows/ci.yml

@@ -31,12 +31,12 @@ jobs:
 
     - name: Run style checks
       run: |
-        pydocstyle MatplotLibAPI
+        pydocstyle .
         black --check .
 
     - name: Run static type analysis
       run: |
-        pyright MatplotLibAPI
+        pyright .
 
     - name: Run tests with coverage
       run: |

{matplotlibapi-3.2.18 → matplotlibapi-3.2.20}/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-3.2.18 → matplotlibapi-3.2.20}/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-3.2.18 → matplotlibapi-3.2.20}/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 → matplotlibapi-3.2.20}/PKG-INFO

@@ -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 → matplotlibapi-3.2.20}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 [project]
 name = "MatplotLibAPI"
-version = "3.2.18"
+version = "3.2.20"
 readme = "README.md"
 requires-python = ">=3.8"
 dependencies = [

{matplotlibapi-3.2.18 → matplotlibapi-3.2.20}/scripts/generate_sample_data.py

@@ -97,7 +97,7 @@ def generate_treemap_data():
     }
     df = pd.DataFrame(data)
     # For treemap, we need a path-like structure. We will create it here.
-    df["path"] = df["parent"] + "/" + df["location"]
+    df["path"] = df["parent"].str.cat(df["location"], sep="/")
     df["path"] = df["path"].str.lstrip("/")
     df.to_csv("data/treemap.csv", index=False)
 
@@ -169,7 +169,6 @@ def generate_wordcloud_data():
 
 def generate_bar_data():
     """Generate and save sample data for bar and stacked bar charts."""
-
     data = {
         "product": ["Gadget", "Gadget", "Gadget", "Widget", "Widget", "Widget"],
         "region": ["North", "South", "West", "North", "South", "West"],
@@ -181,7 +180,6 @@ def generate_bar_data():
 
 def generate_histogram_data():
     """Generate and save sample data for histogram and KDE plots."""
-
     data = {
         "waiting_time_minutes": [
             5,
@@ -212,7 +210,6 @@ def generate_histogram_data():
 
 def generate_box_violin_data():
     """Generate and save sample data for box and violin plots."""
-
     data = {
         "department": [
             "Engineering",
@@ -243,7 +240,6 @@ def generate_box_violin_data():
 
 def generate_heatmap_and_correlation_data():
     """Generate and save sample data for heatmaps and correlation matrices."""
-
     data = {
         "month": ["Jan", "Jan", "Feb", "Feb", "Mar", "Mar", "Apr", "Apr"],
         "channel": [
@@ -269,7 +265,6 @@ def generate_heatmap_and_correlation_data():
 
 def generate_area_data():
     """Generate and save sample data for area charts."""
-
     data = {
         "quarter": ["Q1", "Q2", "Q3", "Q4", "Q1", "Q2", "Q3", "Q4"],
         "segment": [
@@ -290,7 +285,6 @@ def generate_area_data():
 
 def generate_pie_waffle_data():
     """Generate and save sample data for pie, donut, and waffle charts."""
-
     data = {
         "device": ["Desktop", "Mobile", "Tablet", "Other"],
         "sessions": [5200, 8900, 1300, 600],
@@ -302,7 +296,6 @@ def generate_pie_waffle_data():
 
 def generate_sankey_data():
     """Generate and save sample data for Sankey diagrams."""
-
     data = {
         "source": ["Homepage", "Homepage", "Landing Page", "Landing Page", "Cart"],
         "target": ["Landing Page", "Product", "Product", "Signup", "Checkout"],

matplotlibapi-3.2.20/tests/__init__.py

@@ -0,0 +1 @@
+"""Public test for MatplotLibAPI."""

{matplotlibapi-3.2.18 → matplotlibapi-3.2.20}/tests/conftest.py

@@ -2,7 +2,7 @@
 
 import os
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, Generator
 
 import pandas as pd
 import pytest
@@ -13,7 +13,6 @@ from scripts import generate_sample_data
 @pytest.fixture(scope="session")
 def sample_data_dir(tmp_path_factory: pytest.TempPathFactory) -> Path:
     """Generate sample CSV files in an isolated directory for tests."""
-
     base_dir = tmp_path_factory.mktemp("sample_data")
     cwd = os.getcwd()
     os.chdir(base_dir)
@@ -28,7 +27,7 @@ def sample_data_dir(tmp_path_factory: pytest.TempPathFactory) -> Path:
 @pytest.fixture(scope="session")
 def load_sample_df(
     sample_data_dir: Path,
-) -> Callable[[str, Any], pd.DataFrame]:
+) -> Callable[..., pd.DataFrame]:
     """Return a loader that reads generated sample CSVs into dataframes."""
 
     def _loader(filename: str, **kwargs: Any) -> pd.DataFrame:
@@ -38,9 +37,8 @@ def load_sample_df(
 
 
 @pytest.fixture(autouse=True)
-def close_matplotlib_figures() -> None:
+def close_matplotlib_figures() -> Generator[None, None, None]:
     """Close any matplotlib figures created during a test."""
-
     yield
 
     import matplotlib.pyplot as plt

matplotlibapi-3.2.20/tests/test_wordcloud.py

@@ -0,0 +1,77 @@
+"""Tests for word cloud visualizations."""
+
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+import numpy as np
+
+from MatplotLibAPI.Wordcloud import (
+    aplot_wordcloud,
+    create_circular_mask,
+    fplot_wordcloud,
+)
+
+
+def test_fplot_wordcloud(load_sample_df):
+    """Render a word cloud figure from sample data."""
+
+    df = load_sample_df("wordcloud.csv")
+
+    fig = fplot_wordcloud(
+        pd_df=df, text_column="country", weight_column="population", random_state=42
+    )
+
+    assert isinstance(fig, Figure)
+    default_mask = create_circular_mask(size=300)
+    image = fig.axes[0].images[0].get_array()
+    assert image is not None
+    assert tuple(image.shape[:2]) == default_mask.shape
+
+
+def test_fplot_wordcloud_with_mask(load_sample_df):
+    """Render a word cloud using a circular mask to constrain placement."""
+
+    df = load_sample_df("wordcloud.csv")
+    mask = create_circular_mask(size=200)
+
+    fig = fplot_wordcloud(
+        pd_df=df,
+        text_column="country",
+        weight_column="population",
+        random_state=0,
+        mask=mask,
+    )
+
+    image = fig.axes[0].images[0].get_array()
+    assert image is not None
+    assert tuple(image.shape[:2]) == mask.shape
+
+
+def test_aplot_wordcloud(load_sample_df):
+    """Render a word cloud onto an existing axes object."""
+
+    df = load_sample_df("wordcloud.csv")
+    fig, ax = plt.subplots()
+
+    result_ax = aplot_wordcloud(
+        ax=ax,
+        pd_df=df,
+        text_column="country",
+        weight_column="population",
+        random_state=42,
+    )
+
+    assert result_ax is not None
+    assert ax is result_ax
+    image = result_ax.images[0].get_array()
+    assert image is not None
+    assert image.shape[0] > 0 and image.shape[1] > 0
+
+
+def test_create_circular_mask():
+    """Verify circular mask generation."""
+
+    mask = create_circular_mask(size=100, radius=40)
+    assert mask.shape == (100, 100)
+    assert mask.dtype == np.uint8
+    assert np.sum(mask == 0) > 0
+    assert np.sum(mask == 255) > 0

matplotlibapi-3.2.18/tests/test_wordcloud.py

@@ -1,17 +0,0 @@
-"""Tests for word cloud visualizations."""
-
-from matplotlib.figure import Figure
-
-from MatplotLibAPI.Wordcloud import fplot_wordcloud
-
-
-def test_fplot_wordcloud(load_sample_df):
-    """Render a word cloud figure from sample data."""
-
-    df = load_sample_df("wordcloud.csv")
-
-    fig = fplot_wordcloud(
-        pd_df=df, text_column="country", weight_column="population", random_state=42
-    )
-
-    assert isinstance(fig, Figure)