graph/quickbook/reference/mean_geodesic.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 Mean Geodesic]
[template ex_mean_geodesic[] [link
    boost_graph.reference.algorithms.measures.mean_geodesic.examples.mean_geodesic_distance
    Mean Geodesic Example]]
[template ex_inclusive_mean_geodesic[] [link
    boost_graph.reference.algorithms.measures.mean_geodesic.examples.inclusive_mean_geodesic_distance
    Inclusive Mean Geodesic Example]]

[heading Overview]
The /mean geodesic distance/ measure is used in large network analysis to identify
central vertices and as a measure of the /small-world phenomenon/. The mean geodesic
distance of a vertex is defined as the average of geodesic distances from that
vertex every /other/ vertex in the graph. It is computed as:

[$images/eq/mean_geodesic.png]

Where /d(u,v)/ is the shortest path (geodesic distance) from /u/ to /v/. Note
that this excludes /d(u,u)/ from the average, even if /d(u,u)/ is non-zero, which
is rare for social networks. Note that if any vertex in the graph is unreachable
from any other, then the graph is unconnected, and the distance between those two
unonnected vertices is infinite. This imlplies that the closeness of every vertex
in an unconnected (and undirected) graph is also infinite. This is not necessarily
the case for directed graphs.

The mean geodesic distance is often used to quantify whether or not a graph exhibits
the so-called small-world phenomenon. If the mean geodesic distance of a graph is
small with respect to its density (the ratio of vertices to edges), then the graph
is said to exhibit the small-world phenomenon. This implies that vertices are
The mean geodesic distance of a graph, it's so-called /small-world distance/, is
the average of the mean geodesics for each vertex. It is computed as:

[$images/eq/small_world.png]

Note that computing the measure in this fashion means that the small-world distance
of the graph may lie outside the minimum and maximum mean geodesic distances of its
vertices.

Consider a social network of friends, which is represented by an undirected graph.

[figure
    images/reference/social_network.png
    *Figure 1.* A network of friends.
]

In this network, Frank has the lowest mean geodesic distance with an average of
1.375. Scott and Laurie have the second lowest distances with values of 1.5 and
1.875 respectively. The small-world distance of this graph is approximately 1.92.
See the [ex_mean_geodesic] for details on computing the mean geodesic and small
world distances of undirected graphs.

This framework also allows for a specialization of measures used to compute these
values. The default measures used in this framework implement the formulas given
above. In some instances, it may be worthwhile to redefine the measure. For example,
if a graph has meaningful non-zero distance-to-self, the averages should be computed
over all vertices instead of excluding the vertex for which distances are being
averaged. See the [ex_inclusive_mean_geodesic] for details on defining alternative
measures, and using weighted graphs to find shortest paths.

[section [^mean_geodesic()]]
    #include <boost/graph/geodesic_distance.hpp>

    template <typename Graph, typename DistanceMap>
    float mean_geodesic(const Graph& g, DistanceMap dm)

    template <typename ResultType, typename Graph, typename DistanceMap>
    ResultType mean_geodesic(const Graph& g, DistanceMap dm)

    template <typename Graph, typename DistanceMap, typename Measure>
    typename Measure::result_type
    mean_geodesic(const Graph& g, DistanceMap dm, Measure m)

The `mean_geodesic()` function can be used to compute the mean geodesic distance
(its average distance to all other vertices) for a single vertex. This function
requires a distance map that contains the distance from one vertex (the source) to
all others in the graph. This distance map can be computed as the result of a
shortest paths algorithm such as [dijkstra_shortest_paths] or [bellman_ford_shortest_paths].
If the graph is unweighted, distances can be recorded from a [breadth_first_search].

