boost/graph/bc_clustering.hpp

0001 // Copyright 2004 The Trustees of Indiana University.
0002
0003 // Distributed under the Boost Software License, Version 1.0.
0004 // (See accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 //  Authors: Douglas Gregor
0008 //           Andrew Lumsdaine
0009 #ifndef BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP
0010 #define BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP
0011
0012 #include <boost/algorithm/minmax_element.hpp>
0013 #include <boost/graph/betweenness_centrality.hpp>
0014 #include <boost/graph/graph_traits.hpp>
0015 #include <boost/graph/graph_utility.hpp>
0016 #include <boost/pending/indirect_cmp.hpp>
0017 #include <vector>
0018 #include <boost/property_map/property_map.hpp>
0019
0020 namespace boost
0021 {
0022
0023 /** Threshold termination function for the betweenness centrality
0024  * clustering algorithm.
0025  */
0026 template < typename T > struct bc_clustering_threshold
0027 {
0028     typedef T centrality_type;
0029
0030     /// Terminate clustering when maximum absolute edge centrality is
0031     /// below the given threshold.
0032     explicit bc_clustering_threshold(T threshold)
0033     : threshold(threshold), dividend(1.0)
0034     {
0035     }
0036
0037     /**
0038      * Terminate clustering when the maximum edge centrality is below
0039      * the given threshold.
0040      *
0041      * @param threshold the threshold value
0042      *
0043      * @param g the graph on which the threshold will be calculated
0044      *
0045      * @param normalize when true, the threshold is compared against the
0046      * normalized edge centrality based on the input graph; otherwise,
0047      * the threshold is compared against the absolute edge centrality.
0048      */
0049     template < typename Graph >
0050     bc_clustering_threshold(T threshold, const Graph& g, bool normalize = true)
0051     : threshold(threshold), dividend(1.0)
0052     {
0053         if (normalize)
0054         {
0055             typename graph_traits< Graph >::vertices_size_type n
0056                 = num_vertices(g);
0057             dividend = T((n - 1) * (n - 2)) / T(2);
0058         }
0059     }
0060
0061     /** Returns true when the given maximum edge centrality (potentially
0062      * normalized) falls below the threshold.
0063      */
0064     template < typename Graph, typename Edge >
0065     bool operator()(T max_centrality, Edge, const Graph&)
0066     {
0067         return (max_centrality / dividend) < threshold;
0068     }
0069
0070 protected:
0071     T threshold;
0072     T dividend;
0073 };
0074
0075 /** Graph clustering based on edge betweenness centrality.
0076  *
0077  * This algorithm implements graph clustering based on edge
0078  * betweenness centrality. It is an iterative algorithm, where in each
0079  * step it compute the edge betweenness centrality (via @ref
0080  * brandes_betweenness_centrality) and removes the edge with the
0081  * maximum betweenness centrality. The @p done function object
0082  * determines when the algorithm terminates (the edge found when the
0083  * algorithm terminates will not be removed).
0084  *
0085  * @param g The graph on which clustering will be performed. The type
0086  * of this parameter (@c MutableGraph) must be a model of the
0087  * VertexListGraph, IncidenceGraph, EdgeListGraph, and Mutable Graph
0088  * concepts.
0089  *
0090  * @param done The function object that indicates termination of the
0091  * algorithm. It must be a ternary function object thats accepts the
0092  * maximum centrality, the descriptor of the edge that will be
0093  * removed, and the graph @p g.
0094  *
0095  * @param edge_centrality (UTIL/OUT) The property map that will store
0096  * the betweenness centrality for each edge. When the algorithm
0097  * terminates, it will contain the edge centralities for the
0098  * graph. The type of this property map must model the
0099  * ReadWritePropertyMap concept. Defaults to an @c
0100  * iterator_property_map whose value type is
0101  * @c Done::centrality_type and using @c get(edge_index, g) for the
0102  * index map.
0103  *
0104  * @param vertex_index (IN) The property map that maps vertices to
0105  * indices in the range @c [0, num_vertices(g)). This type of this
0106  * property map must model the ReadablePropertyMap concept and its
0107  * value type must be an integral type. Defaults to
0108  * @c get(vertex_index, g).
0109  */
0110 template < typename MutableGraph, typename Done, typename EdgeCentralityMap,
0111     typename VertexIndexMap >
0112 void betweenness_centrality_clustering(MutableGraph& g, Done done,
0113     EdgeCentralityMap edge_centrality, VertexIndexMap vertex_index)
0114 {
0115     typedef typename property_traits< EdgeCentralityMap >::value_type
0116         centrality_type;
0117     typedef typename graph_traits< MutableGraph >::edge_iterator edge_iterator;
0118     typedef
0119         typename graph_traits< MutableGraph >::edge_descriptor edge_descriptor;
0120
0121     if (has_no_edges(g))
0122         return;
0123
0124     // Function object that compares the centrality of edges
0125     indirect_cmp< EdgeCentralityMap, std::less< centrality_type > > cmp(
0126         edge_centrality);
0127
0128     bool is_done;
0129     do
0130     {
0131         brandes_betweenness_centrality(g,
0132             edge_centrality_map(edge_centrality)
0133                 .vertex_index_map(vertex_index));
0134         std::pair< edge_iterator, edge_iterator > edges_iters = edges(g);
0135         edge_descriptor e
0136             = *boost::first_max_element(edges_iters.first, edges_iters.second, cmp);
0137         is_done = done(get(edge_centrality, e), e, g);
0138         if (!is_done)
0139             remove_edge(e, g);
0140     } while (!is_done && !has_no_edges(g));
0141 }
0142
0143 /**
0144  * \overload
0145  */
0146 template < typename MutableGraph, typename Done, typename EdgeCentralityMap >
0147 void betweenness_centrality_clustering(
0148     MutableGraph& g, Done done, EdgeCentralityMap edge_centrality)
0149 {
0150     betweenness_centrality_clustering(
0151         g, done, edge_centrality, get(vertex_index, g));
0152 }
0153
0154 /**
0155  * \overload
0156  */
0157 template < typename MutableGraph, typename Done >
0158 void betweenness_centrality_clustering(MutableGraph& g, Done done)
0159 {
0160     typedef typename Done::centrality_type centrality_type;
0161     std::vector< centrality_type > edge_centrality(num_edges(g));
0162     betweenness_centrality_clustering(g, done,
0163         make_iterator_property_map(edge_centrality.begin(), get(edge_index, g)),
0164         get(vertex_index, g));
0165 }
0166
0167 } // end namespace boost
0168
0169 #endif // BOOST_GRAPH_BETWEENNESS_CENTRALITY_CLUSTERING_HPP