MatplotLibAPI 3.3.0__py3-none-any.whl → 4.0.1__py3-none-any.whl

MatplotLibAPI/{Composite.py → composite.py}

@@ -10,17 +10,19 @@ from matplotlib.figure import Figure
 from matplotlib.gridspec import GridSpec
 from plotly.subplots import make_subplots
 
-from .Bubble import BUBBLE_STYLE_TEMPLATE, FIG_SIZE, aplot_bubble
-from .Network import aplot_network
-from .StyleTemplate import (
+from .base_plot import BasePlot
+
+from .bubble import BUBBLE_STYLE_TEMPLATE, FIG_SIZE, Bubble
+from .network import aplot_network, NetworkGraph
+from .style_template import (
     MAX_RESULTS,
     TITLE_SCALE_FACTOR,
     StyleTemplate,
     validate_dataframe,
 )
-from .Table import aplot_table
-from .Treemap import TREEMAP_STYLE_TEMPLATE, aplot_treemap
-from .Wordcloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud
+from .table import aplot_table
+from .treemap import TREEMAP_STYLE_TEMPLATE, aplot_treemap
+from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, WordCloud
 
 
 def plot_composite_bubble(
@@ -79,36 +81,29 @@ def plot_composite_bubble(
     """
     validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
 
-    if not sort_by:
-        sort_by = z
-    if not filter_by:
-        filter_by = z
-    plot_df = pd_df.sort_values(by=filter_by, ascending=ascending)[
-        [label, x, y, z]
-    ].head(max_values)
-
     fig = cast(Figure, plt.figure(figsize=figsize))
-    fig.patch.set_facecolor(style.background_color)
+    fig.set_facecolor(style.background_color)
     grid = GridSpec(2, 2, height_ratios=[2, 1], width_ratios=[1, 1])
     ax = fig.add_subplot(grid[0, 0:])
-    ax = aplot_bubble(
-        pd_df=cast(pd.DataFrame, plot_df),
+    ax = Bubble(
+        pd_df=pd_df,
         label=label,
         x=x,
         y=y,
         z=z,
-        title=title,
-        style=style,
         max_values=max_values,
         center_to_mean=center_to_mean,
         sort_by=sort_by,
         ascending=ascending,
+    ).aplot(
+        title=title,
+        style=style,
         ax=ax,
     )
 
     ax2 = fig.add_subplot(grid[1, 0])
     ax2 = aplot_table(
-        pd_df=cast(pd.DataFrame, plot_df),
+        pd_df=pd_df,
         cols=[label, z, y, x],
         title=f"Top {table_rows}",
         ax=ax2,
@@ -119,7 +114,7 @@ def plot_composite_bubble(
     )
     ax3 = fig.add_subplot(grid[1, 1])
     ax3 = aplot_table(
-        pd_df=cast(pd.DataFrame, plot_df),
+        pd_df=pd_df,
         cols=[label, z, y, x],
         title=f"Last {table_rows}",
         ax=ax3,
@@ -171,46 +166,39 @@ def plot_composite_treemap(
     go.Figure, optional
         Composite treemap figure, or None if no data frames are provided.
     """
+    go_fig = go.Figure()
     num_dimensions = len(pd_dfs)
-    if num_dimensions > 0:
-        subplot_titles = [
-            f"{title}::{dim.title()}" if title is not None else dim.title()
-            for dim in pd_dfs.keys()
-        ]
-        fig = make_subplots(
-            rows=num_dimensions,
-            cols=1,
-            specs=[
-                [{"type": "treemap"} for _ in range(0, 1)]
-                for _ in range(0, num_dimensions)
-            ],
-            subplot_titles=subplot_titles,
-            vertical_spacing=0.2,
-        )
+    subplot_titles = [
+        f"{title}::{dim.title()}" if title is not None else dim.title()
+        for dim in pd_dfs
+    ]
+    fig = make_subplots(
+        rows=num_dimensions,
+        cols=1,
+        specs=[[{"type": "treemap"} for _ in range(1)] for _ in range(num_dimensions)],
+        subplot_titles=subplot_titles,
+        vertical_spacing=0.2,
+        figure=go_fig,
+    )
 
-        current_row = 1
-        for path, df in pd_dfs.items():
-            trm = aplot_treemap(
-                pd_df=df,
-                path=path,
-                values=values,
-                style=style,
-                color=color,
-                sort_by=sort_by,
-                ascending=ascending,
-                max_values=max_values,
-            )
-            fig.add_trace(trm, row=current_row, col=1)
-            current_row += 1
-        return fig
-    return None
+    for current_row, (path, df) in enumerate(pd_dfs.items(), start=1):
+        trm = aplot_treemap(
+            pd_df=df,
+            path=path,
+            values=values,
+            style=style,
+            color=color,
+            sort_by=sort_by,
+            ascending=ascending,
+            max_values=max_values,
+        )
+        fig.add_trace(trm, row=current_row, col=1)
+    return fig
 
 
-def plot_wordcloud_network(
-    nodes_df: pd.DataFrame,
+def fplot_wordcloud_network(
+    node_df: pd.DataFrame,
     edges_df: pd.DataFrame,
-    node_col: str = "node",
-    node_weight_col: str = "weight",
     edge_source_col: str = "source",
     edge_target_col: str = "target",
     edge_weight_col: str = "weight",
@@ -226,15 +214,8 @@ def plot_wordcloud_network(
 
     Parameters
     ----------
-    nodes_df : pd.DataFrame
-        DataFrame containing node labels and optional weights for the word cloud.
     edges_df : pd.DataFrame
         DataFrame containing edge connections for the network plot.
-    node_col : str, optional
-        Column in ``nodes_df`` containing the node labels. The default is ``"node"``.
-    node_weight_col : str, optional
-        Column in ``nodes_df`` containing weights for sizing words. The default is
-        ``"weight"``.
     edge_source_col : str, optional
         Column in ``edges_df`` containing source nodes. The default is ``"source"``.
     edge_target_col : str, optional
@@ -265,11 +246,6 @@ def plot_wordcloud_network(
     Figure
         Matplotlib figure containing the word cloud on top and network below.
     """
-    validate_dataframe(nodes_df, cols=[node_col], sort_by=node_weight_col)
-    validate_dataframe(
-        edges_df, cols=[edge_source_col, edge_target_col, edge_weight_col], sort_by=None
-    )
-
     fig_raw, axes_raw = plt.subplots(
         2,
         1,
@@ -282,7 +258,7 @@ def plot_wordcloud_network(
     wordcloud_style = wordcloud_style or style
     network_style = network_style or style
 
-    fig.patch.set_facecolor(style.background_color)
+    fig.set_facecolor(style.background_color)
     if title:
         fig.suptitle(
             title,
@@ -291,30 +267,41 @@ def plot_wordcloud_network(
             fontname=style.font_name,
         )
 
-    aplot_wordcloud(
-        pd_df=nodes_df,
-        text_column=node_col,
-        weight_column=node_weight_col,
-        title=None,
-        style=wordcloud_style,
-        max_words=max_words,
-        stopwords=stopwords,
-        ax=wordcloud_ax,
+    validate_dataframe(
+        node_df,
+        cols=["node", "weight"],
+    )
+    validate_dataframe(
+        edges_df,
+        cols=[edge_source_col, edge_target_col, edge_weight_col],
     )
 
-    aplot_network(
-        pd_df=edges_df,
-        node_df=nodes_df,
-        node_col=node_col,
-        node_weight_col=node_weight_col,
+    network = NetworkGraph.from_pandas(
+        node_df,
+        edges_df,
+        node_col="node",
+        node_weight_col="weight",
         edge_source_col=edge_source_col,
         edge_target_col=edge_target_col,
         edge_weight_col=edge_weight_col,
+    )
+    network.aplot(
         title=None,
         style=network_style,
         ax=network_ax,
     )
 
+    aplot_wordcloud(
+        pd_df=network.node_view.to_dataframe(),
+        text_column="node",
+        weight_column=edge_weight_col,
+        title=None,
+        style=wordcloud_style,
+        max_words=max_words,
+        stopwords=stopwords,
+        ax=wordcloud_ax,
+    )
+
     if title:
         fig.tight_layout(rect=(0, 0, 1, 0.95))
     else:

MatplotLibAPI/heatmap.py

@@ -0,0 +1,246 @@
+"""Heatmap and correlation matrix helpers."""
+
+from typing import Any, Optional, Sequence, Tuple, cast
+
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from pandas.api.extensions import register_dataframe_accessor
+
+from .base_plot import BasePlot
+from .style_template import (
+    HEATMAP_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from .typing import CorrelationMethod
+from .utils import _get_axis, _merge_kwargs
+
+__all__ = [
+    "HEATMAP_STYLE_TEMPLATE",
+    "aplot_heatmap",
+    "aplot_correlation_matrix",
+    "fplot_heatmap",
+    "fplot_correlation_matrix",
+]
+
+
+@register_dataframe_accessor("heatmap")
+class Heatmap(BasePlot):
+    """Class for plotting heatmaps and correlation matrices."""
+
+    def __init__(
+        self,
+        pd_df: pd.DataFrame,
+        x: str,
+        y: str,
+        value: str,
+    ):
+        self._obj = _prepare_data(pd_df, x, y, value)
+        self.x = x
+        self.y = y
+        self.value = value
+
+    @property
+    def correlation_matrix(self) -> pd.DataFrame:
+        """Compute the correlation matrix for the underlying DataFrame."""
+        return self._obj.corr()
+
+    def aplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot a heatmap on an existing Matplotlib axes."""
+        plot_ax = _get_axis(ax)
+        heatmap_kwargs: dict[str, Any] = {
+            "data": self._obj,
+            "cmap": style.palette,
+            "ax": plot_ax,
+        }
+        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+
+        plot_ax.set_xlabel(string_formatter(self.x))
+        plot_ax.set_ylabel(string_formatter(self.y))
+        if title:
+            plot_ax.set_title(title)
+        return plot_ax
+
+    def fplot(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (10, 6),
+    ) -> Figure:
+        """Plot a heatmap on a new Matplotlib figure."""
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = fig.add_subplot(111)
+        ax.set_facecolor(style.background_color)
+        self.aplot(title=title, style=style, ax=ax)
+        return fig
+
+    def aplot_correlation_matrix(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Plot a correlation matrix heatmap on existing axes."""
+        plot_ax = _get_axis(ax)
+        heatmap_kwargs: dict[str, Any] = {
+            "data": self.correlation_matrix,
+            "cmap": style.palette,
+            "annot": True,
+            "fmt": ".2f",
+            "ax": plot_ax,
+        }
+        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+        if title:
+            plot_ax.set_title(title)
+        return plot_ax
+
+    def fplot_correlation_matrix(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        figsize: Tuple[float, float] = (10, 6),
+    ) -> Figure:
+        """Plot a correlation matrix heatmap on a new figure."""
+        fig = Figure(
+            figsize=figsize,
+            facecolor=style.background_color,
+            edgecolor=style.background_color,
+        )
+        ax = fig.add_subplot(111)
+        ax.set_facecolor(style.background_color)
+        self.aplot_correlation_matrix(
+            title=title,
+            style=style,
+            ax=ax,
+        )
+        return fig
+
+
+def _prepare_data(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    value: str,
+) -> pd.DataFrame:
+    """Prepare data for heatmap plotting."""
+    validate_dataframe(pd_df, cols=[x, y, value])
+    plot_df = pd_df[[x, y, value]].pivot_table(
+        index=y, columns=x, values=value, aggfunc="mean"
+    )
+    return plot_df
+
+
+def _compute_correlation_matrix(
+    pd_df: pd.DataFrame,
+    columns: Optional[Sequence[str]],
+    method: CorrelationMethod,
+) -> pd.DataFrame:
+    """Compute a correlation matrix from numeric dataframe columns."""
+    source_df = pd_df[list(columns)] if columns else pd_df
+    numeric_df = source_df.select_dtypes(include="number")
+    if numeric_df.empty:
+        raise ValueError("No numeric columns available to compute correlation matrix.")
+    return numeric_df.corr(method=cast(Any, method))
+
+
+def aplot_heatmap(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    value: str,
+    title: Optional[str] = None,
+    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot a matrix heatmap for multivariate pattern detection."""
+    return Heatmap(
+        pd_df=pd_df,
+        x=x,
+        y=y,
+        value=value,
+    ).aplot(
+        title=title,
+        style=style,
+        ax=ax,
+        **kwargs,
+    )
+
+
+def aplot_correlation_matrix(
+    pd_df: pd.DataFrame,
+    columns: Optional[Sequence[str]] = None,
+    method: CorrelationMethod = "pearson",
+    title: Optional[str] = None,
+    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot a correlation matrix heatmap for numeric columns."""
+    corr_df = _compute_correlation_matrix(pd_df=pd_df, columns=columns, method=method)
+    plot_ax = _get_axis(ax)
+    heatmap_kwargs: dict[str, Any] = {
+        "data": corr_df,
+        "cmap": style.palette,
+        "annot": True,
+        "fmt": ".2f",
+        "ax": plot_ax,
+    }
+    sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_heatmap(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    value: str,
+    title: Optional[str] = None,
+    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot a matrix heatmap on a new figure."""
+    return Heatmap(
+        pd_df=pd_df,
+        x=x,
+        y=y,
+        value=value,
+    ).fplot(
+        title=title,
+        style=style,
+        figsize=figsize,
+    )
+
+
+def fplot_correlation_matrix(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    value: str,
+    title: Optional[str] = None,
+    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot a correlation matrix heatmap on a new figure."""
+    return Heatmap(
+        pd_df=pd_df,
+        x=x,
+        y=y,
+        value=value,
+    ).fplot_correlation_matrix(title=title, style=style, figsize=figsize)

MatplotLibAPI/histogram.py

@@ -0,0 +1,172 @@
+"""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, _merge_kwargs
+
+__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)
+        histplot_kwargs: dict[str, Any] = {
+            "data": self._obj,
+            "x": self.column,
+            "bins": self.bins,
+            "kde": self.kde,
+            "color": style.font_color,
+            "edgecolor": style.background_color,
+            "ax": plot_ax,
+        }
+        sns.histplot(**_merge_kwargs(histplot_kwargs, kwargs))
+        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 = fig.add_subplot(111)
+        ax.set_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",
+]