boost::betweenness_centrality_clustering — Graph
clustering based on edge betweenness centrality.
@@ -48,53 +52,68 @@ clustering based on edge betweenness centrality.
Description
-
-
Parameters
-
-
done
-
-
The function object that indicates termination of the algorithm.
-It must be a ternary function object thats accepts the maximum
-centrality, the descriptor of the edge that will be removed, and
-the graph g .
-
-
edge_centrality
-
-
(UTIL/OUT) The property map that will store the betweenness
-centrality for each edge. When the algorithm terminates, it will
-contain the edge centralities for the graph. The type of this
-property map must model the ReadWritePropertyMap concept. Defaults
-to an iterator_property_map whose
-value type is Done::centrality_type
-and using get(edge_index, g) for
-the index map.
-
-
g
-
-
The graph on which clustering will be performed. The type of
-this parameter (MutableGraph ) must
-be a model of the VertexListGraph, IncidenceGraph, EdgeListGraph,
-and Mutable Graph concepts.
-
-
vertex_index
-
-
(IN) The property map that maps vertices to indices in the range
-[0, num_vertices(g)). This type of this property map must model the
-ReadablePropertyMap concept and its value type must be an integral
-type. Defaults to get(vertex_index,
-g) .
-
-
-
This algorithm implements graph clustering based on edge
betweenness centrality. It is an iterative algorithm, where in each
step it compute the edge betweenness centrality (via brandes_betweenness_centrality) and
+"betweenness_centrality.html">brandes_betweenness_centrality) and
removes the edge with the maximum betweenness centrality. The
done function object determines
when the algorithm terminates (the edge found when the algorithm
terminates will not be removed).
-
+
+
Parameters
+IN: const Graph& g
+
+ The graph object on which the algorithm will be applied. The type
+ Graph must be a model of Vertex List Graph and Incidence Graph. When an edge
+ centrality map is supplied, it must also model Edge List Graph and MutableGraph.
+
+Python: The parameter is named graph.
+
+
+IN: Done done
+
+The function object that indicates termination of the algorithm.
+It must be a ternary function object thats accepts the maximum
+centrality, the descriptor of the edge that will be removed, and
+the graph g.
+Python: Any callable Python object will suffice.
+
+ This property map is used to accumulate the betweenness centrality
+ of each edge, and is a secondary form of output for the
+ algorithm. The type EdgeCentralityMap must be a model of Read/Write
+ Property Map, with the graph's edge descriptor type as its key
+ type. The value type of this property map should be the same as the
+ value type of the CentralityMap property map.
+
+ Default: a dummy_property_map, which requires no
+ work to compute and returns no answer.
+ Python: The color map must be a edge_double_map for
+ the graph.
+ Python default: graph.get_edge_double_map("centrality")
+
+
+IN: VertexIndexMap vertex_index
+
+ This maps each vertex to an integer in the range [0,
+ num_vertices(g)). This is necessary for efficient updates of the
+ heap data structure when an edge is relaxed. The type
+ VertexIndexMap must be a model of
+ Readable Property Map. The value type of the map must be an
+ integer type. The vertex descriptor type of the graph needs to be
+ usable as the key type of the map.
+ Default:get(vertex_index, g)
+ Python: Unsupported parameter.
+
+
diff --git a/doc/history.html b/doc/history.html
index 979a74d8..5dca5d24 100644
--- a/doc/history.html
+++ b/doc/history.html
@@ -82,6 +82,7 @@ September 27, 2000.
The Boost Graph Library offers a wealth of graph algorithms and
data types for C++. These algorithms are flexible and efficient,
but the mechanisms employed to achieve this goal can result in
@@ -28,6 +28,38 @@
efficiency, making it possible to rapidly develop useful systems
using the BGL in Python.
The Python bindings for the Graph library are experimental at
this time. The bindings may not work (but they probably do) and we
@@ -48,6 +80,28 @@
GCC are okay but Visual C++ 7.1 will crash. We're working to
resolve the situation.
The goal of the BGL-Python bindings is to create a set of
+ bindings for the majority of the BGL in Python that:
+
+
"Feel" like the BGL, but with Python syntax.
+
Allow rapid prototyping of algorithms for the BGL.
+
Allow easy porting from the BGL in Python to the BGL in
+ C++.
+
Permit the use of the BGL in applications for which C++ is
+ not particularly well suited.
+
Strike a balance between simplicity, usability, and
+ efficiency.
+
+
+
Note that one goal we did not list is that the Python syntax be
+ perfect for Python. For instance, one might implement a graph
+ library in Python very differently from the way the BGL is
+ implemented in C++, and the Python version may be syntactically
+ superior. Nonetheless, having a strong syntactic correlation
+ between the BGL in C++ and the BGL in Python is important for this
+ project.
The
+ Python bindings for the Boost Graph Library retain essentially the
+ same syntax. Because of this, there is no separate documentation
+ for the BGL in Python: each BGL component (algorithms, data
+ structures, etc.) available in Python will be marked with the
+ Python symbol . Unless an explicit Python section (or
+ field) is present, the Python versions have precisely the same
+ semantics as the C++ version.
+
+
Graph types
+
+
The C++ Boost Graph Library provides several graph types that
+ permit the generation of a huge number of specific graph types. In
+ Python, the BGL only exposes two general-purpose graph
+ types: Graph and Digraph, for undirected and
+ directed graphs, respectively. Both graph types are part of
+ the bgl extension module for Python. These graph types
+ are one-size-fits-most, offering stable vertex and edge
+ descriptors and a core set of operations from the adjacency_list class
+ template. The following sections briefly describe the operations
+ that can be performed on both the Graph
+ and Digraph Python graph types, although the
+ documentation uses Graph in the description.
+
+
Unlike the C++ graph types in the BGL, the Python graph types
+ use object-oriented syntax. For
+ instance, num_vertices(g) retrieves the number of
+ vertices in graph g in C++, whereas the Python
+ equivalent is g.num_vertices(). All of the graph
+ operations described in the following text are methods of the
+ graph type.
+
+
Types
+
Graph.Vertex
+
+The type of a vertex descriptor in the graph Graph that will
+be used to refer to vertices in the graph. Note that there may be
+several Python objects that refer to the same vertex, which can be
+compared with == and != correctly.
+Bug: Vertex descriptors do not work properly when used in a
+Python dict.
+
+
+
Graph.Edge
+
+The type of a edge descriptor in the graph Graph that will
+be used to refer to edges in the graph. Note that there may be
+several Python objects that refer to the same edge, which can be
+compared with == and != correctly.
+Bug: Edge descriptors do not work properly when used in a
+Python dict.
+
+
+
Constructors
+
Graph()
+
+Constructs an empty graph.
+
+
+
Graph(edges, name_map = "")
+
+Constructs a graph from a list of edges. edges should be a
+Python sequence, the elements of which should be 2-tuples containing
+the source and target of the edge. The sources and targets can be of
+any type that has a less-than operator defined, e.g., strings or
+integers. If a non-empty string is provided for name_map,
+a vertex_object_map will be created that maps from the
+vertices that are created to the name used in the list of edges.
+
+
+
Graph(filename, kind)
+
+Constructs a graph from an external file using one of the Boost Graph
+Library's graph parsers. filename is a string containing the
+file name. kind is an value of type bgl.file_kind,
+which has one of the following values:
+
+
bgl.file_kind.adjlist: Reads an adjacency-list
+representation into the graph. In the file, each line represents a
+single edge. On that line will be the source and target of the edge,
+separated by one or more spaces.
+
bgl.file_kind.graphviz: Reads a GraphViz DOT file into the
+graph. The DOT file must represent a graph that is directed (for
+a Digraph) or undirected (for a Graph). See read_graphviz for additional details.
+
+
+
+
Graph(generator, seed)
+
+Constructs a graph using the random generator generator and
+random seed value seed (an integer). The generator
+parameter may be one of three things:
+
+
bgl.ErdosRenyi(n, p): Generates a graph
+ with n vertices and a probability 0 <= p >=
+ 1 of having an edge between any two vertices u
+ and v.
+
+
bgl.SmallWorld(n, k, p): Generates a small-world graph
+ with n vertices, each of which is connected to
+ its k nearest neighbors (assuming one places the vertices
+ in a circle). With probability p, each edge in the graph is
+ randomly rewired.
+
+
bgl.PowerLawOutDegree(n, alpha, beta): Generates a
+ scale-free graph using the Power Law Out Degree model
+ with n vertices. Each vertex has degree beta *
+ x-alpha, where x is a random value between 0
+ and n-1. The value of beta controls the y-intercept of the
+ curve, so that increasing beta increases the average degree of
+ vertices. The value of alpha controls how steeply the curve drops
+ off, with larger values indicating a steeper curve. The web graph,
+ for instance, has alpha ~ 2.72.
+
+
+
+
General operations
+
is_directed()
+
+Returns True if the edges in the graph are
+directed, False otherwise.
+
+
+
Vertex List Graph operations
+
num_vertices()
+
+Returns the number of vertices in the graph.
+
+
+
vertices
+
+Returns a sequence containing all vertices in the graph. This
+sequence has a Python iterator, such that the following Python code
+prints the names of all vertices in graph g:
+
+for v in g.vertices:
+ print name[v]
+
+
+
+
Edge List Graph operations
+
num_edges()
+
+Returns the number of edges in the graph.
+
+
+
edges
+
+Returns a sequence containing all edges in the graph. This
+sequence has a Python iterator, such that the following Python code
+prints the weights of all edges in graph g:
+
+for e in g.edges:
+ print weight[e]
+
+
+
+
Mutable Graph operations
+
add_vertex()
+
+Adds a new vertex to the graph and returns the descriptor of the new
+vertex. Default values for all property maps attached to the graph
+will be provided for this vertex.
+
+
+
clear_vertex(v)
+
+Removes all of the incoming and outgoing edges to the
+vertex v. The properties for each of the edges removed will
+be removed from the property maps attached to the graph.
+
+
+
remove_vertex(v)
+
+Removes the vertex v from the graph. Before invoking this
+function, there must be no edges attached to this vertex (either
+incoming or outgoing), which can be ensured by a call
+to clear_vertex(v). Properties associated with this vertex
+will be removed from the property maps attached to the graph. Once
+this call completes, the vertex descriptor v is considered
+invalid and cannot be used again.
+
+
+
add_edge(u, v)
+
+Add an edge (u, v) to the graph and returns the descriptor for
+the new edge. Default values for all property maps attached to the graph
+will be provided for this edge.
+
+
+
remove_edge(e)
+
+Remove the edge e from the graph. The properties
+for e will be be removed from the property maps attached to
+the graph. Once this operation completes, the edge
+descriptor e is considered invalid and cannot be used again.
+
+
+
Incidence Graph operations
+
source(e)
+
+Returns the source of the edge e.
+
+
+
target(e)
+
+Returns the target of the edge e.
+
+
+
out_edges(u)
+
+Returns a sequence containing all edges outgoing
+from u. This sequence has an iterator, so that the following
+Python code prints the weights of all edges outgoing from
+vertex u in graph g:
+
+for e in g.out_edges(u):
+ print weight[e]
+
+For each edge e, g.source(e) == u.
+
+
+
out_degree(u)
+
+Returns the number of edges outgoing from vertex u.
+
+
+
in_edges(v)
+
+Returns a sequence containing all edges incoming
+to v. This sequence has an iterator, so that the following
+Python code prints the weights of all edges incoming to
+vertex v in graph g:
+
+for e in g.in_edges(u):
+ print weight[e]
+
+For each edge e, g.target(e) == v. For undirected
+graphs, the in_edges will be equivalent to
+the out_edges, except that the source and target will be
+swapped.
+
+
+
in_degree(u)
+
+Returns the number of edges incoming to vertex u. For
+undirected graphs, g.in_degree(u) == g.in_degree(v).
+
+
+
adjacent_vertices(u)
+
+Returns a sequence containing all vertices adjacent to
+u. This sequence has an iterator, so that the following
+Python code prints the names of all vertices adjacent to
+vertex u in graph g:
+
+for v in g.adjacent_vertices(u):
+ print name[v]
+
+The sequence of adjacent vertices for vertex u corresponds to
+the targets of the outgoing edges of u.
+
+
+
Vertex property maps
+
has_vertex_map(name)
+
+Returns True if the graph contains a vertex property map
+with the name name.
+
+
+
get_vertex_index_map()
+
+Returns a property map that maps vertex descriptors to indices in the
+range [0, g.num_vertices()).
+
+
+
get_vertex_color_map()
+
+Returns a property map that maps vertex descriptors to values of the
+Python type bgl.Color, which is an enumeration containing
+the values white, gray, and black. If a
+property map of this name already exists, its values are converted to
+colors. Otherwise, a new map is created.
+
+
+
get_vertex_double_map()
+
+Returns a property map that maps vertex descriptors to double
+values. If a property map of this name already exists, its values are
+converted to doubles. Otherwise, a new map is created.
+
+
+
get_vertex_int_map()
+
+Returns a property map that maps vertex descriptors to int
+values. If a property map of this name already exists, its values are
+converted to ints. Otherwise, a new map is created.
+
+
+
get_vertex_string_map()
+
+Returns a property map that maps vertex descriptors to string
+values. If a property map of this name already exists, its values are
+converted to strings. Otherwise, a new map is created.
+
+
+
get_vertex_object_map()
+
+Returns a property map that maps vertex descriptors to
+Python objects. If a property map of this name already
+exists, its values are converted to objects. Otherwise, a new
+map is created.
+
+
+
get_vertex_point_map()
+
+Returns a property map that maps vertex descriptors to values of the
+Python type bgl.Point2D, which is an class
+containing x and y attributes
+storing double values. If a property map of this name already
+exists, its values are converted to 2-D points. Otherwise, a new map
+is created.
+Bug: Writing just the x or y attributes of
+a bgl.Point2D object does not work at this time. However,
+you can create a new bgl.Point2D object and assign it into
+the property map.
+
+
+
Edge property maps
+
has_edge_map(name)
+
+Returns True if the graph contains a edge property map
+with the name name.
+
+
+
get_edge_index_map()
+
+Returns a property map that maps edge descriptors to indices in the
+range [0, g.num_edges()).
+
+
+
get_edge_color_map()
+
+Returns a property map that maps edge descriptors to values of the
+Python type bgl.Color, which is an enumeration containing
+the values white, gray, and black. If a
+property map of this name already exists, its values are converted to
+colors. Otherwise, a new map is created.
+
+
+
get_edge_double_map()
+
+Returns a property map that maps edge descriptors to double
+values. If a property map of this name already exists, its values are
+converted to doubles. Otherwise, a new map is created.
+
+
+
get_edge_int_map()
+
+Returns a property map that maps edge descriptors to int
+values. If a property map of this name already exists, its values are
+converted to ints. Otherwise, a new map is created.
+
+
+
get_edge_string_map()
+
+Returns a property map that maps edge descriptors to string
+values. If a property map of this name already exists, its values are
+converted to strings. Otherwise, a new map is created.
+
+
+
get_edge_object_map()
+
+Returns a property map that maps edge descriptors to
+Python objects. If a property map of this name already
+exists, its values are converted to objects. Otherwise, a new
+map is created.
+
+
+
Input/Output operations
+
read_graphviz(filename, node_id = "node_id")
+
+Reads a GraphViz file
+named filenameinto the graph, which is assumed to be
+empty. The operation will create a vertex_string_map
+named node_id that maps from vertex descriptors to the node
+identifiers in the GraphViz file. All vertex and edge attributes
+stored in the file will be loaded into vertex_string_map
+and edge_string_map property maps, respectively. An exception
+will be thrown if parsing of the GraphViz file fails.
+
+
+
write_graphviz(filename, node_id = None)
+
+Writes the graph into a file named filename in GraphViz format. All vertex and
+edge attributes stored in the graph's property maps will be written to
+the file. If node_id is provided, the vertex identifiers in
+the GraphViz output will correspond with the names provided in the
+vertex property map node_id. Otherwise, integer indices will
+be used to identify nodes in the output file.
+
+
+
Algorithms
+
+
All algorithms available in Python operate only on the Python
+ graph types supplied by the BGL-Python bindings and are not
+ generic in the same sense as their C++ counterparts. However,
+ unless marked otherwise, their parameters are still customizable
+ from Python. See, for instance, breadth_first_search,
+ which can still be provided with a customized queue and visitor
+ from within Python.
+
+
All algorithms are in the bgl extension module, at the
+ top level, and have the same names as in C++.
+
+
The parameters of BGL functions exposed to Python have the same
+ general data types, order, and names as in C++. If the BGL
+ function takes named parameters, then the names of the parameters
+ can be used for keyword arguments in Python. For instance:
Unless otherwise specified, all parameters documented in C++
+ are available in Python. If there are any differences, the
+ parameter documentation will contain a Python line
+ describing those differences. If the default in Python differs
+ from the C++ default, the parameter documentation will contain
+ a Python default line. Finally, if the algorithm's
+ behavior is radically different in Python, the algorithm will
+ contain a "Python" section. Although not available now, we would
+ like to rewrite the C++ examples in Python and add a "Python
+ Example" for each algorithm with inline examples.
+
+
Property Maps
+
+
Property maps in Python allow the same [] operator
+ syntax as Python dictionaries. For instance, if we have a property
+ map rank mapping vertices to integers, we can increment
+ the rank of vertex v with the following Python code:
+
+rank[v] = rank[v] + 1
+
+
+
However, unlike Python dictionaries one cannot enumerate the
+ keys or values in a property map. Instead, you must enumerate the
+ vertex or edges in the graph to index into the Python property
+ map. This restriction follows from the C++ formulation of
+ property maps, which do not allow such iteration.
+
+
A simple visualization tool
+
+
The program vis.py, in the examples/python
+ subdirectory, is a simple Graph visualization tool written in
+ Python using the BGL bindings. It can load graphs, perform graph
+ layout, run a few graph algorithms on graphs, etc. At present, it
+ is not a useful program per se but merely an example of
+ what can be achieved (quickly!) using the BGL-Python bindings. To
+ use this program you will need to install wxPython.
+
+
Request for comments
+
+
We want YOU to send it comments, questions, bug reports,
+ or suggestions for the BGL-Python bindings. They are experimental,
+ used primarily in-house for rapid prototyping of graph systems. If
+ you have any ideas, please post them to the Boost-Users
+ or Boost
+ Developers mailing lists, or e-mail me directly at .
Function
-betweenness_centrality_clustering
+
+
. Unless an explicit Python section (or
+ field) is present, the Python versions have precisely the same
+ semantics as the C++ version.