williamr@2: // Copyright 2004 The Trustees of Indiana University.
williamr@2: 
williamr@2: // Distributed under the Boost Software License, Version 1.0.
williamr@2: // (See accompanying file LICENSE_1_0.txt or copy at
williamr@2: // http://www.boost.org/LICENSE_1_0.txt)
williamr@2: 
williamr@2: //  Authors: Douglas Gregor
williamr@2: //           Andrew Lumsdaine
williamr@2: #ifndef BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP
williamr@2: #define BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP
williamr@2: 
williamr@2: #include <boost/graph/betweenness_centrality.hpp>
williamr@2: #include <boost/graph/graph_traits.hpp>
williamr@2: #include <boost/pending/indirect_cmp.hpp>
williamr@2: #include <algorithm>
williamr@2: #include <vector>
williamr@2: #include <boost/property_map.hpp>
williamr@2: 
williamr@2: namespace boost {
williamr@2: 
williamr@2: /** Threshold termination function for the betweenness centrality
williamr@2:  * clustering algorithm.
williamr@2:  */
williamr@2: template<typename T>
williamr@2: struct bc_clustering_threshold
williamr@2: {
williamr@2:   typedef T centrality_type;
williamr@2: 
williamr@2:   /// Terminate clustering when maximum absolute edge centrality is
williamr@2:   /// below the given threshold.
williamr@2:   explicit bc_clustering_threshold(T threshold) 
williamr@2:     : threshold(threshold), dividend(1.0) {}
williamr@2:   
williamr@2:   /**
williamr@2:    * Terminate clustering when the maximum edge centrality is below
williamr@2:    * the given threshold.
williamr@2:    *
williamr@2:    * @param threshold the threshold value
williamr@2:    *
williamr@2:    * @param g the graph on which the threshold will be calculated
williamr@2:    *
williamr@2:    * @param normalize when true, the threshold is compared against the
williamr@2:    * normalized edge centrality based on the input graph; otherwise,
williamr@2:    * the threshold is compared against the absolute edge centrality.
williamr@2:    */
williamr@2:   template<typename Graph>
williamr@2:   bc_clustering_threshold(T threshold, const Graph& g, bool normalize = true)
williamr@2:     : threshold(threshold), dividend(1.0)
williamr@2:   {
williamr@2:     if (normalize) {
williamr@2:       typename graph_traits<Graph>::vertices_size_type n = num_vertices(g);
williamr@2:       dividend = T((n - 1) * (n - 2)) / T(2);
williamr@2:     }
williamr@2:   }
williamr@2: 
williamr@2:   /** Returns true when the given maximum edge centrality (potentially
williamr@2:    * normalized) falls below the threshold.
williamr@2:    */
williamr@2:   template<typename Graph, typename Edge>
williamr@2:   bool operator()(T max_centrality, Edge, const Graph&)
williamr@2:   {
williamr@2:     return (max_centrality / dividend) < threshold;
williamr@2:   }
williamr@2: 
williamr@2:  protected:
williamr@2:   T threshold;
williamr@2:   T dividend;
williamr@2: };
williamr@2: 
williamr@2: /** Graph clustering based on edge betweenness centrality.
williamr@2:  * 
williamr@2:  * This algorithm implements graph clustering based on edge
williamr@2:  * betweenness centrality. It is an iterative algorithm, where in each
williamr@2:  * step it compute the edge betweenness centrality (via @ref
williamr@2:  * brandes_betweenness_centrality) and removes the edge with the
williamr@2:  * maximum betweenness centrality. The @p done function object
williamr@2:  * determines when the algorithm terminates (the edge found when the
williamr@2:  * algorithm terminates will not be removed).
williamr@2:  *
williamr@2:  * @param g The graph on which clustering will be performed. The type
williamr@2:  * of this parameter (@c MutableGraph) must be a model of the
williamr@2:  * VertexListGraph, IncidenceGraph, EdgeListGraph, and Mutable Graph
williamr@2:  * concepts.
williamr@2:  *
williamr@2:  * @param done The function object that indicates termination of the
williamr@2:  * algorithm. It must be a ternary function object thats accepts the
williamr@2:  * maximum centrality, the descriptor of the edge that will be
williamr@2:  * removed, and the graph @p g.
williamr@2:  *
williamr@2:  * @param edge_centrality (UTIL/OUT) The property map that will store
williamr@2:  * the betweenness centrality for each edge. When the algorithm
williamr@2:  * terminates, it will contain the edge centralities for the
williamr@2:  * graph. The type of this property map must model the
williamr@2:  * ReadWritePropertyMap concept. Defaults to an @c
williamr@2:  * iterator_property_map whose value type is 
williamr@2:  * @c Done::centrality_type and using @c get(edge_index, g) for the 
williamr@2:  * index map.
williamr@2:  *
williamr@2:  * @param vertex_index (IN) The property map that maps vertices to
williamr@2:  * indices in the range @c [0, num_vertices(g)). This type of this
williamr@2:  * property map must model the ReadablePropertyMap concept and its
williamr@2:  * value type must be an integral type. Defaults to 
williamr@2:  * @c get(vertex_index, g).
williamr@2:  */
williamr@2: template<typename MutableGraph, typename Done, typename EdgeCentralityMap,
williamr@2:          typename VertexIndexMap>
williamr@2: void 
williamr@2: betweenness_centrality_clustering(MutableGraph& g, Done done,
williamr@2:                                   EdgeCentralityMap edge_centrality,
williamr@2:                                   VertexIndexMap vertex_index)
williamr@2: {
williamr@2:   typedef typename property_traits<EdgeCentralityMap>::value_type
williamr@2:     centrality_type;
williamr@2:   typedef typename graph_traits<MutableGraph>::edge_iterator edge_iterator;
williamr@2:   typedef typename graph_traits<MutableGraph>::edge_descriptor edge_descriptor;
williamr@2:   typedef typename graph_traits<MutableGraph>::vertices_size_type
williamr@2:     vertices_size_type;
williamr@2: 
williamr@2:   if (edges(g).first == edges(g).second) return;
williamr@2: 
williamr@2:   // Function object that compares the centrality of edges
williamr@2:   indirect_cmp<EdgeCentralityMap, std::less<centrality_type> > 
williamr@2:     cmp(edge_centrality);
williamr@2: 
williamr@2:   bool is_done;
williamr@2:   do {
williamr@2:     brandes_betweenness_centrality(g, 
williamr@2:                                    edge_centrality_map(edge_centrality)
williamr@2:                                    .vertex_index_map(vertex_index));
williamr@2:     edge_descriptor e = *max_element(edges(g).first, edges(g).second, cmp);
williamr@2:     is_done = done(get(edge_centrality, e), e, g);
williamr@2:     if (!is_done) remove_edge(e, g);
williamr@2:   } while (!is_done && edges(g).first != edges(g).second);
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2:  * \overload
williamr@2:  */ 
williamr@2: template<typename MutableGraph, typename Done, typename EdgeCentralityMap>
williamr@2: void 
williamr@2: betweenness_centrality_clustering(MutableGraph& g, Done done,
williamr@2:                                   EdgeCentralityMap edge_centrality)
williamr@2: {
williamr@2:   betweenness_centrality_clustering(g, done, edge_centrality,
williamr@2:                                     get(vertex_index, g));
williamr@2: }
williamr@2: 
williamr@2: /**
williamr@2:  * \overload
williamr@2:  */ 
williamr@2: template<typename MutableGraph, typename Done>
williamr@2: void
williamr@2: betweenness_centrality_clustering(MutableGraph& g, Done done)
williamr@2: {
williamr@2:   typedef typename Done::centrality_type centrality_type;
williamr@2:   std::vector<centrality_type> edge_centrality(num_edges(g));
williamr@2:   betweenness_centrality_clustering(g, done, 
williamr@2:     make_iterator_property_map(edge_centrality.begin(), get(edge_index, g)),
williamr@2:     get(vertex_index, g));
williamr@2: }
williamr@2: 
williamr@2: } // end namespace boost
williamr@2: 
williamr@2: #endif // BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP