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/pending/indirect_cmp.hpp>

    15 #include <algorithm>

    16 #include <vector>

    17 #include <boost/property_map.hpp>

    18 

    19 namespace boost {

    20 

    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;

    28 

    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) {}

    33   

    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   }

    55 

    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   }

    64 

    65  protected:

    66   T threshold;

    67   T dividend;

    68 };

    69 

    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;

   118 

   119   if (edges(g).first == edges(g).second) return;

   120 

   121   // Function object that compares the centrality of edges

   122   indirect_cmp<EdgeCentralityMap, std::less<centrality_type> > 

   123     cmp(edge_centrality);

   124 

   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 }

   135 

   136 /**

   137  * \overload

   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 }

   147 

   148 /**

   149  * \overload

   150  */ 

   151 template<typename MutableGraph, typename Done>

   152 void

   153 betweenness_centrality_clustering(MutableGraph& g, Done done)

   154 {

   155   typedef typename Done::centrality_type centrality_type;

   156   std::vector<centrality_type> edge_centrality(num_edges(g));

   157   betweenness_centrality_clustering(g, done, 

   158     make_iterator_property_map(edge_centrality.begin(), get(edge_index, g)),

   159     get(vertex_index, g));

   160 }

   161 

   162 } // end namespace boost

   163 

   164 #endif // BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP