|Revision 014d05, 11.1 KB checked in by Tiago de Paula Peixoto <tiago@…>, 4 years ago (diff)|
Quick start using graph-tool
The :mod:`graph_tool` module provides a :class:`~graph_tool.Graph` class and several algorithms that operate on it. The internals of this class, and of most algorithms, are written in C++ for performance.
The module must be of course imported before it can be used. The package is subdivided into several sub-modules. To import everything from all of them, one can do:
In the following, it will always be assumed that the previous line was run.
Creating and manipulating graphs
An empty graph can be created by instantiating a :class:`~graph_tool.Graph` class:
By default, newly created graphs are always directed. To construct undirected graphs, one must pass the directed parameter:
A graph can always be switched on-the-fly from directed to undirected (and vice versa), with the :meth:`~graph_tool.Graph.set_directed` method. The "directedness" of the graph can be queried with the :meth:`~graph_tool.Graph.is_directed` method,
A graph can also be created from another graph, in which case the entire graph (and its internal property maps, see :ref:`sec_property_maps`) is copied:
Once a graph is created, it can be populated with vertices and edges. A vertex can be added with the :meth:`~graph_tool.Graph.add_vertex` method,
which returns an instance of a :class:`~graph_tool.Vertex` class, also called a vertex descriptor. The :meth:`~graph_tool.Graph.add_vertex` method also accepts an optional parameter which specifies the number of vertices to create. If this value is greater than 1, it returns a list of vertices:
Each vertex has an unique index, which is numbered from 0 to N-1, where N is the number of vertices. This index can be obtained by using the :attr:`~graph_tool.Graph.vertex_index` attribute of the graph (which is a property map, see :ref:`sec_property_maps`), or by converting the vertex descriptor to an int.
There is no need to keep the vertex descriptor lying around to access them at a later point: One can obtain the descriptor of a vertex with a given index using the :meth:`~graph_tool.Graph.vertex` method,
Another option is to iterate through the vertices, as described in section :ref:`sec_iteration`.
Once we have some vertices in the graph, we can create some edges between them with the :meth:`~graph_tool.Graph.add_edge` method, which returns an edge descriptor (an instance of the :class:`~graph_tool.Edge` class).
Edges also have an unique index, which is given by the :attr:`~graph_tool.Graph.edge_index` property:
Unlike the vertices, edge indexes are not guaranteed to be continuous in any range, but they are always unique.
Both vertex and edge descriptors have methods which query associate information, such as :meth:`~graph_tool.Vertex.in_degree`, :meth:`~graph_tool.Vertex.out_degree`, :meth:`~graph_tool.Edge.source` and :meth:`~graph_tool.Edge.target`:
Iterating over vertices and edges
Algorithms must often iterate through the vertices, edges, out edge, etc. of the graph. The :class:`~graph_tool.Graph` and :class:`~graph_tool.Edge` classes provide the necessary iterators for doing so. The iterators always give back edge or vertex descriptors.
The code above will print the vertices and edges of the graph in the order they are found.
The out- and in-edges of a vertex, as well as the out- and in-neighbours can be iterated through with the :meth:`~graph_tool.Vertex.out_edges`, :meth:`~graph_tool.Vertex.in_edges`, :meth:`~graph_tool.Vertex.out_neighbours` and :meth:`~graph_tool.Vertex.in_neighbours` respectively.
Property maps are a way of associating additional to the vertices, edges or to the graph itself. There are thus three types of property maps: vertex, edge and graph. All of them are instances of the same class, :class:`~graph_tool.PropertyMap`. Each property map has an associated value type, which must be chosen from the predefined set:
New property maps can be created for a given graph by calling the :meth:`~graph_tool.Graph.new_vertex_property`, :meth:`~graph_tool.Graph.new_edge_property`, or :meth:`~graph_tool.Graph.new_graph_property`, for each map type. The values are then accessed by vertex or edge descriptors, or the graph itself, as such:
Internal property maps
Any created property map can be made "internal" to the respective graph. This means that it will be copied and saved to a file together with the graph. Properties are internalized by including them in the graph's dictionary-like attributes :attr:`~graph_tool.Graph.vertex_properties`, :attr:`~graph_tool.Graph.edge_properties` or :attr:`~graph_tool.Graph.graph_properties`. When inserted in the graph, the property maps must have an unique name (between those of the same type):
Graphs can be saved and loaded in two formats: graphml and dot. Graphml is the default and preferred format. The dot format is also supported, but since it contains no type information, all properties are read later as strings, and must be converted per hand. Therefore you should always use graphml, except when interfacing with another software which expects dot format.
A graph can be saved or loaded to a file with the :attr:`~graph_tool.Graph.save` and :attr:`~graph_tool.Graph.load` methods, which take either a file name or a file-like object. A graph can also be loaded from disk with the :func:`~graph_tool.load_graph` function, as such:
Graph classes can also be pickled with the :mod:`pickle` module.
An Example: Building a Price Network
We can draw the graph to see some other features of its topology. For that we use the :func:`~graph_tool.draw.graph_draw` function.