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.
- Install MCP dependencies:
pip install -e .[mcp]
- 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 forbar,histogram,box_violin,heatmap,correlation_matrix,area,pie,waffle,sankey,table,timeserie,wordcloud,treemap, andsunburst.- 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, ortable: 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:
- Call
describe_plot_modules. - Select a module from
supported_plot_modules. - Read recommended keys from
parameter_hints[module_name]. - Call
plot_modulewithparams+csv_pathortable.
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.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| matplotlibapi-4.0.2.tar.gz | 73.2 kB | Without provenance | Details for matplotlibapi-4.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| matplotlibapi-4.0.2-py3-none-any.whl | Python 3 | none | any | Details for matplotlibapi-4.0.2-py3-none-any.whl |
Total release size: 140.3 kB
Release files / matplotlibapi-4.0.2.tar.gz
| Download URL | matplotlibapi-4.0.2.tar.gz |
|---|---|
| Size | 73.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
51f176dd4f8cbd117dd98a5f8119d14158dfefde0ee129cdb1fdac1f97018426
|
|
BLAKE2b-256 checksum How to use checksums |
10792d963e5f5e206fa0c20117805f89a0e4261597ce32e436fdc7047eb6d3eb
|
| 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.2-py3-none-any.whl
| Download URL | matplotlibapi-4.0.2-py3-none-any.whl |
|---|---|
| Size | 67.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ac94204e9ad7c934723d80a45f675ca0c017e323ef49a6d24882f8197a19adb
|
|
BLAKE2b-256 checksum How to use checksums |
bed77385115df8cb403e090c64fd6d9124a53b872bd58b9859d7c406017b6445
|
| 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.2
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.