Add Zachary's Karate Club

releasenotes/notes/karate-club-35708b3838689a0b.yaml

@@ -0,0 +1,14 @@
+---
+features:
+  - |
+    Added a new function, :func:`~rustworkx.generators.karate_club_graph` that
+    returns Zachary's Karate Club graph, commonly found in social network examples.
+
+    .. jupyter-execute::
+
+      import rustworkx.generators
+      from rustworkx.visualization import mpl_draw
+
+      graph = rustworkx.generators.karate_club_graph()
+      layout = rustworkx.circular_layout(graph)
+      mpl_draw(graph, pos=layout)

rustworkx-core/src/generators/karate_club.rs

@@ -0,0 +1,96 @@
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+use std::hash::Hash;
+
+use petgraph::data::{Build, Create};
+use petgraph::visit::{Data, NodeIndexable};
+
+use super::InvalidInputError;
+
+// Adapted from NetworkX, licensed under the MIT license
+// https://github.com/networkx/networkx/blob/409979eff35f02eff54f4eea3731736bd431dc2e/networkx/generators/social.py#L49
+const ZACHARY: &str = "\
+0 4 5 3 3 3 3 2 2 0 2 3 2 3 0 0 0 2 0 2 0 2 0 0 0 0 0 0 0 0 0 2 0 0\n\
+4 0 6 3 0 0 0 4 0 0 0 0 0 5 0 0 0 1 0 2 0 2 0 0 0 0 0 0 0 0 2 0 0 0\n\
+5 6 0 3 0 0 0 4 5 1 0 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 2 2 0 0 0 3 0\n\
+3 3 3 0 0 0 0 3 0 0 0 0 3 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+3 0 0 0 0 0 2 0 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+3 0 0 0 0 0 5 0 0 0 3 0 0 0 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+3 0 0 0 2 5 0 0 0 0 0 0 0 0 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+2 4 4 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+2 0 5 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 0 4 3\n\
+0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2\n\
+2 0 0 0 3 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+1 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+3 5 3 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 2\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 4\n\
+0 0 0 0 0 3 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+2 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 2\n\
+2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 1\n\
+2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 0\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 5 0 4 0 2 0 0 5 4\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 0 3 0 0 0 2 0 0\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 5 2 0 0 0 0 0 0 7 0 0\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 0 0 0 2\n\
+0 0 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 3 0 0 0 0 0 0 0 0 4\n\
+0 0 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 0 2\n\
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 0 0 4 0 0 0 0 0 3 2\n\
+0 2 0 0 0 0 0 0 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 3\n\
+2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 2 7 0 0 2 0 0 0 4 4\n\
+0 0 2 0 0 0 0 0 3 0 0 0 0 0 3 3 0 0 1 0 3 0 2 5 0 0 0 0 0 4 3 4 0 5\n\
+0 0 0 0 0 0 0 0 4 2 0 0 0 3 2 4 0 0 2 1 1 0 3 4 0 0 2 4 2 2 3 4 5 0";
+
+const MR_HI_MEMBERS: [usize; 17] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12, 13, 16, 17, 19, 21];
+
+/// Generates Zachary's Karate Club graph.
+///
+/// Zachary's Karate Club graph is a well-known social network that represents
+/// the relations between 34 members of a karate club.
+pub fn karate_club_graph<G, T, F, H, M>(
+    mut default_node_weight: F,
+    mut default_edge_weight: H,
+) -> Result<G, InvalidInputError>
+where
+    G: Build + Create + Data<NodeWeight = T, EdgeWeight = M> + NodeIndexable,
+    F: FnMut(bool) -> T,
+    H: FnMut(usize) -> M,
+    G::NodeId: Eq + Hash,
+{
+    let mut graph = G::with_capacity(0, 0);
+    let membership: std::collections::HashSet<usize> = MR_HI_MEMBERS.into_iter().collect();
+    let mut node_indices = Vec::new();
+    for (row, line) in ZACHARY.split('\n').enumerate() {
+        let node_id = graph.add_node(default_node_weight(membership.contains(&row)));
+        node_indices.push(node_id);
+        let this_row: Vec<usize> = line
+            .split_whitespace()
+            .map(|b| b.parse::<usize>().unwrap())
+            .collect();
+
+        for (col, entry) in this_row.iter().enumerate() {
+            if *entry >= 1 && row > col {
+                graph.add_edge(
+                    node_indices[col],
+                    node_indices[row],
+                    default_edge_weight(*entry),
+                );
+            }
+        }
+    }
+    Ok(graph)
+}

rustworkx-core/src/generators/mod.rs

@@ -22,6 +22,7 @@ mod grid_graph;
 mod heavy_hex_graph;
 mod heavy_square_graph;
 mod hexagonal_lattice_graph;
