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

MatplotLibAPI/composite.py

@@ -7,13 +7,12 @@ 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 .base_plot import BasePlot
+from .base_plot import FIG_SIZE
 
-from .bubble import BUBBLE_STYLE_TEMPLATE, FIG_SIZE, Bubble
-from .network import aplot_network, NetworkGraph
+from .bubble import aplot_bubble, Bubble
+from .network import NetworkGraph
 from .style_template import (
     MAX_RESULTS,
     TITLE_SCALE_FACTOR,
@@ -21,8 +20,8 @@ from .style_template import (
     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
+from .treemap import aplot_treemap
+from .word_cloud import WORDCLOUD_STYLE_TEMPLATE, aplot_wordcloud
 
 
 def plot_composite_bubble(
@@ -32,7 +31,7 @@ def plot_composite_bubble(
     y: str,
     z: str,
     title: Optional[str] = None,
-    style: StyleTemplate = BUBBLE_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     max_values: int = 50,
     center_to_mean: bool = False,
     filter_by: Optional[str] = None,
@@ -80,12 +79,20 @@ def plot_composite_bubble(
         Matplotlib figure containing the composite bubble chart and tables.
     """
     validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
+    if style is None:
+        style = WORDCLOUD_STYLE_TEMPLATE
+    fig = plt.figure(figsize=figsize)
+    gs = fig.add_gridspec(
+        2,
+        2,
+        height_ratios=[2, 1],
+        width_ratios=[1, 1],
+    )
+    ax = fig.add_subplot(gs[0, :])
+    ax2 = fig.add_subplot(gs[1, 0])
+    ax3 = fig.add_subplot(gs[1, 1])
 
-    fig = cast(Figure, plt.figure(figsize=figsize))
-    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 = Bubble(
+    aplot_bubble(
         pd_df=pd_df,
         label=label,
         x=x,
@@ -95,13 +102,11 @@ def plot_composite_bubble(
         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=pd_df,
         cols=[label, z, y, x],
@@ -112,7 +117,7 @@ def plot_composite_bubble(
         max_values=table_rows,
         style=style,
     )
-    ax3 = fig.add_subplot(grid[1, 1])
+
     ax3 = aplot_table(
         pd_df=pd_df,
         cols=[label, z, y, x],
@@ -133,7 +138,7 @@ def plot_composite_bubble(
 def plot_composite_treemap(
     pd_dfs: Dict[str, pd.DataFrame],
     values: str,
-    style: StyleTemplate = TREEMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     title: Optional[str] = None,
     color: Optional[str] = None,
     sort_by: Optional[str] = None,
@@ -196,6 +201,219 @@ def plot_composite_treemap(
     return fig
 
 
+def fplot_bubble(
+    pd_df: pd.DataFrame,
+    label: str,
+    x: str,
+    y: str,
+    z: str,
+    title: Optional[str] = None,
+    style: Optional[StyleTemplate] = None,
+    max_values: int = 50,
+    center_to_mean: bool = False,
+    filter_by: Optional[str] = None,
+    sort_by: Optional[str] = None,
+    ascending: bool = False,
+    table_rows: int = 10,
+    figsize: Tuple[float, float] = FIG_SIZE,
+) -> Figure:
+    """Plot a composite bubble chart with summary tables.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        Data to be plotted.
+    label : str
+        Column name for bubble labels.
+    x : str
+        Column name for the x-axis values.
+    y : str
+        Column name for the y-axis values.
+    z : str
+        Column name for bubble sizes.
+    title : str, optional
+        Title of the plot. The default is ``None``.
+    style : StyleTemplate, optional
+        Style configuration. The default is `BUBBLE_STYLE_TEMPLATE`.
+    max_values : int, optional
+        Maximum number of rows to display in the chart. The default is 50.
+    center_to_mean : bool, optional
+        Whether to center the bubbles on the mean. The default is `False`.
+    filter_by : str, optional
+        Column used to filter the data.
+    sort_by : str, optional
+        Column used to sort the data.
+    ascending : bool, optional
+        Sort order for the data. The default is `False`.
+    table_rows : int, optional
+        Number of rows to display in the tables. The default is 10.
+    figsize : tuple[float, float], optional
+        Size of the created figure. The default is FIG_SIZE.
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure containing the composite bubble chart and tables.
+    """
+    validate_dataframe(pd_df, cols=[label, x, y, z], sort_by=sort_by)
+    if style is None:
+        style = WORDCLOUD_STYLE_TEMPLATE
+    fig = plt.figure(figsize=figsize)
+    gs = fig.add_gridspec(
+        2,
+        2,
+        height_ratios=[2, 1],
+        width_ratios=[1, 1],
+    )
+    ax = fig.add_subplot(gs[0, :])
+    ax2 = fig.add_subplot(gs[1, 0])
+    ax3 = fig.add_subplot(gs[1, 1])
+
+    aplot_bubble(
+        pd_df=pd_df,
+        label=label,
+        x=x,
+        y=y,
+        z=z,
+        max_values=max_values,
+        center_to_mean=center_to_mean,
+        sort_by=sort_by,
+        ascending=ascending,
+        title=title,
+        style=style,
+        ax=ax,
+    )
+
+    ax2 = aplot_table(
+        pd_df=pd_df,
+        cols=[label, z, y, x],
+        title=f"Top {table_rows}",
+        ax=ax2,
+        sort_by=sort_by,
+        ascending=False,
+        max_values=table_rows,
+        style=style,
+    )
+
+    ax3 = aplot_table(
+        pd_df=pd_df,
+        cols=[label, z, y, x],
+        title=f"Last {table_rows}",
+        ax=ax3,
+        sort_by=sort_by,
+        ascending=True,
+        max_values=table_rows,
+        style=style,
+    )
+    if title:
+        fig.tight_layout(rect=(0, 0, 1, 0.95))
+    else:
+        fig.tight_layout()
+    return fig
+
+
+def fplot_wordcloud_network2(
+    edges_df: pd.DataFrame,
+    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: Optional[StyleTemplate] = None,
+    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
+    ----------
+    edges_df : pd.DataFrame
+        DataFrame containing edge connections for the network plot.
+    edge_source_col : str, optional
+        Column in ``edges_df`` containing source nodes. The default is ``"source"``.
+    edge_target_col : str, optional
+        Column in ``edges_df`` containing target nodes. The default is ``"target"``.
+    edge_weight_col : str, optional
+        Column in ``edges_df`` containing edge weights. The default is ``"weight"``.
+    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``.
+
+    Returns
+    -------
+    Figure
+        Matplotlib figure containing the word cloud on top and network below.
+    """
+    if not style:
+        style = WORDCLOUD_STYLE_TEMPLATE
+    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)
+
+    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,
+        )
+
+    network = NetworkGraph.from_pandas_edgelist(
+        edges_df=edges_df,
+        source=edge_source_col,
+        target=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:
+        fig.tight_layout()
+    return fig
+
+
 def fplot_wordcloud_network(
     node_df: pd.DataFrame,
     edges_df: pd.DataFrame,
@@ -205,7 +423,7 @@ def fplot_wordcloud_network(
     max_words: int = MAX_RESULTS,
     stopwords: Optional[Iterable[str]] = None,
     title: Optional[str] = None,
-    style: StyleTemplate = WORDCLOUD_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     wordcloud_style: Optional[StyleTemplate] = None,
     network_style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = FIG_SIZE,
@@ -246,6 +464,8 @@ def fplot_wordcloud_network(
     Figure
         Matplotlib figure containing the word cloud on top and network below.
     """
+    if not style:
+        style = WORDCLOUD_STYLE_TEMPLATE
     fig_raw, axes_raw = plt.subplots(
         2,
         1,

MatplotLibAPI/heatmap.py

@@ -6,17 +6,15 @@ 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 .types import CorrelationMethod
 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",
@@ -27,7 +25,6 @@ __all__ = [
 ]
 
 
-@register_dataframe_accessor("heatmap")
 class Heatmap(BasePlot):
     """Class for plotting heatmaps and correlation matrices."""
 
@@ -43,26 +40,30 @@ class Heatmap(BasePlot):
         self.y = y
         self.value = value
 
-    @property
-    def correlation_matrix(self) -> pd.DataFrame:
+    def correlation_matrix(
+        self,
+        correlation_method: CorrelationMethod = "pearson",
+    ) -> pd.DataFrame:
         """Compute the correlation matrix for the underlying DataFrame."""
-        return self._obj.corr()
+        return self._obj.corr(method=correlation_method)
 
     def aplot(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         ax: Optional[Axes] = None,
         **kwargs: Any,
     ) -> Axes:
         """Plot a heatmap on an existing Matplotlib axes."""
-        plot_ax = _get_axis(ax)
+        if not style:
+            style = HEATMAP_STYLE_TEMPLATE
+        plot_ax = BasePlot.get_axis(ax)
         heatmap_kwargs: dict[str, Any] = {
             "data": self._obj,
             "cmap": style.palette,
             "ax": plot_ax,
         }
-        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+        sns.heatmap(**BasePlot.merge_kwargs(heatmap_kwargs, kwargs))
 
         plot_ax.set_xlabel(string_formatter(self.x))
         plot_ax.set_ylabel(string_formatter(self.y))
@@ -70,40 +71,26 @@ class Heatmap(BasePlot):
             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,
+        style: Optional[StyleTemplate] = None,
+        correlation_method: CorrelationMethod = "pearson",
         ax: Optional[Axes] = None,
         **kwargs: Any,
     ) -> Axes:
         """Plot a correlation matrix heatmap on existing axes."""
-        plot_ax = _get_axis(ax)
+        if not style:
+            style = HEATMAP_STYLE_TEMPLATE
+        plot_ax = BasePlot.get_axis(ax)
         heatmap_kwargs: dict[str, Any] = {
-            "data": self.correlation_matrix,
+            "data": self.correlation_matrix(correlation_method),
             "cmap": style.palette,
             "annot": True,
             "fmt": ".2f",
             "ax": plot_ax,
         }
-        sns.heatmap(**_merge_kwargs(heatmap_kwargs, kwargs))
+        sns.heatmap(**BasePlot.merge_kwargs(heatmap_kwargs, kwargs))
         if title:
             plot_ax.set_title(title)
         return plot_ax
@@ -111,20 +98,18 @@ class Heatmap(BasePlot):
     def fplot_correlation_matrix(
         self,
         title: Optional[str] = None,
-        style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+        style: Optional[StyleTemplate] = None,
         figsize: Tuple[float, float] = (10, 6),
+        correlation_method: CorrelationMethod = "pearson",
     ) -> 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)
+        if not style:
+            style = HEATMAP_STYLE_TEMPLATE
+        fig, ax = BasePlot.create_fig(figsize=figsize, style=style)
         self.aplot_correlation_matrix(
             title=title,
             style=style,
+            correlation_method=correlation_method,
             ax=ax,
         )
         return fig
@@ -163,7 +148,7 @@ def aplot_heatmap(
     y: str,
     value: str,
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     ax: Optional[Axes] = None,
     **kwargs: Any,
 ) -> Axes:
@@ -183,27 +168,51 @@ def aplot_heatmap(
 
 def aplot_correlation_matrix(
     pd_df: pd.DataFrame,
-    columns: Optional[Sequence[str]] = None,
-    method: CorrelationMethod = "pearson",
+    x: str,
+    y: str,
+    value: str,
+    correlation_method: CorrelationMethod = "pearson",
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     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
+    """Plot a correlation matrix heatmap on existing Matplotlib axes.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        Source dataframe containing correlation inputs.
+    x : str
+        Column used for heatmap x-axis labels.
+    y : str
+        Column used for heatmap y-axis labels.
+    value : str
+        Column providing values before correlation aggregation.
+    correlation_method : CorrelationMethod, optional
+        Correlation method. The default is ``"pearson"``.
+    title : str, optional
+        Plot title. The default is ``None``.
+    style : StyleTemplate, optional
+        Style template for rendering. The default is ``None``.
+    ax : Axes, optional
+        Matplotlib axes to draw on. If ``None``, use current axes.
+    **kwargs : Any
+        Additional keyword arguments forwarded to seaborn.
+
+    Returns
+    -------
+    Axes
+        The Matplotlib axes containing the correlation heatmap.
+    """
+    return Heatmap(
+        pd_df=pd_df,
+        x=x,
+        y=y,
+        value=value,
+    ).aplot_correlation_matrix(
+        title=title, style=style, correlation_method=correlation_method, ax=ax
+    )
 
 
 def fplot_heatmap(
@@ -212,7 +221,7 @@ def fplot_heatmap(
     y: str,
     value: str,
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = (10, 6),
 ) -> Figure:
     """Plot a matrix heatmap on a new figure."""
@@ -234,8 +243,9 @@ def fplot_correlation_matrix(
     y: str,
     value: str,
     title: Optional[str] = None,
-    style: StyleTemplate = HEATMAP_STYLE_TEMPLATE,
+    style: Optional[StyleTemplate] = None,
     figsize: Tuple[float, float] = (10, 6),
+    correlation_method: CorrelationMethod = "pearson",
 ) -> Figure:
     """Plot a correlation matrix heatmap on a new figure."""
     return Heatmap(
@@ -243,4 +253,6 @@ def fplot_correlation_matrix(
         x=x,
         y=y,
         value=value,
-    ).fplot_correlation_matrix(title=title, style=style, figsize=figsize)
+    ).fplot_correlation_matrix(
+        title=title, style=style, figsize=figsize, correlation_method=correlation_method
+    )

MatplotLibAPI/histogram.py

@@ -3,9 +3,7 @@
 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
 
@@ -19,12 +17,10 @@ from .style_template import (
     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."""
 
@@ -49,7 +45,7 @@ class Histogram(BasePlot):
     ) -> Axes:
 
         validate_dataframe(self._obj, cols=[self.column])
-        plot_ax = _get_axis(ax)
+        plot_ax = BasePlot.get_axis(ax)
         histplot_kwargs: dict[str, Any] = {
             "data": self._obj,
             "x": self.column,
@@ -59,7 +55,7 @@ class Histogram(BasePlot):
             "edgecolor": style.background_color,
             "ax": plot_ax,
         }
-        sns.histplot(**_merge_kwargs(histplot_kwargs, kwargs))
+        sns.histplot(**BasePlot.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")
@@ -67,26 +63,6 @@ class Histogram(BasePlot):
             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,

MatplotLibAPI/network/__init__.py

@@ -7,6 +7,7 @@ organizing implementation details in submodules.
 from .constants import _DEFAULT, _WEIGHT_PERCENTILES
 from .core import NETWORK_STYLE_TEMPLATE, NetworkGraph
 from .plot import (
+    trim_low_degree_nodes,
     aplot_network,
     aplot_network_node,
     aplot_network_components,
@@ -17,6 +18,7 @@ from .plot import (
 from .scaling import _scale_weights, _softmax
 
 __all__ = [
+    "trim_low_degree_nodes",
     "aplot_network",
     "aplot_network_node",
     "aplot_network_components",

MatplotLibAPI/network/constants.py

@@ -19,4 +19,5 @@ _DEFAULT = {
 
 _WEIGHT_PERCENTILES = np.arange(10, 100, 10)
 
+
 __all__ = ["_DEFAULT", "_WEIGHT_PERCENTILES"]