[heading Parameters]
[table
    [[Type] [Parameter] [Description]]
    [
        [template] [`ResultType`]
        [
            The `ResultType` template parmeter explitly specifies the the
            return type of the `closeness()` function. If not
            given, the return type is `float`.

            *Requirements:* The return type is required to model the
            [NumericValue] concept.
        ]
    ]
    [
        [required, in] [`const Graph& g`]
        [
            The graph for which vertex measures are being comptued.

            *Requirements:* The `Graph` type must be a model of the
            [VertexListGraph] concepts.
        ]
    ]
    [
        [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].
        ]
    ]
    [
        [optional, in] [`Measure measure`]
        [
            The 'measure' parameter is an instance of a closeness measure that
            performs the final division 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` parameter. The `result_type` of the `Measure` must
            model the [NumericValue] concept.
        ]
    ]
]

[heading Return]
The `mean_geodesic()` function returns the average of geodesic distances
to other vertices from a source. If the source vertex is not connected to one other
in the graph, this value is infinite.

[heading Complexity]
The `mean_geodesic()` function returns in /O(n*O(M))/ where /n/ is the number of
vertices in the graph and /O(M)/ is the complexity of the given measure. If no
measure is given, this function returns in linear time.
[endsect]

[section [^all_mean_geodesics()]]
    #include <boost/graph/geodesic_distance.hpp>

    template <typename Graph, typename DistanceMatrixMap, typename GeodesicMap>
    typename property_traits<GeodesicMap>::value_type
    all_mean_geodesics(const Graph& g, DistanceMatrixMap dm, GeodesicMap gm)

    template <typename Graph, typename DistanceMatrixMap, typename GeodesicMap, typename Measure>
    typename property_traits<GeodesicMap>::value_type
    all_mean_geodesics(const Graph& g, DistanceMatrixMap dm, GeodesicMap gm, Measure m)

The `all_mean_geodesics()` function computes the average distance of each vertex in a
graph to every other vertex using a matrix that contains the distances between
each pair of vertices. This matrix can be computed as the output of an all-pairs shortest
path algorithm (e.g., [floyd_warshall_all_pairs_shortest_paths] or [johnson_all_pairs_shortest_paths])
or as the result of repeated [breadth_first_search]s (if the graph is unweighted).

This function returns the average of all mean geodesic distances, also known as the
small-world distance. If any vertices have infinite mean geodesic distance, this
return value will be infinite.

[heading Parameters]
[table
    [[Type] [Parameter] [Description]]
    [
        [required, in] [`const Graph& g`]
        [
            The graph for which vertex measures are being comptued.

            *Requirements:* The `Graph` type must be a model of the
            [VertexListGraph] concepts.
        ]
    ]
    [
        [required, in] [`DistanceMatrixMap dm`]
        [
            Given vertices /u/ and /v/, the `dm` parameter provides the length
            of the shortest path between the two vertices.

            *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, both] [`GeodesicMap gm`]
        [
            The geodesic map `gm` stores the resulting mean geodesic distances for
            each vertex in the graph.

            *Requirements:* The `GeodesicMap` type must be a model of the
            [WritablePropertyMap] concept. The `key_type` of this parameter
            must be the same as the `vertex_descriptor` of the `Graph` parameter,
            and the `value_type` must be a model of the [NumericValue] concept.
        ]
    ]
    [
        [optional, in] [`Measure measure`]
        [
            The 'measure' parameter is an instance of a closeness measure operates
            on the sum of distances of a vertex.

            *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 `all_mean_geodesics()` function returns the small-world distance for the graph.
This is the average of the mean geodesic distances of all vertices in the graph.
If any vertices have infinite mean geodesic distance, then the small-world distance
will also be infinite.

[heading Complexity]
The `all_mean_geodesics()` function returns in ['O(n[sup 2]*O(M))] where /n/ is the
number of vertices in the graph, and /O(M)/ is the complexity of the given measure.
If no measure is given, this function returns in quadratic time.
[endsect]

[section [^small_world_distance()]]
    #include <boost/graph/geodesic_distance.hpp>

    template <typename Graph, typename GeodesicMap, typename Measure>
    typename Measure::result_type
    small_world_distance(const Graph& g, GeodesicMap gm, Measure m)

    template <typename Graph, typename GeodesicMap>
    typename property_traits<GeodesicMap>::value_type
    small_world_distance(const Graph& g, GeodesicMap gm)

The `small_world_distance()` function computes the mean geodesic distance for the
entire graph by averaging the mean geodesic distances of each vertex in the geodesic
distance map. Note that this function does not compute the mean geodesic distances
of each vertex. Those values must be computed by using the [mean_goedesic] function.

[heading Parameters]
[table
    [[Type] [Parameter] [Description]]
    [
        [required, in] [`const Graph& g`]
        [
            The graph for which vertex measures are being comptued.

            *Requirements:* The `Graph` type must be a model of the
            [VertexListGraph] concepts.
        ]
    ]
    [
        [required, both] [`GeodesicMap gm`]
        [
            The geodesic map `gm` contains the previously computed mean geodesic
            distances for each vertex in the graph.

            *Requirements:* The `GeodesicMap` type must model the [ReadablePropertyMap]
            concept. The `key_type` of this parameter must be the same as the
            `vertex_descriptor` of the `Graph` parameter, and the `value_type` must
            be a model of the [NumericValue] concept.
        ]
    ]
    [
        [optional, in] [`Measure measure`]
        [
            The 'measure' parameter is an instance of a closeness measure that
            performs the final division 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 `GeodesicMap`. The `result_type` must model the [NumericValue]
            concept.
        ]
    ]
]

[heading Return]
The `small_world_distance()` function returns the mean geodesic distance for the
entire graph - a common measure of the small-world property. If the graph is
unconnected, the mean geodesic distance is infinite.

[heading Complexity]
The `small_world_distance()` function returns in /O(n*O(M))/ where /n/ is the number
of vertices in the graph and /O(M)/ is the complexity of the measure. If not measure
is given, then this function returns in linear time.
[endsect]

[section Examples]
[heading Mean Geodesic Distance]
This example shows how to compute the mean geodesic distance for each vertex
in a social network, and the mean geodesic distance for the graph as a whole.
This example includes the files

* [^examples/mean_geodesic.hpp]
* [^examples/helper.hpp]

[mean_geodesic_example]

In this example, the small world distance (`sw`) can be computed separetly from
the mean geodesic distances if need be.

    // Compute the small-world distance after computing mean geodesics
    float sw = small_world_distance(g, gm);

If given the file `social_network.graph` as input, the output of this program will
be:

[pre
Scott       1.5
Jill        2.125
Mary        2
Bill        2.125
Josh        2
Frank       1.375
Laurie      1.875
Anne        2.125
Howard      2.125
small world distance: 1.91667
]

Note that this program can be easily modified to work on directed graphs. In the
file `social_network.hpp`, simply replace `typedef undirected_graph<Actor> ...` to
`typedef directed_graph<Actor> ...`.

[heading Inclusive Mean Geodesic Distance]
This example shows how to implement alternative measures for the [mean_geodesic]
and [graph_mean_geodesic] functions to account for non-zero length self-loop
distances. Mean geodesic distances are computed both ways and the results printed
to standard output. This example includes the files:

* [^examples/mean_geodesic.hpp]
* [^examples/helper.hpp]

[inclusive_mean_geodesic_example]

If given the file `prob_network.graph` as input, the output of this program will
be:

[pre
vertex      excluding   including
myspace     0.941667    0.807143
digg        0.538333    0.461429
blogger     0.496667    0.425714
slashdot    0.721667    0.618571
wikipedia   0.498333    0.427143
blogspot    0.763333    0.654286
bbc         0.818333    0.701429
small world (excluding self-loops): 0.682619
small world (including self-loops): 0.585102
]

[endsect]
[endsect]