Add viz/temporal extras and make plotting code import-safe without matplotlib

Author: FraLotito

.github/workflows/tests.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install -e ".[dev]"
-          python -m pip install matplotlib
+          python -m pip install matplotlib tqdm
 
       - name: Pytest
         run: pytest

hypergraphx/viz/draw_communities.py

@@ -1,6 +1,5 @@
 from typing import Optional, Tuple, Union
 
-import matplotlib.pyplot as plt
 import networkx as nx
 import numpy as np
 
@@ -13,7 +12,7 @@ def draw_communities(
     u: np.array,
     col: dict,
     figsize: tuple = (7, 7),
-    ax: Optional[plt.Axes] = None,
+    ax: Optional["plt.Axes"] = None,
     pos: Optional[dict] = None,
     edge_color: str = "lightgrey",
     edge_width: float = 0.3,
@@ -33,6 +32,13 @@ def draw_communities(
     opt_dist: float = 0.2,
     show: bool = False,
 ):
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "draw_communities requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     """Visualize the node memberships of a hypergraph. Nodes are colored according to their memberships,
     which can be either hard- or soft-membership, and the node size is proportional to the degree in the hypergraph.
     Edges are the pairwise interactions of the hypergraph clique projection.

hypergraphx/viz/draw_hypergraph.py

@@ -1,7 +1,6 @@
 import random
 from typing import Optional, Union
 
-import matplotlib.pyplot as plt
 import networkx as nx
 import numpy as np
 
@@ -74,7 +73,7 @@ def Smooth_by_Chaikin(self, number_of_refinements):
 def draw_hypergraph(
     hypergraph: Hypergraph,
     figsize: tuple = (12, 7),
-    ax: Optional[plt.Axes] = None,
+    ax: Optional["plt.Axes"] = None,
     pos: Optional[dict] = None,
     edge_color: str = "lightgrey",
     hyperedge_color_by_order: Optional[dict] = None,
@@ -106,6 +105,12 @@ def draw_hypergraph(
     matplotlib.axes.Axes
         The axes the plot was drawn on.
     """
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "draw_hypergraph requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
 
     def _stable_color(order_value):
         rng = random.Random(order_value)

hypergraphx/viz/draw_motifs.py

@@ -1,7 +1,5 @@
-import matplotlib.pyplot as plt
 import networkx as nx
 import itertools
-from matplotlib.patches import Polygon
 
 
 def draw_motifs(
@@ -37,6 +35,14 @@ def draw_motifs(
     fig : matplotlib.figure.Figure
     axes : list[matplotlib.axes.Axes]
     """
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+        from matplotlib.patches import Polygon  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "draw_motifs requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     # Collect all unique nodes across all patterns
     all_nodes = set(
         itertools.chain.from_iterable(itertools.chain.from_iterable(patterns))

hypergraphx/viz/draw_projections.py

@@ -1,4 +1,3 @@
-import matplotlib.pyplot as plt
 import networkx as nx
 
 from hypergraphx import Hypergraph
@@ -33,6 +32,13 @@ def draw_bipartite(
     ax : matplotlib.axes.Axes.
         The axes the graph was drawn on.
     """
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "draw_bipartite requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     g, _ = bipartite_projection(h)
 
     if pos is None:
@@ -77,6 +83,13 @@ def draw_clique(h: Hypergraph, pos=None, ax=None, show: bool = False, **kwargs):
     -------
     ax : matplotlib.axes.Axes. The axes the graph was drawn on.
     """
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "draw_clique requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     g = clique_projection(h)
 
     if pos is None:

hypergraphx/viz/draw_simplicial.py

@@ -1,4 +1,3 @@
-import matplotlib.pyplot as plt
 import networkx as nx
 
 from hypergraphx.representations.projections import clique_projection
@@ -37,6 +36,13 @@ def draw_simplicial(
     matplotlib.axes.Axes
         The axes the plot was drawn on.
     """
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "draw_simplicial requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     G = clique_projection(HG, keep_isolated=True)
     if pos is None:
         pos = nx.spring_layout(G)

hypergraphx/viz/plot_motifs.py

@@ -1,8 +1,5 @@
 import math
 
-import matplotlib.pyplot as plt
-from matplotlib.patches import Polygon
-
 from hypergraphx.motifs.utils import generate_motifs
 
 
@@ -105,6 +102,14 @@ def _draw_motif_icon(
 ):
     if not events:
         return
+    # Lazy import of Polygon to keep this module import-safe without matplotlib.
+    try:
+        from matplotlib.patches import Polygon  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "plot_motifs requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     node_ids = sorted({n for ev in events for n in ev})
     k = len(node_ids)
     if k == 0:
@@ -261,6 +266,14 @@ def plot_motifs(
     annotate_fmt: str = "{:+.2f}",
     hover_labels: bool = False,
 ):
+    try:
+        import matplotlib.pyplot as plt  # type: ignore
+        from matplotlib.patches import Polygon  # type: ignore
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "plot_motifs requires matplotlib. Install with `pip install hypergraphx[viz]`."
+        ) from exc
+
     """
     Plot motifs. Motifs are sorted in such a way to show first lower order motifs, then higher order motifs.
 

pyproject.toml

@@ -37,12 +37,21 @@ dev = [
   "black>=24.3.0",
   "pre-commit",
 ]
+temporal = [
+  "tqdm",
+]
+viz = [
+  "matplotlib",
+  # optional interactive hover labels in plot_motifs
+  "mplcursors",
+]
 docs = [
   "sphinx",
   "furo",
   "nbsphinx",
   "matplotlib",
   "seaborn",
+  "tqdm",
 ]
 ml = [
   "scikit-learn",

tests/measures/test_shortest_paths_helpers.py

@@ -59,13 +59,13 @@ def test_calc_sizes_redundancies_and_props():
     assert "avg_size" in sample
     assert len(sample["sizes"]) == len(sample["sp"]) - 1
 
-    avg_ord = spl.copy()
-    avg_ord.values[:] = 2
-    np.fill_diagonal(avg_ord.values, 0)
-    avg_ord.values[0, 1] = 3
-    avg_ord.values[1, 0] = 3
+    # Avoid mutating DataFrame .values directly (can be read-only under some pandas modes).
+    avg_ord = np.full_like(spl.to_numpy(), 2.0)
+    np.fill_diagonal(avg_ord, 0)
+    avg_ord[0, 1] = 3
+    avg_ord[1, 0] = 3
     # If only one boolean class appears, unstack drops the other column.
-    props = calc_prop_true_dyad_paths_per_spl(spl.to_numpy(), avg_ord.to_numpy())
+    props = calc_prop_true_dyad_paths_per_spl(spl.to_numpy(), avg_ord)
     assert "spl" in props.columns
     assert any(col in props.columns for col in ("prop_False", "prop_True"))