MatplotLibAPI 3.2.12__tar.gz → 3.2.14__tar.gz

matplotlibapi-3.2.14/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: Python CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[dev]
+
+    - name: Run style checks
+      run: |
+        pydocstyle MatplotLibAPI
+        black --check .
+
+    - name: Run static type analysis
+      run: |
+        pyright MatplotLibAPI
+
+    - name: Run tests with coverage
+      run: |
+        pytest -q --cov=MatplotLibAPI --cov-report=term-missing --cov-fail-under=70

matplotlibapi-3.2.14/.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

matplotlibapi-3.2.14/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.vscode
+.env
+.pytest_cache
+.benchmarks
+scratch*
+data/
+# Python build artifacts
+*.egg-info/
+dist/
+build/
+
+# Python cache files
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/

matplotlibapi-3.2.14/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+These instructions apply to any automated agent contributing to this repository.
+
+## 1. Code Style
+
+- Use standard PEP 8 formatting for all Python code.
+- Write commit messages in the imperative mood (e.g., "Add feature" not "Added feature").
+- Keep the implementation Pythonic and maintainable.
+
+## 2. Docstring Style
+
+- Document all public classes, parameters, methods, and functions.
+- Use **NumPy-style** docstrings following [PEP 257](httpshttps://peps.python.org/pep-0257/) conventions.
+- **Do not** use `:param` / `:type` syntax (reST/Sphinx style) or Google-style `Args`.
+- Always include type hints in function signatures.
+- Begin docstrings with a **short, one-line summary**, followed by a blank line and an optional extended description.
+- Use the following NumPy-style sections when applicable:
+  - `Parameters`
+  - `Returns`
+  - `Raises`
+  - `Examples`
+- **For classes, the main docstring should include a `Methods` section summarizing each public method and its one-line description.**
+- For optional parameters, note the default value in the description.
+- Use present tense and active voice (“Return…”, “Fetch…”).
+
+## 3. Code Quality and Testing
+
+Before running tests, install the development dependencies declared in `pyproject.toml`:
+
+```bash
+pip install -e .[dev]
+```
+
+To ensure your changes will pass the automated checks in our Continuous Integration (CI) pipeline, run the following commands locally before committing. All checks must pass.
+
+**Style Checks:**
+```bash
+pydocstyle MatplotLibAPI
+black --check .
+```
+
+**Static Type Analysis:**
+```bash
+pyright MatplotLibAPI
+```
+
+**Unit Tests and Coverage:**
+```bash
+pytest -q --cov=MatplotLibAPI --cov-report=term-missing --cov-fail-under=70
+```
+
+## 4. Directory Layout
+
+- Production code lives in `MatplotLibAPI/`.
+- Tests live in `tests/`.
+- Keep imports relative within the package (e.g., `from MatplotLibAPI...`).
+
+## 5. Pull Request Messages
+
+Each pull request should include:
+
+1. **Summary** – brief description of the change.
+2. **Testing** – commands run and confirmation that the tests passed.
+
+Example PR body:
+
+```
+### Summary
+- add new helper to utils.list
+- expand tests for list chunking
+
+### Testing
+- `pytest` (all tests passed)
+```
+
+## 6. General Guidelines
+
+- Avoid pushing large data files to the repository.
+- Prefer small, focused commits over sweeping changes.
+- Update or add tests whenever you modify functionality.

matplotlibapi-3.2.14/MatplotLibAPI/Bubble.py

@@ -0,0 +1,453 @@
+"""Bubble chart plotting helpers.
+
+Provides functions to create and render bubble charts using seaborn and matplotlib,
+with customizable styling via `StyleTemplate`.
+"""
+
+from typing import Dict, Optional, Tuple, cast
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from matplotlib.ticker import NullLocator
+
+from .StyleTemplate import (
+    BUBBLE_STYLE_TEMPLATE,
+    MAX_RESULTS,
+    StyleTemplate,
+    bmk_formatter,
+    format_func,
+    generate_ticks,
+    percent_formatter,
+    string_formatter,
+    validate_dataframe,
+    DynamicFuncFormatter,
+    FormatterFunc,
+)
+
+
+def _prepare_bubble_data(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    sort_by: Optional[str],
+    ascending: bool,
+    max_values: int,
+    center_to_mean: bool,
+    style: StyleTemplate,
+) -> pd.DataFrame:
+    """Prepare data for bubble chart.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        Input DataFrame.
+    label : str
+        Column name for bubble labels.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    z : str
+        Column name for bubble sizes.
+    sort_by : Optional[str]
+        Column to sort by.
+    ascending : bool
+        Sort order.
+    max_values : int
+        Maximum number of bubbles to display.
+    center_to_mean : bool
+        Whether to center x-axis values around the mean.
+    style : StyleTemplate
+        Styling for the plot.
+
+    Returns
+    -------
+    pd.DataFrame
+        Prepared DataFrame for plotting.
+
+    Raises
+    ------
+    AttributeError
+        If required columns are missing from the DataFrame.
+    """
+    validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
+    sort_col = sort_by or z
+
+    plot_df = (
+        pd_df[[label, x, y, z]]
+        .sort_values(by=[sort_col], ascending=ascending)  # type: ignore
+        .head(max_values)
+        .copy()
+    )
+
+    if center_to_mean:
+        plot_df[x] -= plot_df[x].mean()
+
+    plot_df["quintile"] = pd.qcut(plot_df[z], 5, labels=False, duplicates="drop")
+    plot_df["fontsize"] = plot_df["quintile"].map(style.font_mapping)  # type: ignore
+    return plot_df
+
+
+def _setup_bubble_axes(
+    ax: Axes,
+    style: StyleTemplate,
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    format_funcs: Optional[Dict[str, Optional[FormatterFunc]]],
+) -> None:
+    """Configure axes for the bubble chart.
+
+    Parameters
+    ----------
+    ax : Axes
+        Matplotlib axes object.
+    style : StyleTemplate
+        Styling for the plot.
+    pd_df : pd.DataFrame
+        DataFrame used for plotting.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    format_funcs : Optional[Dict[str, Optional[FormatterFunc]]]
+        Functions to format axis tick labels.
+    """
+    ax.set_facecolor(style.background_color)
+
+    if style.xscale:
+        ax.set(xscale=style.xscale)
+    if style.yscale:
+        ax.set(yscale=style.yscale)
+
+    # X-axis ticks and formatting
+    x_min, x_max = cast(float, pd_df[x].min()), cast(float, pd_df[x].max())
+    ax.xaxis.set_ticks(generate_ticks(x_min, x_max, num_ticks=style.x_ticks))
+    ax.xaxis.grid(True, "major", linewidth=0.5, color=style.font_color)
+    if format_funcs and (fmt_x := format_funcs.get(x)):
+        ax.xaxis.set_major_formatter(DynamicFuncFormatter(fmt_x))
+
+    # Y-axis ticks and formatting
+    y_min, y_max = cast(float, pd_df[y].min()), cast(float, pd_df[y].max())
+    ax.yaxis.set_ticks(generate_ticks(y_min, y_max, num_ticks=style.y_ticks))
+    if style.yscale == "log":
+        ax.yaxis.set_minor_locator(NullLocator())
+    else:
+        ax.minorticks_off()
+    ax.yaxis.grid(True, "major", linewidth=0.5, color=style.font_color)
+    if format_funcs and (fmt_y := format_funcs.get(y)):
+        ax.yaxis.set_major_formatter(DynamicFuncFormatter(fmt_y))
+
+    ax.tick_params(
+        axis="both", which="major", colors=style.font_color, labelsize=style.font_size
+    )
+
+
+def _draw_bubbles(
+    ax: Axes, plot_df: pd.DataFrame, x: str, y: str, z: str, style: StyleTemplate
+) -> None:
+    """Draw bubbles on the axes.
+
+    Parameters
+    ----------
+    ax : Axes
+        Matplotlib axes object.
+    plot_df : pd.DataFrame
+        DataFrame with data for plotting.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    z : str
+        Column name for bubble sizes.
+    style : StyleTemplate
+        Styling for the plot.
+    """
+    sns.scatterplot(
+        data=plot_df,
+        x=x,
+        y=y,
+        size=z,
+        hue="quintile",
+        sizes=(100, 2000),
+        legend=False,
+        palette=sns.color_palette(style.palette, as_cmap=True),
+        edgecolor=style.background_color,
+        ax=ax,
+    )
+
+
+def _draw_bubble_labels(
+    ax: Axes,
+    plot_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    style: StyleTemplate,
+    format_funcs: Optional[Dict[str, Optional[FormatterFunc]]],
+) -> None:
+    """Draw labels for each bubble.
+
+    Parameters
+    ----------
+    ax : Axes
+        Matplotlib axes object.
+    plot_df : pd.DataFrame
+        DataFrame with data for plotting.
+    label : str
+        Column name for bubble labels.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    style : StyleTemplate
+        Styling for the plot.
+    format_funcs : Optional[Dict[str, Optional[FormatterFunc]]]
+        Functions to format bubble labels.
+    """
+    for _, row in plot_df.iterrows():
+        x_val, y_val, label_val = row[x], row[y], str(row[label])
+        if format_funcs and (fmt_label := format_funcs.get(label)):
+            label_val = fmt_label(label_val, None)
+        ax.text(
+            cast(float, x_val),
+            cast(float, y_val),
+            label_val,
+            ha="center",
+            fontsize=row["fontsize"],
+            color=style.font_color,
+        )
+
+
+def _draw_mean_lines(
+    ax: Axes,
+    plot_df: pd.DataFrame,
+    x: str,
+    y: str,
+    hline: bool,
+    vline: bool,
+    style: StyleTemplate,
+) -> None:
+    """Draw horizontal and vertical mean lines.
+
+    Parameters
+    ----------
+    ax : Axes
+        Matplotlib axes object.
+    plot_df : pd.DataFrame
+        DataFrame with data for plotting.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    hline : bool
+        Whether to draw a horizontal line at the mean of y.
+    vline : bool
+        Whether to draw a vertical line at the mean of x.
+    style : StyleTemplate
+        Styling for the plot.
+    """
+    if vline:
+        ax.axvline(
+            int(cast(float, plot_df[x].mean())), linestyle="--", color=style.font_color
+        )
+    if hline:
+        ax.axhline(
+            int(cast(float, plot_df[y].mean())), linestyle="--", color=style.font_color
+        )
+
+
+def aplot_bubble(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    title: Optional[str] = None,
+    style: StyleTemplate = BUBBLE_STYLE_TEMPLATE,
+    max_values: int = MAX_RESULTS,
+    center_to_mean: bool = False,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    hline: bool = False,
+    vline: bool = False,
+    ax: Optional[Axes] = None,
+) -> Axes:
+    """Plot a bubble chart onto the given axes.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        DataFrame containing the data to plot.
+    label : str
+        Column name used for labeling bubbles.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    z : str
+        Column name for bubble sizes.
+    title : str, optional
+        Plot title.
+    style : StyleTemplate, optional
+        Plot styling options. The default is `BUBBLE_STYLE_TEMPLATE`.
+    max_values : int, optional
+        Max number of rows to display. The default is `MAX_RESULTS`.
+    center_to_mean : bool, optional
+        Whether to center x values around their mean. The default is `False`.
+    sort_by : str, optional
+        Column to sort by before slicing.
+    ascending : bool, optional
+        Sort order. The default is `False`.
+    hline : bool, optional
+        Whether to draw a horizontal line at the mean of y. The default is `False`.
+    vline : bool, optional
+        Whether to draw a vertical line at the mean of x. The default is `False`.
+    ax : Axes, optional
+        Existing matplotlib axes to use. If None, uses current axes.
+
+    Returns
+    -------
+    Axes
+        The matplotlib Axes object containing the bubble chart.
+
+    Raises
+    ------
+    AttributeError
+        If required columns are not in the DataFrame.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> import matplotlib.pyplot as plt
+    >>> from MatplotLibAPI.Bubble import aplot_bubble
+    >>> data = {
+    ...     'country': ['A', 'B', 'C', 'D'],
+    ...     'gdp_per_capita': [45000, 42000, 52000, 48000],
+    ...     'life_expectancy': [81, 78, 83, 82],
+    ...     'population': [10, 20, 5, 30]
+    ... }
+    >>> df = pd.DataFrame(data)
+    >>> fig, ax = plt.subplots()
+    >>> aplot_bubble(df, label='country', x='gdp_per_capita', y='life_expectancy', z='population', ax=ax)
+    """
+    if ax is None:
+        ax = cast(Axes, plt.gca())
+
+    plot_df = _prepare_bubble_data(
+        pd_df, label, x, y, z, sort_by, ascending, max_values, center_to_mean, style
+    )
+
+    format_funcs = format_func(style.format_funcs, label=label, x=x, y=y, z=z)
+
+    _setup_bubble_axes(ax, style, plot_df, x, y, format_funcs)
+
+    _draw_bubbles(ax, plot_df, x, y, z, style)
+
+    _draw_mean_lines(ax, plot_df, x, y, hline, vline, style)
+
+    _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)
+
+    return ax
+
+
+def fplot_bubble(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    title: Optional[str] = None,
+    style: StyleTemplate = BUBBLE_STYLE_TEMPLATE,
+    max_values: int = MAX_RESULTS,
+    center_to_mean: bool = False,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    hline: bool = False,
+    vline: bool = False,
+    figsize: Tuple[float, float] = (19.2, 10.8),
+) -> Figure:
+    """Create a new matplotlib Figure with a bubble chart.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        DataFrame containing the data to plot.
+    label : str
+        Column name for bubble labels.
+    x : str
+        Column name for x-axis values.
+    y : str
+        Column name for y-axis values.
+    z : str
+        Column name for bubble sizes.
+    title : str, optional
+        Title for the chart. The default is ``None``.
+    style : StyleTemplate, optional
+        Plot styling. The default is `BUBBLE_STYLE_TEMPLATE`.
+    max_values : int, optional
+        Max number of rows to display. The default is `MAX_RESULTS`.
+    center_to_mean : bool, optional
+        Whether to center x around its mean. The default is `False`.
+    sort_by : str, optional
+        Column to sort by.
+    ascending : bool, optional
+        Sort order. The default is `False`.
+    hline : bool, optional
+        Draw horizontal line at mean y. The default is `False`.
+    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).
+
+    Returns
+    -------
+    Figure
+        A matplotlib Figure object containing the bubble chart.
+
+    Raises
+    ------
+    AttributeError
+        If required columns are not in the DataFrame.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> from MatplotLibAPI.Bubble import fplot_bubble
+    >>> data = {
+    ...     'country': ['A', 'B', 'C', 'D'],
+    ...     'gdp_per_capita': [45000, 42000, 52000, 48000],
+    ...     'life_expectancy': [81, 78, 83, 82],
+    ...     'population': [10, 20, 5, 30]
+    ... }
+    >>> df = pd.DataFrame(data)
+    >>> fig = fplot_bubble(df, label='country', x='gdp_per_capita', y='life_expectancy', z='population')
+    """
+    fig = cast(Figure, plt.figure(figsize=figsize))
+    fig.patch.set_facecolor(style.background_color)
+    ax = fig.add_subplot()
+    aplot_bubble(
+        pd_df=pd_df,
+        label=label,
+        x=x,
+        y=y,
+        z=z,
+        title=title,
+        style=style,
+        max_values=max_values,
+        center_to_mean=center_to_mean,
+        sort_by=sort_by,
+        ascending=ascending,
+        hline=hline,
+        vline=vline,
+        ax=ax,
+    )
+    return fig