MatplotLibAPI 3.2.21__py3-none-any.whl → 4.0.0__py3-none-any.whl

MatplotLibAPI/histogram.py

@@ -0,0 +1,170 @@
+"""Histogram and KDE plotting helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+from pandas.api.extensions import register_dataframe_accessor
+import seaborn as sns
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+
+from .base_plot import BasePlot
+
+from .style_template import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    NETWORK_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from .utils import _get_axis
+
+__all__ = ["DISTRIBUTION_STYLE_TEMPLATE", "aplot_histogram", "fplot_histogram"]
+
+
+@register_dataframe_accessor("histogram")
+class Histogram(BasePlot):
+    """Class for plotting histograms with optional KDE."""
+
+    def __init__(
+        self,
+        pd_df: pd.DataFrame,
+        column: str,
+        bins: int = 20,
+        kde: bool = True,
+    ):
+        super().__init__(pd_df=pd_df)
+        self.column = column
+        self.bins = bins
+        self.kde = kde
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+
+        validate_dataframe(self._obj, cols=[self.column])
+        plot_ax = _get_axis(ax)
+        sns.histplot(
+            data=self._obj,
+            x=self.column,
+            bins=self.bins,
+            kde=self.kde,
+            color=style.font_color,
+            edgecolor=style.background_color,
+            ax=plot_ax,
+        )
+        plot_ax.set_facecolor(style.background_color)
+        plot_ax.set_xlabel(string_formatter(self.column))
+        plot_ax.set_ylabel("Frequency")
+        if title:
+            plot_ax.set_title(title)
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (10, 6),
+    ) -> Figure:
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = Axes(fig=fig, facecolor=style.background_color)
+        self.aplot(
+            title=title,
+            style=style,
+            ax=ax,
+        )
+        return fig
+
+
+def aplot_histogram(
+    pd_df: pd.DataFrame,
+    column: str,
+    bins: int = 20,
+    kde: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot a histogram with an optional kernel density estimate.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        The input DataFrame containing the data to plot.
+    column : str
+        The name of the column to plot.
+    bins : int, optional
+        The number of bins for the histogram, by default 20.
+    kde : bool, optional
+        Whether to include a kernel density estimate, by default True.
+    title : Optional[str], optional
+        The title of the plot, by default None.
+    style : StyleTemplate, optional
+        The style template to use for the plot, by default DISTRIBUTION_STYLE_TEMPLATE.
+    ax : Optional[Axes], optional
+        An optional matplotlib Axes to plot on. If None, a new figure and axes will be created, by default None.
+    **kwargs : Any
+        Additional keyword arguments to pass to seaborn.histplot.
+    """
+    return Histogram(
+        pd_df=pd_df,
+        column=column,
+        bins=bins,
+        kde=kde,
+    ).aplot(
+        title=title,
+        style=style,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def fplot_histogram(
+    pd_df: pd.DataFrame,
+    column: str,
+    bins: int = 20,
+    kde: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot a histogram with optional KDE on a new figure.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        The input DataFrame containing the data to plot.
+    column : str
+        The name of the column to plot.
+    bins : int, optional
+        The number of bins for the histogram, by default 20.
+    kde : bool, optional
+        Whether to include a kernel density estimate, by default True.
+    title : Optional[str], optional
+        The title of the plot, by default None.
+    style : StyleTemplate, optional
+        The style template to use for the plot, by default DISTRIBUTION_STYLE_TEMPLATE.
+    figsize : Tuple[float, float], optional
+        The size of the figure, by default (10, 6).
+    """
+    return Histogram(
+        pd_df=pd_df,
+        column=column,
+        bins=bins,
+        kde=kde,
+    ).fplot(
+        title=title,
+        style=style,
+        figsize=figsize,
+    )

MatplotLibAPI/mcp/__init__.py

@@ -0,0 +1,17 @@
+"""MCP helper utilities for MatplotLibAPI."""
+
+from .metadata import (
+    DEDICATED_PLOT_TOOLS,
+    PLOT_MODULE_PARAMETER_HINTS,
+    SHARED_INPUT_CONTRACT,
+)
+from .renderers import MATPLOTLIB_RENDERERS, PLOTLY_RENDERERS, SUPPORTED_PLOT_MODULES
+
+__all__ = [
+    "DEDICATED_PLOT_TOOLS",
+    "MATPLOTLIB_RENDERERS",
+    "PLOTLY_RENDERERS",
+    "PLOT_MODULE_PARAMETER_HINTS",
+    "SHARED_INPUT_CONTRACT",
+    "SUPPORTED_PLOT_MODULES",
+]

MatplotLibAPI/mcp/metadata.py

@@ -0,0 +1,90 @@
+"""Discoverability metadata used by MCP plot tools."""
+
+from typing import Dict
+
+SHARED_INPUT_CONTRACT: Dict[str, str] = {
+    "csv_path": "Path to a CSV file with source data.",
+    "table": "In-memory table as list[dict[str, Any]] records.",
+    "return": "PNG bytes suitable for application/octet-stream.",
+}
+
+PLOT_MODULE_PARAMETER_HINTS: Dict[str, Dict[str, str]] = {
+    "bubble": {
+        "label": "Bubble label column name.",
+        "x": "X-axis column name.",
+        "y": "Y-axis column name.",
+        "z": "Bubble size column name.",
+    },
+    "network": {
+        "edge_source_col": "Source-node column name (default: source).",
+        "edge_target_col": "Target-node column name (default: target).",
+        "edge_weight_col": "Edge-weight column name (default: weight).",
+    },
+    "bar": {
+        "category": "Category column name.",
+        "value": "Numeric value column name.",
+    },
+    "histogram": {"value": "Numeric value column name."},
+    "box_violin": {"y": "Numeric value column name."},
+    "heatmap": {
+        "x": "X-axis category column name.",
+        "y": "Y-axis category column name.",
+        "value": "Cell value column name.",
+    },
+    "correlation_matrix": {
+        "features": "List of numeric columns used in correlation matrix.",
+    },
+    "area": {
+        "x": "X-axis column name.",
+        "y": "List of stacked y-axis columns.",
+    },
+    "pie": {
+        "label": "Category label column name.",
+        "value": "Numeric value column name.",
+    },
+    "waffle": {
+        "label": "Category label column name.",
+        "value": "Numeric value column name.",
+    },
+    "sankey": {
+        "source": "Source-node column name.",
+        "target": "Target-node column name.",
+        "value": "Flow/weight column name.",
+    },
+    "table": {},
+    "timeserie": {
+        "x": "Datetime or ordered x-axis column name.",
+        "y": "List of y-axis series columns.",
+    },
+    "wordcloud": {
+        "text_column": "Text/token column name.",
+        "weight_column": "Weight/frequency column name (optional).",
+    },
+    "treemap": {
+        "path": "Hierarchy column names in order.",
+        "values": "Numeric value column name.",
+    },
+    "sunburst": {
+        "path": "Hierarchy column names in order.",
+        "values": "Numeric value column name.",
+    },
+}
+
+DEDICATED_PLOT_TOOLS: Dict[str, str] = {
+    "plot_bubble": "bubble",
+    "plot_network": "network",
+    "plot_bar": "bar",
+    "plot_histogram": "histogram",
+    "plot_box_violin": "box_violin",
+    "plot_heatmap": "heatmap",
+    "plot_correlation_matrix": "correlation_matrix",
+    "plot_area": "area",
+    "plot_pie": "pie",
+    "plot_waffle": "waffle",
+    "plot_sankey": "sankey",
+    "plot_table": "table",
+    "plot_timeserie": "timeserie",
+    "plot_wordcloud": "wordcloud",
+    "plot_treemap": "treemap",
+    "plot_sunburst": "sunburst",
+}

MatplotLibAPI/mcp/renderers.py

@@ -0,0 +1,45 @@
+"""Renderer registries for MCP plot-module dispatch."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict
+
+from ..area import fplot_area
+from ..bar import fplot_bar
+from ..box_violin import fplot_box_violin
+from ..heatmap import fplot_correlation_matrix, fplot_heatmap
+from ..histogram import fplot_histogram
+from ..pie import fplot_pie
+from ..sankey import fplot_sankey
+from ..sunburst import fplot_sunburst
+from ..table import fplot_table
+from ..timeserie import fplot_timeserie
+from ..treemap import fplot_treemap
+from ..waffle import fplot_waffle
+from ..word_cloud import fplot_wordcloud
+
+Renderer = Callable[..., Any]
+
+MATPLOTLIB_RENDERERS: Dict[str, Renderer] = {
+    "bar": fplot_bar,
+    "histogram": fplot_histogram,
+    "box_violin": fplot_box_violin,
+    "heatmap": fplot_heatmap,
+    "correlation_matrix": fplot_correlation_matrix,
+    "area": fplot_area,
+    "pie": fplot_pie,
+    "waffle": fplot_waffle,
+    "table": fplot_table,
+    "timeserie": fplot_timeserie,
+    "wordcloud": fplot_wordcloud,
+}
+
+PLOTLY_RENDERERS: Dict[str, Renderer] = {
+    "sankey": fplot_sankey,
+    "treemap": fplot_treemap,
+    "sunburst": fplot_sunburst,
+}
+
+SUPPORTED_PLOT_MODULES = sorted(
+    ["bubble", "network", *MATPLOTLIB_RENDERERS.keys(), *PLOTLY_RENDERERS.keys()]
+)