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