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

MatplotLibAPI/{Composite.py → composite.py}

@@ -5,16 +5,24 @@ from typing import Dict, Iterable, Optional, Tuple, cast
 import matplotlib.pyplot as plt
 import pandas as pd
 import plotly.graph_objects as go
+from matplotlib.axes import Axes
 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 NETWORK_STYLE_TEMPLATE, aplot_network
-from .StyleTemplate import MAX_RESULTS, 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 .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 .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud, WordCloud
 
 
 def plot_composite_bubble(
@@ -73,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,
@@ -113,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,
@@ -122,7 +123,10 @@ def plot_composite_bubble(
         max_values=table_rows,
         style=style,
     )
-    fig.tight_layout()
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
     return fig
 
 
@@ -162,90 +166,78 @@ 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,
-    text_column: str = "node",
-    node_weight: Optional[str] = "weight",
-    source: str = "source",
-    target: str = "target",
-    edge_weight: str = "weight",
-    wordcloud_title: Optional[str] = None,
-    network_title: Optional[str] = None,
-    wordcloud_style: StyleTemplate = WORDCLOUD_STYLE_TEMPLATE,
-    network_style: StyleTemplate = NETWORK_STYLE_TEMPLATE,
+    edge_source_col: str = "source",
+    edge_target_col: str = "target",
+    edge_weight_col: str = "weight",
     max_words: int = MAX_RESULTS,
     stopwords: Optional[Iterable[str]] = None,
+    title: Optional[str] = None,
+    style: StyleTemplate = WORDCLOUD_STYLE_TEMPLATE,
+    wordcloud_style: Optional[StyleTemplate] = None,
+    network_style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = FIG_SIZE,
 ) -> Figure:
     """Plot a word cloud above a network graph.
 
     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.
-    text_column : str, optional
-        Column in ``nodes_df`` containing the node labels. The default is ``"node"``.
-    node_weight : str, optional
-        Column in ``nodes_df`` containing weights for sizing words. The default is
-        ``"weight"``.
-    source : str, optional
+    edge_source_col : str, optional
         Column in ``edges_df`` containing source nodes. The default is ``"source"``.
-    target : str, optional
+    edge_target_col : str, optional
         Column in ``edges_df`` containing target nodes. The default is ``"target"``.
-    edge_weight : str, optional
+    edge_weight_col : str, optional
         Column in ``edges_df`` containing edge weights. The default is ``"weight"``.
-    wordcloud_title : str, optional
-        Title for the word cloud subplot. The default is ``None``.
-    network_title : str, optional
-        Title for the network subplot. The default is ``None``.
-    wordcloud_style : StyleTemplate, optional
-        Style configuration for the word cloud. The default is
-        ``WORDCLOUD_STYLE_TEMPLATE``.
-    network_style : StyleTemplate, optional
-        Style configuration for the network graph. The default is
-        ``NETWORK_STYLE_TEMPLATE``.
     max_words : int, optional
         Maximum number of words to include in the word cloud. The default is ``50``.
     stopwords : Iterable[str], optional
         Stopwords to exclude from the word cloud. The default is ``None``.
+    title : str, optional
+        Title for the composite figure. The default is ``None``.
+    style : StyleTemplate, optional
+        Shared style configuration applied to the composite figure and used for
+        subplots when specialized styles are not provided. The default is
+        ``WORDCLOUD_STYLE_TEMPLATE``.
+    wordcloud_style : StyleTemplate, optional
+        Optional style configuration for the word cloud subplot. When ``None``
+        the shared ``style`` is used. The default is ``None``.
+    network_style : StyleTemplate, optional
+        Optional style configuration for the network subplot. When ``None`` the
+        shared ``style`` is used. The default is ``None``.
     figsize : tuple[float, float], optional
         Size of the composite figure. The default is ``FIG_SIZE``.
 
@@ -254,35 +246,64 @@ def plot_wordcloud_network(
     Figure
         Matplotlib figure containing the word cloud on top and network below.
     """
-    validate_dataframe(nodes_df, cols=[text_column], sort_by=node_weight)
-    validate_dataframe(edges_df, cols=[source, target, edge_weight], sort_by=None)
+    fig_raw, axes_raw = plt.subplots(
+        2,
+        1,
+        figsize=figsize,
+        gridspec_kw={"height_ratios": [1, 2]},
+    )
+    fig = cast(Figure, fig_raw)
+    wordcloud_ax, network_ax = cast(Tuple[Axes, Axes], axes_raw)
 
-    fig = cast(Figure, plt.figure(figsize=figsize))
-    fig.patch.set_facecolor(wordcloud_style.background_color)
-    grid = GridSpec(2, 1, height_ratios=[1, 2])
+    wordcloud_style = wordcloud_style or style
+    network_style = network_style or style
+
+    fig.set_facecolor(style.background_color)
+    if title:
+        fig.suptitle(
+            title,
+            color=style.font_color,
+            fontsize=style.font_size * TITLE_SCALE_FACTOR,
+            fontname=style.font_name,
+        )
+
+    validate_dataframe(
+        node_df,
+        cols=["node", "weight"],
+    )
+    validate_dataframe(
+        edges_df,
+        cols=[edge_source_col, edge_target_col, edge_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,
+    )
 
-    wordcloud_ax = fig.add_subplot(grid[0, 0])
     aplot_wordcloud(
-        pd_df=nodes_df,
-        text_column=text_column,
-        weight_column=node_weight,
-        title=wordcloud_title,
+        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,
     )
 
-    network_ax = fig.add_subplot(grid[1, 0])
-    aplot_network(
-        pd_df=edges_df,
-        source=source,
-        target=target,
-        weight=edge_weight,
-        title=network_title,
-        style=network_style,
-        ax=network_ax,
-    )
-
-    fig.tight_layout()
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
     return fig

MatplotLibAPI/heatmap.py

@@ -0,0 +1,223 @@
+"""Heatmap and correlation matrix helpers."""
+
+from typing import Any, Optional, Sequence, Tuple
+
+import pandas as pd
+from pandas.api.extensions import register_dataframe_accessor
+import matplotlib.pyplot as plt
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .base_plot import BasePlot
+
+from .style_template import (
+    HEATMAP_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from .utils import _get_axis
+from .typing import CorrelationMethod
+
+__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_ax = _get_axis(ax)
+        sns.heatmap(self._obj, cmap=style.palette, ax=plot_ax)
+
+        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:
+        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_correlation_matrix(
+        self,
+        title: Optional[str] = None,
+        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        ax: Optional[Axes] = None,
+        **kwargs: Any,
+    ) -> Axes:
+        plot_ax = _get_axis(ax)
+        sns.heatmap(
+            self.correlation_matrix,
+            cmap=style.palette,
+            annot=True,
+            fmt=".2f",
+            ax=plot_ax,
+        )
+        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:
+        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 _prepare_data(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    value: str,
+) -> pd.DataFrame:
+    """Prepare data for treemap 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 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."""
+    return Heatmap(
+        pd_df=pd_df,
+        x="",  # Placeholder since correlation matrix is square
+        y="",  # Placeholder since correlation matrix is square
+        value="",  # Placeholder since correlation matrix is computed internally
+    ).aplot_correlation_matrix(
+        method=method,
+        title=title,
+        style=style,
+        ax=ax,
+        columns=columns,
+        **kwargs,
+    )
+
+
+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,  # Placeholder since correlation matrix is square
+        y=y,  # Placeholder since correlation matrix is square
+        value=value,  # Placeholder since correlation matrix is computed internally
+    ).fplot_correlation_matrix(title=title, style=style, figsize=figsize)