graph/quickbook/reference/betweenness_centrality.qbk

[/
 / Copyright (c) 2007 Andrew Sutton
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section Betweenness Centrality]

    template<typename Graph, typename CentralityMap>
    void
    brandes_betweenness_centrality(const Graph& g, CentralityMap cm)

    template<typename Graph, typename CentralityMap, typename EdgeCentralityMap>
    void
    brandes_betweenness_centrality(const Graph& g,
                                   CentralityMap cm,
                                   EdgeCentralityMap ecm)

    // Named Parameter Interface
    template<typename Graph, ...>
    void brandes_betweenness_centrality(const Graph& g, ...);


The /betweenness centrality/ measure is commonly used in network analysis to identify
vertices (also called actors) that are lie many shortest paths between other vertices
in a graph. Intuitively, vertices with high betweenness centrality act as "hubs" through
which more information flows. The betweenness centrality of a vertex is given as

[$images/eq/betweenness.png]

Where ['[delta][sub st]] is the number of shortest paths between the vertices /s/ and
/t/ and ['[delta][sub st](v)] is the number of shortest paths that pass through the
vertex /v/. Note that the ratio inside the sum an be interpreted as the probability
that /v/ lies on a shortest path between the vertices /s/ and /t/.

This function can also consider the /edge betweenness centrality/, which is defined
as, fro each edge, the betweenness centrality that was contribuetd to the targets
of the edge. This is plural for undirected graphs. Like vertex betweenness, this
measure can be used to determine the edges through which most shortest paths must
pass.

These functions measure the /absolute/ betweenness centrality for vertices. These
values can be converted to /relative/ betweenness centrality by scaling each of
the absolute values by:

[$images/eq/relative_betweenness.png]

Where /n/ is the number of vertices in the graph. Also, given the relative betwenness
centrality, one can compute the /central point dominance/, which is a mueasure of the
maximum betweenness of any point in the graph. For example, this value will be 0 for
complete graphs and 1 for star graphs (where all paths cross a central vertex).
The central point dominance of a graph is defined as:

[$images/eq/central_point_dominance.png]

This module provides a number of functions for computing both vertex and edge
centrality and related measures.

[heading Where Defined]
`boost/graph/betweenness_centrality.hpp`

[heading Parameters]
[table
    [[Type] [Parameter] [Description]]
    [
        [required, in] [`const Graph& g`]
        [
            The graph for which the betweenness centrality of vertices or edges
            is being computed.

            *Requirements:* The `Graph` type must be a model of the [VertexListGraph]
            and [IncidenceGraph] concepts. If the `EdgeCentralityMap` parameter
            is present, this parameter type must also model the [EdgeListGraph].
        ]
    ]
    [
        [required, out] [`CentralityMap cm`]
        [
            The graph for which the betweenness centrality of vertices or edges
            is being computed.

            *Requirements:*
        ]
    ]
    [
        [required, in] [`DistanceMap dm`]
        [
            Given a vertex `v`, the `dm` parameter provides the length of the
            shortest path between a vertex `u` and `v`. The vertex `u` is the
            vertex for which the distance map was initially computed.

            *Requirements:* `DistanceMap` must be a model of [ReadablePropertyMap].
            The `key_type` of the distance map must be the same as the `vertex_descriptor`
            of the `Graph` parameter. The `value_type` is required to be a model of
            [NumericValue].
        ]
    ]
    [
        [required, in] [`DistanceMatrixMap dm`]
        [
            Given vertices /u/ and /v/, the `dm` parameter provides the length
            of the shortest path between the two vertices. Note that the
            distance between a vertex and itself should be 0 (i.e., `dm[u][u] == 0`).

            *Requirements:* `DistanceMatrixMap` must be a model of [ReadablePropertyMap].
            The `key_type` of the distance matrixc must be the same as the `vertex_descriptor`
            of the `Graph` parameter. The `value_type` must be a [ReadWritePropertyMap]
            whose `key_type` is also the `vertex_descriptor` of the `Graph` and
            whose `value_type` is a model of [NumericValue].
        ]
    ]
    [
        [required, out] [`ClosenessMap cm`]
        [
            The cm parameter stores the output of the computed closeness (or
            distance) for each vertex in `g`.

            *Requirements:* The type of `close` must be model the [WritablePropertyMap]
            concepts. The `key_type` of the property map must be the same as the
            `vertex_descriptor` of the `Graph`, and the `value_type` must be a model
            of [NumericValue].
        ]
    ]
    [
        [optional, in] [`Measure measure`]
        [
            The 'measure' parameter is an instance of a closeness measure that
            performs the final operation (the reciprocal) for this computation.

            *Requirements:* The `Measure` type must be a model of the [DistanceMeasure]
            concept. The `distance_type` must be the same type as the `value_type`
            of the `DistanceMap` or `DistanceMatrixMap`. The `result_type` of the
            `Measure` must model the [NumericValue] concept.
        ]
    ]
]

[heading Return]
The `vertex_closeness_centrality()` function returns the closeness of a vertex.
If the source vertex is disconnected from any vertices in the graph, this value is 0.

[heading Complexity]
The `closenesss_centrality()` function returns in ['O(n[sup 2]*O(M))] where /n/
is the number of vertices in the graph and /M/ is the complexity of the given distance
measure. This is ['O(n[sup 2])] by default

The `vertex_closeness_centrality()` function returns in ['O(n*O(M))]. This is
linear by default.

[heading Example (Closeness Centrality)]

[heading Undocumented Functions]
These functions are also part of the betweenness centrality module, but are not
documented since they are more appropriately called using the named parameter
interface.

    template<typename Graph, typename CentralityMap, typename EdgeCentralityMap,
             typename IncomingMap, typename DistanceMap, typename DependencyMap,
             typename PathCountMap, typename VertexIndexMap>
    void
    brandes_betweenness_centrality(const Graph& g,
                                   CentralityMap centrality,
                                   EdgeCentralityMap edge_centrality,
                                   IncomingMap incoming,
                                   DistanceMap distance,
                                   DependencyMap dependency,
                                   PathCountMap path_count,
                                   VertexIndexMap vertex_index)

    template<typename Graph, typename CentralityMap, typename EdgeCentralityMap,
             typename IncomingMap, typename DistanceMap, typename DependencyMap,
             typename PathCountMap, typename VertexIndexMap, typename WeightMap>
    void
    brandes_betweenness_centrality(const Graph& g,
                                   CentralityMap centrality,
                                   EdgeCentralityMap edge_centrality,
                                   IncomingMap incoming,
                                   DistanceMap distance,
                                   DependencyMap dependency,
                                   PathCountMap path_count,
                                   VertexIndexMap vertex_index,
                                   WeightMap weight_map)

[endsect]