Skip to main content

MatplotLibAPI

MatplotLibAPI provides a small, high-level plotting API for pandas DataFrames. It covers common analytical charts, tables, network visualizations, hierarchical charts, and an optional MCP server for agent-driven rendering.

Installation

pip install MatplotLibAPI

For MCP support:

pip install "MatplotLibAPI[mcp]"

Quick start

Supported convenience functions are imported from the package root:

import pandas as pd
from MatplotLibAPI import fplot_bar

sales = pd.DataFrame(
    {
        "product": ["A", "A", "B", "B"],
        "region": ["North", "South", "North", "South"],
        "revenue": [12, 9, 15, 11],
    }
)

fig = fplot_bar(
    sales,
    category="product",
    value="revenue",
    group="region",
    stacked=True,
)
fig.show()

Supported public API

The names below are the stable package-root import surface defined by MatplotLibAPI.__all__.

Symbol Purpose
CorrelationMethod Supported correlation methods.
DataFrameAccessor pandas DataFrame plotting accessor.
fplot_area Area chart.
fplot_bar Bar or stacked-bar chart.
fplot_box_violin Box or violin chart.
fplot_correlation_matrix Correlation matrix.
fplot_heatmap Pivoted heatmap.
fplot_histogram_kde Histogram with optional KDE.
fplot_pie_donut Pie or donut chart.
fplot_sankey Sankey diagram.
fplot_sunburst Sunburst chart.
fplot_table Matplotlib table.
fplot_timeserie Time-series chart.
fplot_treemap Treemap.
fplot_waffle Waffle chart.
fplot_wordcloud Word cloud.

Use module-level imports only for specialized classes or legacy helpers that are not part of the package-root contract:

from MatplotLibAPI.bubble import Bubble
from MatplotLibAPI.network import NetworkGraph
from MatplotLibAPI.Pivot import plot_pivoted_bars

Examples

Area

import pandas as pd
from MatplotLibAPI import fplot_area

frame = pd.DataFrame(
    {
        "quarter": ["Q1", "Q2", "Q1", "Q2"],
        "segment": ["Free", "Free", "Pro", "Pro"],
        "subscriptions": [80, 95, 30, 45],
    }
)
fig = fplot_area(frame, x="quarter", y="subscriptions", label="segment", stacked=True)

Histogram and KDE

import pandas as pd
from MatplotLibAPI import fplot_histogram_kde

frame = pd.DataFrame({"waiting_time_minutes": [3, 5, 5, 8, 10, 13]})
fig = fplot_histogram_kde(
    frame,
    column="waiting_time_minutes",
    bins=6,
    kde=True,
)

Box or violin

import pandas as pd
from MatplotLibAPI import fplot_box_violin

frame = pd.DataFrame(
    {
        "department": ["Sales", "Sales", "Product", "Product"],
        "score": [7.2, 8.1, 8.8, 9.0],
    }
)
fig = fplot_box_violin(
    frame,
    column="score",
    category="department",
    use_violin=True,
)

Heatmap and correlation matrix

import pandas as pd
from MatplotLibAPI import fplot_correlation_matrix, fplot_heatmap

engagement = pd.DataFrame(
    {
        "month": ["Jan", "Jan", "Feb", "Feb"],
        "channel": ["Email", "Social", "Email", "Social"],
        "engagements": [120, 200, 150, 230],
    }
)
metrics = pd.DataFrame({"a": [1, 2, 3], "b": [2, 4, 5]})

heatmap = fplot_heatmap(
    engagement,
    index="month",
    columns="channel",
    values="engagements",
)
correlation = fplot_correlation_matrix(metrics)

Pie, waffle, and Sankey

import pandas as pd
from MatplotLibAPI import fplot_pie_donut, fplot_sankey, fplot_waffle

shares = pd.DataFrame(
    {"device": ["Desktop", "Mobile"], "sessions": [40, 60]}
)
flows = pd.DataFrame(
    {"source": ["Visit", "Visit"], "target": ["Buy", "Leave"], "value": [35, 65]}
)

pie = fplot_pie_donut(shares, category="device", value="sessions", donut=True)
waffle = fplot_waffle(shares, category="device", value="sessions")
sankey = fplot_sankey(flows, source="source", target="target", value="value")

Table and time series

import pandas as pd
from MatplotLibAPI import fplot_table, fplot_timeserie

frame = pd.DataFrame(
    {
        "date": ["2026-01-01", "2026-02-01"],
        "group": ["A", "A"],
        "value": [10, 14],
    }
)

