Skip to main content

MatplotLibAPI

MatplotLibAPI is a Python library that simplifies the process of creating various types of plots from pandas DataFrames. It provides a high-level API for generating bubble charts, network graphs, pivot tables, tables, time series plots, treemaps, and sunburst charts.

Installation

To install the library, you can use pip:

pip install MatplotLibAPI

Generating Sample Data

The examples in this README use sample data that can be generated by running the generate_sample_data.py script:

python scripts/generate_sample_data.py

This will create a data directory with CSV files for each plot type.

Usage

Here's a simple example of how to create a bubble chart using the object-based API with a sample CSV file:

import pandas as pd
import matplotlib.pyplot as plt
from MatplotLibAPI.bubble import Bubble

# Load the sample data
df = pd.read_csv('data/bubble.csv')

# Build and render the bubble chart
fig = Bubble(
    pd_df=df,
    label='country',
    x='gdp_per_capita',
    y='population',
    z='population',
).fplot_w(title='Country Statistics')

# Display the plot
plt.show()

MCP Integration

You can run a dedicated MCP server that exposes MatplotLibAPI plotting tools for LLM agents.

  1. Install MCP dependencies:
pip install -e .[mcp]
  1. Start the MCP server over stdio:
matplotlibapi-mcp

Tool surface

The MCP server provides these tools:

  • plot_bubble: dedicated bubble-chart rendering.
  • plot_network: dedicated network-chart rendering.
  • plot_module: generic module renderer for bar, histogram, box_violin, heatmap, correlation_matrix, area, pie, waffle, sankey, table, timeserie, wordcloud, treemap, and sunburst.
  • Explicit module endpoints such as plot_bar, plot_heatmap, plot_sankey, plot_treemap, and others for direct LLM tool selection with no module-dispatch step.
  • describe_plot_modules: discoverability endpoint that returns supported modules, shared input contract, parameter hints, and dedicated-tool mapping.

All rendering tools accept either:

  • csv_path: filesystem path to a CSV file, or
  • table: in-memory records (list[dict]).

All rendering tools return PNG bytes (octet payload) for downstream transport.

For LLM orchestration, explicit endpoints are generally easier to select and ground (for example plot_heatmap rather than plot_module + plot_module="heatmap"). Keep plot_module for dynamic clients that need one generic surface.

Discoverability-first workflow

For dynamic clients and agent exploration, use this sequence:

  1. Call describe_plot_modules.
  2. Select a module from supported_plot_modules.
  3. Read recommended keys from parameter_hints[module_name].
  4. Call plot_module with params + csv_path or table.

If a module key is invalid, plot_module returns a clear error with supported values.

Example generic call

Example payload for plot_module with in-memory table records:

{
  "plot_module": "heatmap",
  "table": [
    {"month": "Jan", "channel": "Email", "engagements": 120},
    {"month": "Jan", "channel": "Social", "engagements": 200}
  ],
  "params": {
    "x": "month",
    "y": "channel",
    "value": "engagements",
    "title": "Engagement Heatmap"
  }
}

The package exposes a single MCP entry point: matplotlibapi-mcp.

Plot Types

The library supports the following plot types:

  • Bubble (Scatter plot)
  • Bar / Stacked Bar
  • Histogram + KDE
  • Box / Violin
  • Heatmap / Correlation Matrix
  • Area
  • Pie / Donut
  • Waffle
  • Sankey
  • Network (Graph)
  • Pivot
  • Table
  • Timeserie
  • Treemap
  • Sunburst

Examples with Sample Data

This repository includes a data directory with sample CSV files for each plot type. Here's how you can use them:

Bubble Chart

import pandas as pd
from MatplotLibAPI.bubble import Bubble

df = pd.read_csv('data/bubble.csv')
fig = Bubble(
    pd_df=df,
    label='country',
    x='gdp_per_capita',
    y='life_expectancy',
    z='population',
).fplot_w()
fig.show()

Network Graph

import pandas as pd
from MatplotLibAPI.network import NetworkGraph

df = pd.read_csv('data/network.csv')
graph = NetworkGraph.from_pandas_edgelist(
    df,
    source='city_a',
    target='city_b',
    edge_weight_col='distance_km',
)
fig = graph.fplot_w(title='City Network', edge_weight_col='distance_km')
fig.show()

Bar / Stacked Bar

import pandas as pd
from MatplotLibAPI import fplot_bar

df = pd.read_csv('data/bar.csv')
fig = fplot_bar(df, category='product', value='revenue', group='region', stacked=True)
fig.show()

