Merge branch 'main' into add_evaluation_options

Author: florian-huber

graphconstructor/graph.py

@@ -3,6 +3,7 @@
 import numpy as np
 import pandas as pd
 import scipy.sparse as sp
+from scipy.sparse.csgraph import connected_components
 
 
 SymOp = Literal["max", "min", "average"]
@@ -240,13 +241,47 @@ def sorted_by(self, col: str) -> "Graph":
         meta2 = self.meta.iloc[order].reset_index(drop=True)
         return Graph(adj=A2, directed=self.directed, weighted=self.weighted, meta=meta2)
 
-    def degree(self) -> np.ndarray:
-        """Return (out-)degree for directed, degree for undirected. For weighted graphs sum of weights."""
-        if self.weighted:
+    def degree(self, ignore_weights: bool = False) -> np.ndarray:
+        """Return (out-)degree for directed, degree for undirected. For weighted graphs sum of weights.
+        
+        Parameters
+        ----------
+        ignore_weights
+            If True, count number of edges only (treat as unweighted).
+            Default is False.
+        """
+        if self.weighted and not ignore_weights:
             deg = np.asarray(self.adj.sum(axis=1)).ravel()
         else:
             # count nonzeros per row
             deg = np.diff(self.adj.indptr).astype(float)
         if not self.directed:
             return deg
         return deg  # could also return (out_degree, in_degree) if desired
+    
+    def is_connected(self) -> bool:
+        """Return True if the graph is connected (undirected) or strongly connected (directed)."""
+        n_components = connected_components(
+            self.adj,
+            directed=self.directed,
+            connection="strong" if self.directed else "weak",
+            return_labels=False
+            )
+        return n_components == 1
+
+    def connected_components(self, return_labels: bool = False) -> bool:
+        """Return the number of connected components or labels per node.
+        For directed graphs, strongly connected components are returned.
+        
+        Parameters
+        ----------
+        return_labels
+            If True, return an array of component labels per node instead of the number of components.
+            Default is False.
+        """
+        return connected_components(
+            self.adj,
+            directed=self.directed,
+            connection="strong" if self.directed else "weak",
+            return_labels=return_labels
+            )

graphconstructor/visualization/__init__.py

@@ -1,6 +1,9 @@
+from .graph_statistics import plot_degree_distribution, plot_degree_distributions_grid
 from .network_plots_nx import plot_graph_by_class
 
 
 __all__ = [
+    "plot_degree_distribution",
+    "plot_degree_distributions_grid",
     "plot_graph_by_class",
 ]

graphconstructor/visualization/graph_statistics.py