table = fplot_table(pd_df=frame, cols=["date", "value"])
series = fplot_timeserie(pd_df=frame, label="group", x="date", y="value")

Treemap, sunburst, and word cloud

import pandas as pd
from MatplotLibAPI import fplot_sunburst, fplot_treemap, fplot_wordcloud

hierarchy = pd.DataFrame(
    {
        "labels": ["All", "A", "B"],
        "parents": ["", "All", "All"],
        "values": [30, 10, 20],
    }
)
words = pd.DataFrame({"word": ["simple", "reliable"], "weight": [5, 3]})

sunburst = fplot_sunburst(
    hierarchy,
    labels="labels",
    parents="parents",
    values="values",
)
treemap = fplot_treemap(
    pd_df=pd.DataFrame({"path": ["A", "B"], "values": [10, 20]}),
    path="path",
    values="values",
)
cloud = fplot_wordcloud(words, text_column="word", weight_column="weight")

Specialized object APIs

Bubble, NetworkGraph, and the pivot helpers remain intentionally module-level APIs:

import pandas as pd
from MatplotLibAPI.bubble import Bubble
from MatplotLibAPI.network import NetworkGraph
from MatplotLibAPI.Pivot import plot_pivoted_bars

bubble_data = pd.DataFrame(
    {"country": ["A", "B"], "gdp": [10, 20], "life": [70, 80], "population": [5, 8]}
)
bubble = Bubble(
    pd_df=bubble_data,
    label="country",
    x="gdp",
    y="life",
    z="population",
).fplot_w()

edges = pd.DataFrame(
    {"source": ["A", "B"], "target": ["B", "C"], "weight": [1, 2]}
)
network = NetworkGraph.from_pandas_edgelist(
    edges,
    source="source",
    target="target",
    edge_weight_col="weight",
).fplot_w(edge_weight_col="weight")

pivot_data = pd.DataFrame(
    {"category": ["A", "B"], "date": ["2026-01", "2026-01"], "value": [1, 2]}
)
axes = plot_pivoted_bars(
    data=pivot_data,
    label="category",
    x="date",
    y="value",
)

Import migration

Prefer package-root imports for every symbol in the public API table:

# Before
from MatplotLibAPI.bar import fplot_bar
from MatplotLibAPI.heatmap import fplot_heatmap

# Supported public imports
from MatplotLibAPI import fplot_bar, fplot_heatmap

Existing module imports continue to work, but package-root imports are the documented stable contract. Specialized APIs that are not exported in MatplotLibAPI.__all__ should continue to use their module paths.

Sample data

Generate the repository sample CSV files with:

python scripts/generate_sample_data.py

MCP integration

Start the optional stdio server with:

matplotlibapi-mcp

The server exposes dedicated plotting tools, a generic plot_module tool, and describe_plot_modules for capability discovery. Rendering tools accept either a CSV path or in-memory table records and return PNG bytes.

Development

Run the repository quality checks before opening a pull request:

black --check src tests
pydocstyle src
pyright
pytest --cov=MatplotLibAPI --cov-report=term-missing
python -m build
python -m twine check dist/*

Metadata

Release files for MatplotLibAPI 4.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for MatplotLibAPI 4.1.0
File Size Uploaded Provenance Actions
matplotlibapi-4.1.0.tar.gz 69.9 kB Without provenance Details for matplotlibapi-4.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for MatplotLibAPI 4.1.0
File Interpreter ABI Platform Actions
matplotlibapi-4.1.0-py3-none-any.whl Python 3 none any Details for matplotlibapi-4.1.0-py3-none-any.whl

Total release size: 136.4 kB

Release files / matplotlibapi-4.1.0.tar.gz

Download URL matplotlibapi-4.1.0.tar.gz
Size 69.9 kB
Tags Source
SHA-256 checksum
How to use checksums
781004731b7fd565c454ac9eb7a20de8009076358c1beb348749fe11950430af
BLAKE2b-256 checksum
How to use checksums
59436043153332f5215b783d83ce6576c56e08d7b31f0e12c646fc58cae528a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / matplotlibapi-4.1.0-py3-none-any.whl

Download URL matplotlibapi-4.1.0-py3-none-any.whl
Size 66.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e57cac7bf8d7289ae6fbeb0fb09d06daed5c02aeecd64ac56c0253194f1c3dcd
BLAKE2b-256 checksum
How to use checksums
2c2c58fbdec3959cfc83190bb8b7839350bfc3a8b84b6adaf6000ba5f7272794
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for MatplotLibAPI 4.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page