initial implementation of s-connectedness

Author: nwlandry

examples/layouts/plot_barycenter_spring_layout.py

@@ -1,6 +1,6 @@
 """
 =================
-Barycenter spring 
+Barycenter spring
 =================
 
 Draw simple hypergraph with barycenter_spring layout.

examples/layouts/plot_simple_graph.py

@@ -1,6 +1,6 @@
 """
 =================
-Circular 
+Circular
 =================
 
 Draw simple hypergraph with circular layout.

examples/layouts/plot_spiral_layout.py

@@ -1,6 +1,6 @@
 """
 =================
-Spiral 
+Spiral
 =================
 
 Draw simple hypergraph with spiral layout.

examples/layouts/plot_triangular_lattice.py

@@ -12,8 +12,8 @@
 import xgi
 
 # generate lattice
-m, n = 5, 10 # lattice dimensions
-p = 0.5 # probability to promote 3-clique to 2-simplex
+m, n = 5, 10  # lattice dimensions
+p = 0.5  # probability to promote 3-clique to 2-simplex
 
 G = nx.triangular_lattice_graph(m, n, with_positions=True)
 
@@ -22,10 +22,10 @@
 inv_mapping = {v: k for k, v in mapping.items()}
 
 G_aux = nx.relabel_nodes(G, inv_mapping)
-S = xgi.flag_complex_d2(G_aux, p2=p) 
+S = xgi.flag_complex_d2(G_aux, p2=p)
 
 # draw lattice
 pos = {inv_mapping[k]: v for k, v in pos.items()}
 xgi.draw(S, pos=pos)
 
-plt.show()
+plt.show()

tests/algorithms/test_connected.py

@@ -28,6 +28,10 @@ def test_connected_components(edgelist1, edgelist2, edgelist4):
     assert sorted([len(cc) for cc in cc3]) == [5]
     assert {1, 2, 3, 4, 5} in cc3
 
+    cc4 = list(xgi.connected_components(H3, s=3))
+
+    assert sorted([len(cc) for cc in cc1]) == [1, 3, 4]
+
 
 def test_number_connected_components(edgelist1, edgelist2, edgelist4):
     H1 = xgi.Hypergraph(edgelist1)

xgi/algorithms/connected.py

@@ -13,14 +13,16 @@
 ]
 
 
-def is_connected(H):
+def is_connected(H, s=1):
     """
     A function to determine whether a hypergraph is connected.
 
     Parameters
     ----------
     H: Hypergraph object
         The hypergraph of interest
+    s: int, optional
+        The overlap parameter
 
     Returns
     -------
@@ -34,6 +36,13 @@ def is_connected(H):
     largest_connected_component
     largest_connected_hypergraph
 
+    References
+    ----------
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
+
     Example
     -------
     >>> import xgi
@@ -42,17 +51,19 @@ def is_connected(H):
     True
 
     """
-    return len(_plain_bfs(H, list(H.nodes)[0])) == len(H)
+    return len(_plain_bfs(H, list(H.nodes)[0], s=s)) == len(H)
 
 
-def connected_components(H):
+def connected_components(H, s=1):
     """
     A function to find the connected components of a hypergraph.
 
     Parameters
     ----------
     H: Hypergraph object
         The hypergraph of interest
+    s: int, optional
+        The overlap parameter
 
     Returns
     -------
@@ -66,6 +77,13 @@ def connected_components(H):
     largest_connected_component
     largest_connected_hypergraph
 
+    References
+    ----------
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
+
     Example
     -------
     >>> import xgi
@@ -77,19 +95,21 @@ def connected_components(H):
     seen = set()
     for v in H:
         if v not in seen:
-            c = _plain_bfs(H, v)
+            c = _plain_bfs(H, v, s=s)
             seen.update(c)
             yield c
 
 
-def number_connected_components(H):
+def number_connected_components(H, s=1):
     """
     A function to find the number of connected components of a hypergraph.
 
     Parameters
     ----------
     H: Hypergraph object
         The hypergraph of interest
+    s: int, optional
+        The overlap parameter
 
     Returns
     -------
@@ -103,6 +123,13 @@ def number_connected_components(H):
     largest_connected_component
     largest_connected_hypergraph
 
+    References
+    ----------
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
+
     Example
     -------
     >>> import xgi
@@ -115,20 +142,22 @@ def number_connected_components(H):
     seen = set()
     for v in H:
         if v not in seen:
-            c = _plain_bfs(H, v)
+            c = _plain_bfs(H, v, s=s)
             seen.update(c)
             num_cc += 1
     return num_cc
 
 
-def largest_connected_component(H):
+def largest_connected_component(H, s=1):
     """
     A function to find the largest connected component of a hypergraph.
 
     Parameters
     ----------
     H: Hypergraph object
         The hypergraph of interest