Histogram + KDE

import pandas as pd
from MatplotLibAPI import fplot_histogram_kde

df = pd.read_csv('data/histogram.csv')
fig = fplot_histogram_kde(df, column='waiting_time_minutes', bins=8, kde=True)
fig.show()

Box / Violin

import pandas as pd
from MatplotLibAPI import fplot_box_violin

df = pd.read_csv('data/box_violin.csv')
fig = fplot_box_violin(df, column='satisfaction_score', category='department', use_violin=True)
fig.show()

Heatmap / Correlation Matrix

import pandas as pd
from MatplotLibAPI import fplot_heatmap, fplot_correlation_matrix

heatmap_df = pd.read_csv('data/heatmap.csv')
correlation_df = pd.read_csv('data/correlation.csv')

fig_heatmap = fplot_heatmap(heatmap_df, index='month', columns='channel', values='engagements')
fig_corr = fplot_correlation_matrix(correlation_df)

fig_heatmap.show()
fig_corr.show()

Area

import pandas as pd
from MatplotLibAPI import fplot_area

df = pd.read_csv('data/area.csv')
fig = fplot_area(df, x='quarter', y='subscriptions', label='segment', stacked=True)
fig.show()

Pie / Donut

import pandas as pd
from MatplotLibAPI import fplot_pie_donut

df = pd.read_csv('data/pie.csv')
fig = fplot_pie_donut(df, category='device', value='sessions', donut=True)
fig.show()

Waffle

import pandas as pd
from MatplotLibAPI import fplot_waffle

df = pd.read_csv('data/waffle.csv')
fig = fplot_waffle(df, category='device', value='sessions')
fig.show()

Sankey

import pandas as pd
from MatplotLibAPI import fplot_sankey

df = pd.read_csv('data/sankey.csv')
fig = fplot_sankey(df, source='source', target='target', value='value')
fig.show()

Pivot Table

import pandas as pd
from MatplotLibAPI.Pivot import plot_pivoted_bars

df = pd.read_csv('data/pivot.csv')
ax = plot_pivoted_bars(data=df, label="category", x="date", y="value")
ax.figure.show()

Table

import pandas as pd
from MatplotLibAPI import fplot_table

df = pd.read_csv('data/table.csv')
fig = fplot_table(pd_df=df, cols=["col1", "col2"])
fig.show()

Timeseries Plot

import pandas as pd
from MatplotLibAPI import fplot_timeserie

df = pd.read_csv('data/timeserie.csv')
fig = fplot_timeserie(pd_df=df, label="group", x="date", y="value")
fig.show()

Treemap

import pandas as pd
from MatplotLibAPI import fplot_treemap

df = pd.read_csv('data/treemap.csv')
fig = fplot_treemap(pd_df=df, path="path", values="values")
fig.show()

Sunburst Chart

import pandas as pd
from MatplotLibAPI import fplot_sunburst

df = pd.read_csv('data/sunburst.csv')
fig = fplot_sunburst(df, labels="labels", parents="parents", values="values")
fig.show()

Word Cloud

import pandas as pd
from MatplotLibAPI import fplot_wordcloud

df = pd.read_csv('data/wordcloud.csv')
fig = fplot_wordcloud(df, text_column="word", weight_column="weight")
fig.show()

Metadata

Release files for MatplotLibAPI 4.0.3

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.0.3
File Size Uploaded Provenance Actions
matplotlibapi-4.0.3.tar.gz 60.5 kB Without provenance Details for matplotlibapi-4.0.3.tar.gz

Built distribution (wheel)

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

Total release size: 126.3 kB

Release files / matplotlibapi-4.0.3.tar.gz

Download URL matplotlibapi-4.0.3.tar.gz
Size 60.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0b742a642aedd8a03a4d079883d2a41cd49f95fd0edcd34f403bf15a22e1cf5c
BLAKE2b-256 checksum
How to use checksums
cc5e21a564e6b6e42d73370cb69fe0925444b50094d679ab19cc3c3e05cdfadc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

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

Download URL matplotlibapi-4.0.3-py3-none-any.whl
Size 65.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3dc535aceb7786e7272b7d409338dc1a8474edc5f9b579a68a6f1d57c057247b
BLAKE2b-256 checksum
How to use checksums
59ce1e7e25322fa07300fc2fe984bc84e88e77dfb0f5e1b7de13042c15f66662
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for MatplotLibAPI 4.0.3

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.0.3 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