Weighted Eigen Vector Centrality (#17)

Author: dizzyi

src/centrality/algorithms.rs

@@ -81,22 +81,61 @@ where
 // -----------------------------
 //
 
-/// Full implementation of eigenvector centrality with convergence tolerance.
-pub fn eigenvector_centrality_impl<A, Ty>(
-    graph: &BaseGraph<A, f64, Ty>,
+/// Full implementation of eigenvector centrality with convergence tolerance,
+/// calculates eigenvector centrality for nodes in a graph iteratively.
+///
+/// this function designed for generic edge type,
+/// see [`eigenvector_centrality`] and [`eigenvector_centrality_numpy`]
+/// for cleaner interaction with `f64` edge graph.
+///
+/// # Arguments:
+///
+/// * `graph`: the targeted graph.
+/// * `max_iter`: The maximum number of iterations that the algorithm will run for.
+/// * `tol`: the average tolerance for convergence.
+/// * `eval_weight`: callback to evaluate the weight of edges in the graph.
+///
+/// # Returns :
+///
+/// a vector of `f64` representing eigenvector centralities of each node in the graph.
+///
+/// # Example
+/// ```rust
+/// use graphina::core::types::Graph;
+/// use graphina::centrality::algorithms::eigenvector_centrality_impl;
+///
+/// let mut g: Graph<i32, (f64, f64)> = Graph::new();
+/// //                    ^^^^^^^^^^
+/// //                             L arbitrary type as edge
+/// let nodes = [g.add_node(1), g.add_node(2), g.add_node(3)];
+/// g.add_edge(nodes[0], nodes[1], (0.0, 1.0));
+/// g.add_edge(nodes[0], nodes[2], (1.0, 0.0));
+/// let centrality = eigenvector_centrality_impl(
+///     &g, 
+///     1000, 
+///     1e-6_f64, 
+///     |w| w.0 * 10.0 + w.1 // <-- custom evaluation for edge weight
+/// );
+/// println!("{:.5?}", centrality); // [0.70711, 0.07036, 0.70360]
+/// ```
+pub fn eigenvector_centrality_impl<A, W, Ty>(
+    graph: &BaseGraph<A, W, Ty>,
     max_iter: usize,
     tol: f64,
+    eval_weight: impl Fn(&W) -> f64,
 ) -> Vec<f64>
 where
-    Ty: GraphConstructor<A, f64>,
+    Ty: GraphConstructor<A, W>,
 {
     let n = graph.node_count();
     let mut centrality = vec![1.0; n];
+    let mut next = centrality.clone();
     for _ in 0..max_iter {
-        let mut next = vec![0.0; n];
-        for (node, _) in graph.nodes() {
-            for neighbor in graph.neighbors(node) {
-                next[neighbor.index()] += centrality[node.index()];
+        for (src, dst, w) in graph.edges() {
+            let w = eval_weight(w);
+            next[dst.index()] += w * centrality[src.index()];
+            if !<Ty as GraphConstructor<A, W>>::is_directed() {
+                next[src.index()] += w * centrality[dst.index()];
             }
         }
         let norm = next.iter().map(|x| x * x).sum::<f64>().sqrt();
@@ -106,11 +145,14 @@ where
             }
         }
         let diff: f64 = centrality
-            .iter()
+            .iter_mut()
             .zip(next.iter())
-            .map(|(a, b)| (a - b).abs())
+            .map(|(a, b)| {
+                let d = (*a - b).abs();
+                *a = *b;
+                d
+            })
             .sum();
-        centrality = next;
         if diff < tol * n as f64 {
             break;
         }
@@ -119,23 +161,90 @@ where
 }
 
 /// Wrapper for eigenvector centrality with default tolerance (1e-6).
-pub fn eigenvector_centrality<A, Ty>(graph: &BaseGraph<A, f64, Ty>, max_iter: usize) -> Vec<f64>
+/// calculates eigenvector centrality for nodes in a graph iteratively.
+///
+/// # Arguments:
+///
+/// * `graph`: the targeted graph.
+/// * `max_iter`: The maximum number of iterations that the algorithm will run for.
+/// * `weighted`: whether or not the calculated centrality will be weighed.
+///
+/// # Returns :
+///
+/// a vector of `f64` representing eigenvector centralities of each node in the graph.
+///
+/// # Examples :
+/// ```rust
+/// use graphina::centrality::algorithms::eigenvector_centrality;
+/// use graphina::core::types::Graph;
+/// let mut g = Graph::new();
+///
+/// let nodes = [g.add_node(1), g.add_node(2), g.add_node(3)];
+/// g.add_edge(nodes[0], nodes[1], 1.0);
+/// g.add_edge(nodes[0], nodes[2], 2.0);
+/// let centrality = eigenvector_centrality(&g, 1000, false);
+/// println!("{:.5?}", centrality); // [0.70711, 0.50000, 0.50000]
+/// let centrality = eigenvector_centrality(&g, 1000, true);
+/// println!("{:.5?}", centrality); // [0.70711, 0.31623, 0.63246]
+/// ```
+pub fn eigenvector_centrality<A, Ty>(
+    graph: &BaseGraph<A, f64, Ty>,
+    max_iter: usize,
+    weighted: bool,
+) -> Vec<f64>
 where
     Ty: GraphConstructor<A, f64>,
 {
-    eigenvector_centrality_impl(graph, max_iter, 1e-6_f64)
+    let eval_weight = if weighted {
+        |f: &f64| *f
+    } else {
+        |_f: &f64| 1.0
+    };
+    eigenvector_centrality_impl(graph, max_iter, 1e-6_f64, eval_weight)
 }
 
-/// NumPy–style eigenvector centrality (alias to the above).
+/// NumPy–style eigenvector centrality (alias to [`eigenvector_centrality`]).
+/// calculates eigenvector centrality for nodes in a graph iteratively.
+///
+/// # Arguments:
+///
+/// * `graph`: the targeted graph.
+/// * `max_iter`: The maximum number of iterations that the algorithm will run for.
+/// * `weighted`: whether or not the calculated centrality will be weighed.
+///
+/// # Returns :
+///
+/// a vector of `f64` representing eigenvector centralities of each node in the graph.
+///
+/// # Examples :
+/// ```rust
+/// use graphina::centrality::algorithms::eigenvector_centrality_numpy;
+/// use graphina::core::types::Graph;
+/// let mut g = Graph::new();
+///
+/// let nodes = [g.add_node(1), g.add_node(2), g.add_node(3)];
+/// g.add_edge(nodes[0], nodes[1], 1.0);
+/// g.add_edge(nodes[0], nodes[2], 2.0);
+/// let centrality = eigenvector_centrality_numpy(&g, 1000, false);
+/// println!("{:.5?}", centrality); // [0.70711, 0.50000, 0.50000]
+/// let centrality = eigenvector_centrality_numpy(&g, 1000, true);
+/// println!("{:.5?}", centrality); // [0.70711, 0.31623, 0.63246]
+/// ```
 pub fn eigenvector_centrality_numpy<A, Ty>(
     graph: &BaseGraph<A, f64, Ty>,
     max_iter: usize,
     tol: f64,
+    weighted: bool,
 ) -> Vec<f64>
 where
     Ty: GraphConstructor<A, f64>,
 {
-    eigenvector_centrality_impl(graph, max_iter, tol)
+    let eval_weight = if weighted {
+        |f: &f64| *f
+    } else {
+        |_f: &f64| 1.0
+    };
+    eigenvector_centrality_impl(graph, max_iter, tol, eval_weight)
 }
 
 //

tests/test_centrality_algorithms.rs

@@ -82,7 +82,7 @@ fn test_betweenness_centrality() {
 #[test]
 fn test_eigenvector_centrality() {
     let graph = build_test_graph_f64();
-    let ev = eigenvector_centrality(&graph, 20);
+    let ev = eigenvector_centrality(&graph, 20, false);
     // Check that we have 4 scores and all are positive.
     assert_eq!(ev.len(), 4);
     for &score in &ev {