@@ -0,0 +1,212 @@
+from typing import Iterable, Optional, Tuple
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+def plot_degree_distribution(
+    graph,
+    *,
+    x_scale: str = "log",
+    y_scale: str = "log",
+    ax: Optional[plt.Axes] = None,
+    normalize: bool = True,
+    include_zero_degree: bool = False,
+    label: Optional[str] = None,
+    marker: str = "o",
+    markersize: float = 5.0,
+) -> Tuple[plt.Figure, plt.Axes]:
+    """
+    Plot the degree distribution p(k) vs k for a single graph.
+
+    Parameters
+    ----------
+    graph
+        Object exposing `.degree()` -> 1-D numpy array of node degrees.
+    x_scale, y_scale
+        Matplotlib scales ("linear", "log", "symlog", etc.). Defaults "log" / "log".
+    ax
+        Optional axes to draw on. If None, a new figure and axes are created.
+    normalize
+        If True, plot probability mass p(k) = count(k) / N. If False, plot raw counts.
+    include_zero_degree
+        If True, include k=0 in the plot (useful if not using log scale).
+        Note: when using log scale, k=0 cannot be shown and will be dropped.
+    label
+        Optional label for legend.
+    marker
+        Matplotlib marker style for the scatter points.
+    markersize
+        Size of scatter markers.
+
+    Returns
+    -------
+    (fig, ax)
+        The Matplotlib figure and axes used for plotting.
+
+    Notes
+    -----
+    - When `x_scale` or `y_scale` is "log", any k=0 or p(k)=0 entries are removed
+      to avoid invalid values on a log axis.
+    """
+    degrees = graph.degree()
+    if degrees.ndim != 1:
+        raise ValueError("graph.degree() must return a 1-D array of degrees.")
+    if degrees.size == 0:
+        # Create empty plot but still return fig/ax for consistency
+        if ax is None:
+            fig, ax = plt.subplots()
+        else:
+            fig = ax.figure
+        ax.set_xlabel("Degree k")
+        ax.set_ylabel("p(k)" if normalize else "count(k)")
+        ax.set_xscale(x_scale)
+        ax.set_yscale(y_scale)
+        ax.set_title(getattr(graph, "name", "Degree distribution (empty graph)"))
+        return fig, ax
+
+    if np.any(degrees < 0):
+        raise ValueError("Degrees must be nonnegative.")
+
+    # Compute counts per unique degree efficiently
+    # Using np.bincount for speed (requires nonnegative ints)
+    if not np.issubdtype(degrees.dtype, np.integer):
+        # allow float degrees that are whole numbers
+        if np.all(np.mod(degrees, 1) == 0):
+            degrees = degrees.astype(int)
+        else:
+            raise ValueError("Degrees must be integers for degree distributions.")
+
+    counts = np.bincount(degrees)  # index = k, value = count(k)
+    ks = np.nonzero(counts)[0]     # degrees that actually appear
+    freqs = counts[ks].astype(float)
+
+    if normalize:
+        total = freqs.sum()
+        if total == 0:
+            raise ValueError("No nodes with valid degrees found.")
+        pk = freqs / total
+    else:
+        pk = freqs
+
+    # Handle zero-degree inclusion/exclusion
+    if not include_zero_degree or x_scale == "log":
+        mask = ks > 0
+        ks, pk = ks[mask], pk[mask]
+
+    # On log y, remove zero probabilities (shouldn't occur if computed as above)
+    if y_scale == "log":
+        nz = pk > 0
+        ks, pk = ks[nz], pk[nz]
+
+    # Prepare axes
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+
+    ax.scatter(ks, pk, marker=marker, s=markersize**2, label=label)
+    ax.set_xlabel("Degree k")
+    ax.set_ylabel("p(k)" if normalize else "count(k)")
+    ax.set_xscale(x_scale)
+    ax.set_yscale(y_scale)
+
+    title_default = getattr(graph, "name", None)
+    if title_default:
+        ax.set_title(f"Degree distribution: {title_default}")
+    else:
+        ax.set_title("Degree distribution")
+
+    if label is not None:
+        ax.legend()
+
+    ax.grid(True, which="both", linestyle=":", linewidth=0.5, alpha=0.6)
+
+    return fig, ax
+
+
+def plot_degree_distributions_grid(
+    graphs: Iterable,
+    *,
+    ncols: int = 3,
+    x_scale: str = "log",
+    y_scale: str = "log",
+    normalize: bool = True,
+    include_zero_degree: bool = False,
+    figsize: Optional[Tuple[float, float]] = None,
+    tight_layout: bool = True,
+    sharex: bool = False,
+    sharey: bool = False,
+) -> Tuple[plt.Figure, np.ndarray]:
+    """
+    Plot a grid of degree distribution plots for multiple graphs.
+
+    Parameters
+    ----------
+    graphs
+        Iterable of Graph-like objects exposing `.degree() -> np.ndarray`.
+    ncols
+        Number of columns in the grid.
+    x_scale, y_scale
+        Axis scales for all subplots (defaults to "log").
+    normalize
+        If True, plot probability mass p(k). If False, raw counts.
+    include_zero_degree
+        Whether to include k=0 (will be dropped automatically on log x).
+    figsize
+        Optional figure size. If None, inferred from grid size.
+    tight_layout
+        Whether to call `fig.tight_layout()` at the end.
+    sharex, sharey
+        Whether to share x/y axes across subplots.
+
+    Returns
+    -------
+    (fig, axes)
+        Figure and 2D ndarray of Axes (some entries may be unused if the grid
+        is larger than the number of graphs).
+    """
+    graphs = list(graphs)
+    n = len(graphs)
+    if n == 0:
+        raise ValueError("`graphs` must contain at least one graph.")
+
+    nrows = np.ceil(n / ncols)
+    if figsize is None:
+        # heuristic: wider for more columns, taller for more rows
+        figsize = (4 * ncols, 3.2 * nrows)
+
+    fig, axes = plt.subplots(nrows=nrows, ncols=ncols, figsize=figsize, sharex=sharex, sharey=sharey)
+
+    # Ensure axes is 2D array for consistent indexing
+    if isinstance(axes, plt.Axes):
+        axes = np.array([[axes]])
+    elif axes.ndim == 1:
+        axes = axes.reshape(1, -1)
+
+    # Plot each graph
+    for i, graph in enumerate(graphs):
+        r, c = divmod(i, ncols)
+        ax = axes[r, c]
+        label = getattr(graph, "label", None)  # optional custom label field
+        plot_degree_distribution(
+            graph,
+            x_scale=x_scale,
+            y_scale=y_scale,
+            ax=ax,
+            normalize=normalize,
+            include_zero_degree=include_zero_degree,
+            label=label,
+        )
+        # Prefer a clean, concise title per subplot
+        title = getattr(graph, "name", None) or f"Graph {i+1}"
+        ax.set_title(title)
+
+    # Hide any unused axes
+    for j in range(n, nrows * ncols):
+        r, c = divmod(j, ncols)
+        axes[r, c].set_visible(False)
+
+    if tight_layout:
+        fig.tight_layout()
+
+    return fig, axes

