MatplotLibAPI 4.0.0

No project description provided

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(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]

2. 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()
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(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()