1 // Copyright 2004 The Trustees of Indiana University.
3 // Use, modification and distribution is subject to the Boost Software
4 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
7 //  Authors: Douglas Gregor
8 //           Andrew Lumsdaine
9 #ifndef BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP
10 #define BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP
12 #include <boost/graph/betweenness_centrality.hpp>
13 #include <boost/graph/graph_traits.hpp>
14 #include <boost/pending/indirect_cmp.hpp>
15 #include <algorithm>
16 #include <vector>
17 #include <boost/property_map.hpp>
19 namespace boost {
21 /** Threshold termination function for the betweenness centrality
22  * clustering algorithm.
23  */
24 template<typename T>
25 struct bc_clustering_threshold
26 {
27   typedef T centrality_type;
29   /// Terminate clustering when maximum absolute edge centrality is
30   /// below the given threshold.
31   explicit bc_clustering_threshold(T threshold)
32     : threshold(threshold), dividend(1.0) {}
34   /**
35    * Terminate clustering when the maximum edge centrality is below
36    * the given threshold.
37    *
38    * @param threshold the threshold value
39    *
40    * @param g the graph on which the threshold will be calculated
41    *
42    * @param normalize when true, the threshold is compared against the
43    * normalized edge centrality based on the input graph; otherwise,
44    * the threshold is compared against the absolute edge centrality.
45    */
46   template<typename Graph>
47   bc_clustering_threshold(T threshold, const Graph& g, bool normalize = true)
48     : threshold(threshold), dividend(1.0)
49   {
50     if (normalize) {
51       typename graph_traits<Graph>::vertices_size_type n = num_vertices(g);
52       dividend = T((n - 1) * (n - 2)) / T(2);
53     }
54   }
56   /** Returns true when the given maximum edge centrality (potentially
57    * normalized) falls below the threshold.
58    */
59   template<typename Graph, typename Edge>
60   bool operator()(T max_centrality, Edge, const Graph&)
61   {
62     return (max_centrality / dividend) < threshold;
63   }
65  protected:
66   T threshold;
67   T dividend;
68 };
70 /** Graph clustering based on edge betweenness centrality.
71  *
72  * This algorithm implements graph clustering based on edge
73  * betweenness centrality. It is an iterative algorithm, where in each
74  * step it compute the edge betweenness centrality (via @ref
75  * brandes_betweenness_centrality) and removes the edge with the
76  * maximum betweenness centrality. The @p done function object
77  * determines when the algorithm terminates (the edge found when the
78  * algorithm terminates will not be removed).
79  *
80  * @param g The graph on which clustering will be performed. The type
81  * of this parameter (@c MutableGraph) must be a model of the
82  * VertexListGraph, IncidenceGraph, EdgeListGraph, and Mutable Graph
83  * concepts.
84  *
85  * @param done The function object that indicates termination of the
86  * algorithm. It must be a ternary function object thats accepts the
87  * maximum centrality, the descriptor of the edge that will be
88  * removed, and the graph @p g.
89  *
90  * @param edge_centrality (UTIL/OUT) The property map that will store
91  * the betweenness centrality for each edge. When the algorithm
92  * terminates, it will contain the edge centralities for the
93  * graph. The type of this property map must model the
94  * ReadWritePropertyMap concept. Defaults to an @c
95  * iterator_property_map whose value type is
96  * @c Done::centrality_type and using @c get(edge_index, g) for the
97  * index map.
98  *
99  * @param vertex_index (IN) The property map that maps vertices to
100  * indices in the range @c [0, num_vertices(g)). This type of this
101  * property map must model the ReadablePropertyMap concept and its
102  * value type must be an integral type. Defaults to
103  * @c get(vertex_index, g).
104  */
105 template<typename MutableGraph, typename Done, typename EdgeCentralityMap,
106          typename VertexIndexMap>
107 void
108 betweenness_centrality_clustering(MutableGraph& g, Done done,
109                                   EdgeCentralityMap edge_centrality,
110                                   VertexIndexMap vertex_index)
111 {
112   typedef typename property_traits<EdgeCentralityMap>::value_type
113     centrality_type;
114   typedef typename graph_traits<MutableGraph>::edge_iterator edge_iterator;
115   typedef typename graph_traits<MutableGraph>::edge_descriptor edge_descriptor;
116   typedef typename graph_traits<MutableGraph>::vertices_size_type
117     vertices_size_type;
119   if (edges(g).first == edges(g).second) return;
121   // Function object that compares the centrality of edges
122   indirect_cmp<EdgeCentralityMap, std::less<centrality_type> >
123     cmp(edge_centrality);
125   bool is_done;
126   do {
127     brandes_betweenness_centrality(g,
128                                    edge_centrality_map(edge_centrality)
129                                    .vertex_index_map(vertex_index));
130     edge_descriptor e = *max_element(edges(g).first, edges(g).second, cmp);
131     is_done = done(get(edge_centrality, e), e, g);
132     if (!is_done) remove_edge(e, g);
133   } while (!is_done && edges(g).first != edges(g).second);
134 }
136 /**
138  */
139 template<typename MutableGraph, typename Done, typename EdgeCentralityMap>
140 void
141 betweenness_centrality_clustering(MutableGraph& g, Done done,
142                                   EdgeCentralityMap edge_centrality)
143 {
144   betweenness_centrality_clustering(g, done, edge_centrality,
145                                     get(vertex_index, g));
146 }
148 /**