+    s: int, optional
+        The overlap parameter
 
     Returns
     -------
@@ -140,6 +169,13 @@ def largest_connected_component(H):
     connected_components
     largest_connected_hypergraph
 
+    References
+    ----------
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
+
     Example
     -------
     >>> import xgi
@@ -148,10 +184,10 @@ def largest_connected_component(H):
     50
 
     """
-    return max(connected_components(H), key=len)
+    return max(connected_components(H, s=s), key=len)
 
 
-def node_connected_component(H, n):
+def node_connected_component(H, n, s=1):
     """
     A function to find the connected component of which a node in the
     hypergraph is a part.
@@ -162,6 +198,8 @@ def node_connected_component(H, n):
         The hypergraph of interest
     n: hashable
         Node label
+    s: int, optional
+        The overlap parameter
 
     See Also
     --------
@@ -173,6 +211,13 @@ def node_connected_component(H, n):
         Returns the connected component of which the specified node in the
         hypergraph is a part.
 
+    References
+    ----------
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
+
     Example
     -------
     >>> import xgi
@@ -183,19 +228,21 @@ def node_connected_component(H, n):
 
     """
     if n in H:
-        return _plain_bfs(H, n)
+        return _plain_bfs(H, n, s=s)
     else:
         raise XGIError("Specified node is not in the hypergraph!")
 
 
-def largest_connected_hypergraph(H, in_place=False):
+def largest_connected_hypergraph(H, s=1, in_place=False):
     """
     A function to find the largest connected hypergraph from a data set.
 
     Parameters
     ----------
     H: Hypergraph
         The hypergraph of interest
+    s: int, optional
+        The overlap parameter
     in_place: bool, optional
         If False, creates a copy; if True, modifies the existing hypergraph.
         By default, True.
@@ -214,35 +261,63 @@ def largest_connected_hypergraph(H, in_place=False):
     connected_components
     largest_connected_component
 
+    References
+    ----------
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
+
     Example
     -------
     >>> import xgi
     >>> H = xgi.random_hypergraph(10, [0.1, 0.01], seed=1)
     >>> H_gcc = xgi.largest_connected_hypergraph(H)
     >>> print(H_gcc.num_nodes)
     6
-
     """
-    connected_nodes = max(connected_components(H), key=len)
+    connected_nodes = max(connected_components(H, s=s), key=len)
     if not in_place:
         return subhypergraph(H, nodes=connected_nodes).copy()
     else:
         H.remove_nodes_from(set(H.nodes).difference(connected_nodes))
 
 
-def _plain_bfs(H, source):
-    """A fast BFS node generator
+def _plain_bfs(H, source, s=1):
+    """A helper function to do an edge-first BFS search
+
+    Parameters
+    ----------
+    H : xgi.Hypergraph
+        The hypergraph
+    source : hashable
+        The ID of the starting node for the BFS
+    s : int, optional
+        The overlap of edges, by default 1
 
-    Source:
+    Returns
+    -------
+    set
+        A list of all nodes in the s-component.
+
+    References
+    ----------
     https://networkx.org/documentation/stable/_modules/networkx/algorithms/components/connected.html
+
+    Aksoy, S.G., Joslyn, C., Ortiz Marrero, C. et al.
+    Hypernetwork science via high-order hypergraph walks.
+    EPJ Data Sci. 9, 16 (2020).
+    https://doi.org/10.1140/epjds/s13688-020-00231-0
     """
-    seen = set()
-    nextlevel = {source}
+    seen_edges = set()
+    nodes = {source}
+    nextlevel = set(H.edges(H.nodes.memberships(source)).filterby("size", s, "geq"))
     while nextlevel:
         thislevel = nextlevel
         nextlevel = set()
-        for v in thislevel:
-            if v not in seen:
-                seen.add(v)
-                nextlevel.update(H.nodes.neighbors(v))
-    return seen
+        for e in thislevel:
+            if e not in seen_edges:
+                nodes.update(H.edges.members(e))
+                seen_edges.add(e)
+                nextlevel.update(H.edges.neighbors(e, s=s))
+    return nodes