MatplotLibAPI 3.2.14__py3-none-any.whl → 3.2.15__py3-none-any.whl

MatplotLibAPI/Area.py

@@ -0,0 +1,76 @@
+"""Area chart helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    AREA_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_area(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    label: Optional[str] = None,
+    stacked: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = AREA_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot area charts, optionally stacked for part-to-whole trends."""
+    cols = [x, y]
+    if label:
+        cols.append(label)
+    validate_dataframe(pd_df, cols=cols)
+    plot_ax = _get_axis(ax)
+
+    if label:
+        pivot_df = pd_df.pivot_table(
+            index=x, columns=label, values=y, aggfunc="sum"
+        ).sort_index()
+        pivot_df.plot(kind="area", stacked=stacked, alpha=0.7, ax=plot_ax)
+    else:
+        sorted_df = pd_df.sort_values(by=x)
+        plot_ax.fill_between(
+            sorted_df[x], sorted_df[y], color=style.font_color, alpha=0.4
+        )
+        plot_ax.plot(sorted_df[x], sorted_df[y], color=style.font_color)
+
+    plot_ax.set_xlabel(string_formatter(x))
+    plot_ax.set_ylabel(string_formatter(y))
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_area(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    label: Optional[str] = None,
+    stacked: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = AREA_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot area charts on a new figure."""
+    return _wrap_aplot(
+        aplot_area,
+        pd_df=pd_df,
+        figsize=figsize,
+        x=x,
+        y=y,
+        label=label,
+        stacked=stacked,
+        title=title,
+        style=style,
+    )

MatplotLibAPI/Bar.py

@@ -0,0 +1,79 @@
+"""Bar and stacked bar chart helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_bar(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    group: Optional[str] = None,
+    stacked: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot bar or stacked bar charts for categorical comparisons."""
+    cols = [category, value]
+    if group:
+        cols.append(group)
+    validate_dataframe(pd_df, cols=cols)
+
+    plot_ax = _get_axis(ax)
+    plot_df = pd_df.copy()
+
+    if group:
+        pivot_df = plot_df.pivot_table(
+            index=category, columns=group, values=value, aggfunc="sum"
+        )
+        pivot_df.plot(kind="bar", stacked=stacked, ax=plot_ax, alpha=0.85)
+    else:
+        sns.barplot(
+            data=plot_df, x=category, y=value, palette=style.palette, ax=plot_ax
+        )
+
+    plot_ax.set_facecolor(style.background_color)
+    plot_ax.set_xlabel(string_formatter(category))
+    plot_ax.set_ylabel(string_formatter(value))
+    if title:
+        plot_ax.set_title(title)
+    plot_ax.tick_params(axis="x", labelrotation=45)
+    return plot_ax
+
+
+def fplot_bar(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    group: Optional[str] = None,
+    stacked: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot bar or stacked bar charts on a new figure."""
+    return _wrap_aplot(
+        aplot_bar,
+        pd_df=pd_df,
+        figsize=figsize,
+        category=category,
+        value=value,
+        group=group,
+        stacked=stacked,
+        title=title,
+        style=style,
+    )

MatplotLibAPI/BoxViolin.py

@@ -0,0 +1,69 @@
+"""Box and violin plot helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_box_violin(
+    pd_df: pd.DataFrame,
+    column: str,
+    by: Optional[str] = None,
+    violin: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot box or violin charts to summarize distributions."""
+    cols = [column]
+    if by:
+        cols.append(by)
+    validate_dataframe(pd_df, cols=cols)
+    plot_ax = _get_axis(ax)
+
+    if violin:
+        sns.violinplot(data=pd_df, x=by, y=column, palette=style.palette, ax=plot_ax)
+    else:
+        sns.boxplot(data=pd_df, x=by, y=column, palette=style.palette, ax=plot_ax)
+
+    plot_ax.set_facecolor(style.background_color)
+    plot_ax.set_ylabel(string_formatter(column))
+    if by:
+        plot_ax.set_xlabel(string_formatter(by))
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_box_violin(
+    pd_df: pd.DataFrame,
+    column: str,
+    by: Optional[str] = None,
+    violin: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot box or violin charts on a new figure."""
+    return _wrap_aplot(
+        aplot_box_violin,
+        pd_df=pd_df,
+        figsize=figsize,
+        column=column,
+        by=by,
+        violin=violin,
+        title=title,
+        style=style,
+    )

MatplotLibAPI/Heatmap.py

@@ -0,0 +1,113 @@
+"""Heatmap and correlation matrix helpers."""
+
+from typing import Any, Optional, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from pandas._typing import CorrelationMethod
+
+from .StyleTemplate import (
+    HEATMAP_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+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."""
+    validate_dataframe(pd_df, cols=[x, y, value])
+    plot_ax = _get_axis(ax)
+
+    pivot_df = pd_df.pivot_table(index=y, columns=x, values=value, aggfunc="mean")
+    sns.heatmap(pivot_df, cmap=style.palette, ax=plot_ax)
+
+    plot_ax.set_xlabel(string_formatter(x))
+    plot_ax.set_ylabel(string_formatter(y))
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+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."""
+    subset = (
+        columns
+        if columns is not None
+        else pd_df.select_dtypes(include=[np.number]).columns
+    )
+    if len(subset) == 0:
+        raise AttributeError("No numeric columns available for correlation matrix")
+
+    validate_dataframe(pd_df, cols=list(subset))
+    plot_ax = _get_axis(ax)
+
+    selected: pd.DataFrame = pd_df.loc[:, list(subset)]
+    corr = selected.corr(method=method)
+    sns.heatmap(corr, cmap=style.palette, annot=True, fmt=".2f", ax=plot_ax)
+    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 _wrap_aplot(
+        aplot_heatmap,
+        pd_df=pd_df,
+        figsize=figsize,
+        x=x,
+        y=y,
+        value=value,
+        title=title,
+        style=style,
+    )
+
+
+def fplot_correlation_matrix(
+    pd_df: pd.DataFrame,
+    columns: Optional[Sequence[str]] = None,
+    method: CorrelationMethod = "pearson",
+    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 _wrap_aplot(
+        aplot_correlation_matrix,
+        pd_df=pd_df,
+        figsize=figsize,
+        columns=columns,
+        method=method,
+        title=title,
+        style=style,
+    )

MatplotLibAPI/Histogram.py

@@ -0,0 +1,69 @@
+"""Histogram and KDE plotting helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_histogram_kde(
+    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."""
+    validate_dataframe(pd_df, cols=[column])
+    plot_ax = _get_axis(ax)
+
+    sns.histplot(
+        data=pd_df,
+        x=column,
+        bins=bins,
+        kde=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(column))
+    plot_ax.set_ylabel("Frequency")
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_histogram_kde(
+    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."""
+    return _wrap_aplot(
+        aplot_histogram_kde,
+        pd_df=pd_df,
+        figsize=figsize,
+        column=column,
+        bins=bins,
+        kde=kde,
+        title=title,
+        style=style,
+    )

MatplotLibAPI/Network.py

@@ -257,6 +257,21 @@ class NetworkGraph:
         """Return an ``AdjacencyView`` of the graph."""
         return AdjacencyView(self._nx_graph.adj)
 
+    @property
+    def connected_components(self) -> List[set]:
+        """Return the connected components of the graph."""
+        return list(nx.connected_components(self._nx_graph))
+
+    @property
+    def number_of_nodes(self) -> int:
+        """Return the number of nodes in the graph."""
+        return self._nx_graph.number_of_nodes()
+
+    @property
+    def number_of_edges(self) -> int:
+        """Return the number of edges in the graph."""
+        return self._nx_graph.number_of_edges()
+
     def edge_subgraph(self, edges: Iterable) -> "NetworkGraph":
         """Return a subgraph containing only the specified edges.
 
@@ -441,12 +456,11 @@ class NetworkGraph:
         return ax
 
     def plot_network_components(self, *args: Any, **kwargs: Any) -> List:
-        """Plot network components (DEPRECATED).
+        """Plot network components.
 
         .. deprecated:: 0.1.0
-            This method will be removed in a future version.
-            Please use `fplot_network_components` which provides a figure-level interface
-            for plotting components.
+          `plot_network_components` will be removed in a future version.
+          Use `fplot_network_components` instead.
         """
         import warnings
 
@@ -580,7 +594,37 @@ class NetworkGraph:
         return NetworkGraph(network_G)
 
 
-def _prepare_network_graph(
+def compute_network_grid(
+    connected_components: List[set], style: StyleTemplate
+) -> Tuple[Figure, np.ndarray]:
+    """Compute the grid layout for network component subplots.
+
+    Parameters
+    ----------
+    connected_components : list[set]
+        A list of sets, where each set contains the nodes of a connected component.
+    style : StyleTemplate
+        The style template used for plotting.
+
+    Returns
+    -------
+    Tuple[Figure, np.ndarray]
+        A tuple containing the Matplotlib figure and the grid of axes.
+    """
+    n_components = len(connected_components)
+    n_cols = int(np.ceil(np.sqrt(n_components)))
+    n_rows = int(np.ceil(n_components / n_cols))
+    fig, axes_grid = plt.subplots(n_rows, n_cols, figsize=(19.2, 10.8))
+    fig = cast(Figure, fig)
+    fig.patch.set_facecolor(style.background_color)
+    if not isinstance(axes_grid, np.ndarray):
+        axes = np.array([axes_grid])
+    else:
+        axes = axes_grid.flatten()
+    return fig, axes
+
+
+def prepare_network_graph(
     pd_df: pd.DataFrame,
     source: str,
     target: str,
@@ -588,7 +632,37 @@ def _prepare_network_graph(
     sort_by: Optional[str],
     node_list: Optional[List],
 ) -> NetworkGraph:
-    """Prepare NetworkGraph for plotting."""
+    """Prepare a NetworkGraph for plotting from a pandas DataFrame.
+
+    This function takes a DataFrame and prepares it for network visualization by:
+    1. Filtering the DataFrame to include only the nodes in `node_list` (if provided).
+    2. Validating the DataFrame to ensure it has the required columns.
+    3. Creating a `NetworkGraph` from the edge list.
+    4. Extracting the k-core of the graph (k=2) to focus on the main structure.
+    5. Calculating node weights based on the sum of their top k edge weights.
+    6. Trimming the graph to keep only the top k edges per node.
+
+    Parameters
+    ----------
+    pd_df : pd.DataFrame
+        DataFrame containing the edge list.
+    source : str
+        Column name for source nodes.
+    target : str
+        Column name for target nodes.
+    weight : str
+        Column name for edge weights.
+    sort_by : str, optional
+        Column to sort the DataFrame by before processing.
+    node_list : list, optional
+        A list of nodes to include in the graph. If provided, the DataFrame
+        will be filtered to include only edges connected to these nodes.
+
+    Returns
+    -------
+    NetworkGraph
+        The prepared `NetworkGraph` object.
+    """
     if node_list:
         df = pd_df.loc[
             (pd_df["source"].isin(node_list)) | (pd_df["target"].isin(node_list))
@@ -648,12 +722,13 @@ def aplot_network(
     Axes
         Matplotlib axes with the plotted network.
     """
-    graph = _prepare_network_graph(pd_df, source, target, weight, sort_by, node_list)
+    graph = prepare_network_graph(pd_df, source, target, weight, sort_by, node_list)
     return graph.plot_network(title=title, style=style, weight=weight, ax=ax)
 
 
 def aplot_network_components(
     pd_df: pd.DataFrame,
+    axes: Optional[np.ndarray],
     source: str = "source",
     target: str = "target",
     weight: str = "weight",
@@ -662,7 +737,6 @@ def aplot_network_components(
     sort_by: Optional[str] = None,
     node_list: Optional[List] = None,
     ascending: bool = False,
-    axes: Optional[np.ndarray] = None,
 ) -> None:
     """Plot network components separately on multiple axes.
 
@@ -686,10 +760,10 @@ def aplot_network_components(
         Nodes to include.
     ascending : bool, optional
         Sort order for the data. The default is `False`.
-    axes : np.ndarray, optional
-        Existing axes to draw on. If None, new axes are created.
+    axes : np.ndarray
+        Existing axes to draw on.
     """
-    graph = _prepare_network_graph(pd_df, source, target, weight, sort_by, node_list)
+    graph = prepare_network_graph(pd_df, source, target, weight, sort_by, node_list)
 
     connected_components = list(nx.connected_components(graph._nx_graph))
 
@@ -699,37 +773,27 @@ def aplot_network_components(
                 ax.set_axis_off()
         return
 
-    if axes is None:
-        n_components = len(connected_components)
-        n_cols = int(np.ceil(np.sqrt(n_components)))
-        n_rows = int(np.ceil(n_components / n_cols))
-        fig, axes_grid = plt.subplots(n_rows, n_cols, figsize=(19.2, 10.8))
-        fig = cast(Figure, fig)
-        fig.patch.set_facecolor(style.background_color)
-        if not isinstance(axes_grid, np.ndarray):
-            axes = np.array([axes_grid])
-        else:
-            axes = axes_grid.flatten()
+    local_axes = axes
+    if local_axes is None:
+        fig, local_axes = compute_network_grid(connected_components, style)
 
     i = -1
     for i, component in enumerate(connected_components):
-        if i < len(axes):
+        if i < len(local_axes):
             if len(component) > 5:
                 component_graph = graph.subgraph(node_list=list(component))
                 component_graph.plot_network(
                     title=f"{title}::{i}" if title else str(i),
                     style=style,
                     weight=weight,
-                    ax=axes[i],
+                    ax=local_axes[i],
                 )
-            axes[i].set_axis_on()
+            local_axes[i].set_axis_on()
         else:
-            break  # Stop if there are more components than axes
+            break
 
-    # Turn off any unused axes
-    if axes is not None:
-        for j in range(i + 1, len(axes)):
-            axes[j].set_axis_off()
+    for j in range(i + 1, len(local_axes)):
+        local_axes[j].set_axis_off()
 
 
 def fplot_network(

MatplotLibAPI/Pie.py

@@ -0,0 +1,66 @@
+"""Pie and donut chart helpers."""
+
+from typing import Any, Dict, Optional, Tuple
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import PIE_STYLE_TEMPLATE, StyleTemplate, validate_dataframe
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_pie_donut(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    donut: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = PIE_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot pie or donut charts for categorical share visualization."""
+    validate_dataframe(pd_df, cols=[category, value])
+    plot_ax = _get_axis(ax)
+    labels = pd_df[category].astype(str).tolist()
+    sizes = pd_df[value]
+
+    wedgeprops: Optional[Dict[str, Any]] = None
+    if donut:
+        wedgeprops = {"width": 0.3}
+    wedges, *_ = plot_ax.pie(
+        sizes,
+        labels=labels,
+        autopct="%1.1f%%",
+        colors=sns.color_palette(style.palette),
+        wedgeprops=wedgeprops,
+    )
+    plot_ax.axis("equal")
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_pie_donut(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    donut: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = PIE_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (8, 8),
+) -> Figure:
+    """Plot pie or donut charts on a new figure."""
+    return _wrap_aplot(
+        aplot_pie_donut,
+        pd_df=pd_df,
+        figsize=figsize,
+        category=category,
+        value=value,
+        donut=donut,
+        title=title,
+        style=style,
+    )