+mod karate_club;
 mod lollipop_graph;
 mod path_graph;
 mod petersen_graph;
@@ -55,6 +56,7 @@ pub use grid_graph::grid_graph;
 pub use heavy_hex_graph::heavy_hex_graph;
 pub use heavy_square_graph::heavy_square_graph;
 pub use hexagonal_lattice_graph::{hexagonal_lattice_graph, hexagonal_lattice_graph_weighted};
+pub use karate_club::karate_club_graph;
 pub use lollipop_graph::lollipop_graph;
 pub use path_graph::path_graph;
 pub use petersen_graph::petersen_graph;

rustworkx/generators/__init__.pyi

@@ -131,3 +131,4 @@ def directed_complete_graph(
     multigraph: bool = ...,
 ) -> PyDiGraph: ...
 def dorogovtsev_goltsev_mendes_graph(n: int) -> PyGraph: ...
+def karate_club_graph(multigraph: bool = ...) -> PyGraph: ...

src/generators.rs

@@ -1715,6 +1715,62 @@ pub fn dorogovtsev_goltsev_mendes_graph(py: Python, n: usize) -> PyResult<graph:
     })
 }
 
+/// Generates Zachary's Karate Club graph.
+///
+/// Zachary's Karate Club graph is a well-known social network that represents
+/// the relations between 34 members of a karate club, as described in the
+/// paper by Zachary [1]_.
+///
+/// The graph is undirected and contains 34 nodes (members) and 78 edges
+/// (interactions). Each node represents a club member, and each edge represents
+/// a relationship between two members.
+///
+/// :param bool multigraph: When set to ``False`` the output
+///     :class:`~rustworkx.PyGraph` object will not be not be a multigraph and
+///     won't allow parallel edges to be added. Instead
+///     calls which would create a parallel edge will update the existing edge.
+///
+/// :returns: The undirected graph representing the Karate club graph.
+///           Each node is labeled according to its assigned faction.
+///
+/// :rtype: PyGraph
+///
+/// .. jupyter-execute::
+///   
+///   import rustworkx.generators
+///   from rustworkx.visualization import mpl_draw
+///   
+///   graph = rustworkx.generators.karate_club_graph()
+///   layout = rustworkx.circular_layout(graph)
+///   mpl_draw(graph, pos=layout)
+///   
+/// .. [1] Zachary, Wayne W.
+///    "An information flow model for conflict and fission in small groups"
+///    Journal of Anthropological Research, 33, 452-473.
+///     https://doi.org/10.1086/jar.33.4.3629752
+#[pyfunction]
+#[pyo3(
+    signature=(multigraph=true),
+)]
+pub fn karate_club_graph(py: Python, multigraph: bool) -> PyResult<graph::PyGraph> {
+    let default_node_fn = |w: bool| match w {
+        true => "Mr. Hi".to_object(py),
+        false => "Officer".to_object(py),
+    };
+    let default_edge_fn = |w: usize| (w as f64).to_object(py);
+    let graph: StablePyGraph<Undirected> =
+        match core_generators::karate_club_graph(default_node_fn, default_edge_fn) {
+            Ok(graph) => graph,
+            Err(_) => return Err(PyValueError::new_err("error generating Karate club graph")),
+        };
+    Ok(graph::PyGraph {
+        graph,
+        node_removed: false,
+        multigraph,
+        attrs: py.None(),
+    })
+}
+
 #[pymodule]
 pub fn generators(_py: Python, m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(cycle_graph))?;
@@ -1744,5 +1800,6 @@ pub fn generators(_py: Python, m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(complete_graph))?;
     m.add_wrapped(wrap_pyfunction!(directed_complete_graph))?;
     m.add_wrapped(wrap_pyfunction!(dorogovtsev_goltsev_mendes_graph))?;
+    m.add_wrapped(wrap_pyfunction!(karate_club_graph))?;
     Ok(())
 }

tests/graph/test_karate.py

@@ -0,0 +1,42 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import unittest
+
+import rustworkx as rx
+import networkx as nx
+
+
+class TestKarate(unittest.TestCase):
+    def test_isomorphic_to_networkx(self):
+        graph = rx.generators.karate_club_graph()
+        nx_graph = rx.networkx_converter(nx.karate_club_graph(), keep_attributes=True)
+
+        def node_matcher(a, b):
+            if isinstance(a, dict):
+                a, b, = (
+                    b,
+                    a,
+                )
+            return a == b["club"]
+
+        def edge_matcher(a, b):
+            if isinstance(a, dict):
+                a, b, = (
+                    b,
+                    a,
+                )
+            return a == b["weight"]
+
+        self.assertTrue(
+            rx.is_isomorphic(graph, nx_graph, node_matcher=node_matcher, edge_matcher=edge_matcher)
+        )