tests/test_graph.py

@@ -122,6 +122,53 @@ def test_sorted_by_permuted_order():
     # adjacency must be permuted consistently
     assert G2.adj.shape == (3, 3)
 
+# ----------------- utilities -----------------
+def test_graph_is_connected_method():
+    # Connected undirected graph
+    A1 = _csr([1, 1, 1, 1], [0, 0, 1, 2], [1, 2, 2, 0], 3)
+    G1 = Graph.from_csr(A1, directed=False, weighted=True)
+    assert G1.is_connected()
+
+    # Disconnected undirected graph
+    A2 = _csr([1, 1], [0, 0], [1, 2], 4)
+    G2 = Graph.from_csr(A2, directed=False, weighted=True)
+    assert not G2.is_connected()
+
+    # Strongly connected directed graph
+    A3 = _csr([1, 1, 1, 1], [0, 1, 2, 2], [1, 2, 0, 1], 3)
+    G3 = Graph.from_csr(A3, directed=True, weighted=True)
+    assert G3.is_connected()
+
+    # Not strongly connected directed graph
+    A4 = _csr([1, 1], [0, 1], [1, 2], 3)
+    G4 = Graph.from_csr(A4, directed=True, weighted=True)
+    assert not G4.is_connected()
+
+
+def test_graph_connected_components_method():
+    # Undirected graph with 2 components
+    A = _csr([1, 1, 1, 1], [0, 0, 3, 3], [1, 2, 3, 4], 5)
+    G = Graph.from_csr(A, directed=False, weighted=True)
+    n_components, labels = G.connected_components(return_labels=True)
+    assert n_components == 2
+    assert set(labels) == {0, 1}
+    assert np.allclose(labels, np.array([0, 0, 0, 1, 1]))
+
+
+def test_graph_degree_method_weighted_and_unweighted():
+    A = _csr([2.0, 3.0, 4.0, 5.0], [0, 1, 3, 3], [1, 2, 2, 0], 4)
+    G_weighted = Graph.from_csr(A, directed=False, weighted=True)
+    deg_weighted = G_weighted.degree()
+    assert np.allclose(deg_weighted, np.array([7.0, 5.0, 7.0, 9.0]))
+
+    # ignore weights
+    deg_weighted = G_weighted.degree(ignore_weights=True)
+    assert np.allclose(deg_weighted, np.array([2, 2, 2, 2]))
+
+    G_unweighted = Graph.from_csr(A, directed=False, weighted=False)
+    deg_unweighted = G_unweighted.degree()
+    assert np.allclose(deg_unweighted, np.array([2, 2, 2, 2]))
+
 
 # ----------------- exporters -----------------
 @pytest.mark.skipif(not HAS_NX, reason="networkx not installed")