Commit 7da1f0a9 authored by Tiago Peixoto's avatar Tiago Peixoto

Ongoing documentation improvement

This modified several docstrings and introduces a quick-start guide.
parent 9d542a89
{% extends "!layout.html" %}
{% block rootrellink %}
<li><img src="/gfx/graph-icon.png" alt="logo" style="margin-right: 5px; margin-bottom:-2px;" /><a href="/graph-tool/">Project Homepage</a> &raquo;</li>
{{ super() }}
{% endblock %}
all:
sphinx-build -E -b html . build
test:
OMP_NUM_THREADS=1 sphinx-build -b doctest . build
push:
rsync -rEvpLz build/* root@forked.de:/var/www/graph-tool-doc/
.. automodule:: graph_tool.centrality
:members:
.. automodule:: graph_tool.clustering
:members:
:undoc-members:
.. automodule:: graph_tool.community
:members:
:undoc-members:
......@@ -16,7 +16,7 @@ import sys, os
# If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
#sys.path.append(os.path.abspath('.'))
sys.path.append(os.path.abspath('.'))
# General configuration
# ---------------------
......@@ -43,7 +43,7 @@ master_doc = 'index'
# General information about the project.
project = u'graph-tool'
copyright = u'2008, Tiago de Paula Peixoto'
copyright = u'2009, Tiago de Paula Peixoto <tiago@forked.de>'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......@@ -52,7 +52,7 @@ copyright = u'2008, Tiago de Paula Peixoto'
# The short X.Y version.
version = '2.0'
# The full version, including alpha/beta/rc tags.
release = '2.0'
release = '2.0beta1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -88,6 +88,13 @@ exclude_trees = ['.build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# doctest
doctest_global_setup = \
"""
import graph_tool.all as gt
from numpy import array
"""
# Options for HTML output
# -----------------------
......@@ -111,7 +118,7 @@ html_style = 'default.css'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
html_favicon = "graph-icon.ico"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
......@@ -143,12 +150,12 @@ html_static_path = ['.static']
#html_split_index = False
# If true, the reST sources are included in the HTML build as _sources/<name>.
#html_copy_source = True
html_copy_source = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
html_use_opensearch = 'http://projects.forked.de/graph-tool/doc/'
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
......@@ -192,4 +199,7 @@ latex_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/dev': None}
intersphinx_mapping = {'http://docs.python.org': None,
'http://docs.scipy.org/doc/numpy': None,
'http://docs.scipy.org/doc/scipy/reference': None,
'http://matplotlib.sourceforge.net' : None}
.. automodule:: graph_tool.correlations
:members:
:undoc-members:
.. automodule:: graph_tool.draw
:members:
:undoc-members:
.. automodule:: graph_tool.generation
:members:
:undoc-members:
......@@ -6,4 +6,13 @@ Available subpackages
.. toctree::
centrality
clustering
community
correlations
draw
generation
misc
run_action
stats
util
\ No newline at end of file
.. automodule:: graph_tool.misc
:members:
:undoc-members:
#! /usr/bin/env python
# We probably will need some things from several places
import sys, os
from pylab import * # for plotting
from numpy.random import * # for random sampling
seed(42)
# We need to import the graph_tool module itself
from graph_tool.all import *
# let's construct a Price network (the one that existed before Barabasi). It is
# a directed network, with preferential attachment. The algorithm below is a
# very naive, and a bit slow, but quite simple.
# We start with an empty, directed graph
g = Graph()
# We want also to keep the age information for each vertex and edge. For that
# let's create some property maps
v_age = g.new_vertex_property("int")
e_age = g.new_edge_property("int")
# The final size of the network
N = 100000
# We have to start with one vertex
v = g.add_vertex()
v_age[v] = 0
# we will keep a list of the vertices. The number of times a vertex is in this
# list will give the probability of it being selected.
vlist = [v]
# let's now add the new edges and vertices
for i in xrange(1, N):
# create our new vertex
v = g.add_vertex()
v_age[v] = i
# we need to sample a new vertex to be the target, based on its in-degree +
# 1. For that, we simply randomly sample it from vlist.
i = randint(0, len(vlist))
target = vlist[i]
# add edge
e = g.add_edge(v, target)
e_age[e] = i
# put v and target in the list
vlist.append(target)
vlist.append(v)
# now we have a graph!
# let's calculate its in-degree distribution and plot it to a file
in_hist = vertex_hist(g, "in")
clf()
errorbar(in_hist[1], in_hist[0], fmt=".", yerr=sqrt(in_hist[0]))
gca().set_yscale("log")
gca().set_xscale("log")
xlabel("$k_{in}$")
ylabel("$P(k_{in})$")
savefig("deg-hist.png")
# let's do a random walk on the graph and print the age of the vertices we find,
# just for fun.
v = g.vertex(randint(0, g.num_vertices()))
for i in xrange(0, 100):
print "vertex:", v, "in-degree:", v.in_degree(), "out-degree:",\
v.out_degree(), "age:", v_age[v]
if v.out_degree() == 0:
print "Nowhere else to go... We found the main hub!"
break
n_list = []
for w in v.out_neighbours():
n_list.append(w)
v = n_list[randint(0, len(n_list))]
# let's save our graph for posterity We want to save the age properties as
# well... To do this, they must become "internal" properties, as such:
g.vertex_properties["age"] = v_age
g.edge_properties["age"] = e_age
# now we can save it
g.save("price.xml.gz")
This diff is collapsed.
.. automodule:: graph_tool.run_action
:members:
:undoc-members:
.. automodule:: graph_tool.stats
:members:
:undoc-members:
.. automodule:: graph_tool.util
:members:
:undoc-members:
......@@ -66,7 +66,7 @@ misc
stats
vertex and edge statistics
util
assorted untilities
assorted utilities
Utilities
---------
......@@ -77,6 +77,9 @@ show_config
__version__
``graph_tool`` version string
Classes
-------
"""
__author__="Tiago de Paula Peixoto <tiago@forked.de>"
......
This diff is collapsed.
......@@ -90,7 +90,7 @@ def local_clustering(g, prop=None, undirected=False):
>>> g = gt.random_graph(1000, lambda: (5,5), seed=42)
>>> clust = gt.local_clustering(g)
>>> print gt.vertex_average(g, clust)
(0.0045633333333333333, 0.00041406305209606802)
(0.005048478260869565, 0.00043544409486305209)
References
----------
......@@ -149,7 +149,7 @@ def global_clustering(g):
--------
>>> g = gt.random_graph(1000, lambda: (5,5), seed=42)
>>> print gt.global_clustering(g)
(0.0086380072318200073, 0.00044516087903790925)
(0.0079235400765494558, 0.00041721619682007839)
References
----------
......@@ -195,8 +195,8 @@ def extended_clustering(g, props=None, max_depth=3, undirected=False):
:math:`d` is defined as
.. math::
c^d_i = \frac{\left|\right\{ \{u,v\}; u,v \in N_i | d_{G(V\diagdown
\{i\})}(u,v) = d \left\}\right|}{\binom{\left|N_i\right|}{2}},
c^d_i = \frac{\left|\right\{ \{u,v\}; u,v \in N_i | d_{G(V\setminus
\{i\})}(u,v) = d \left\}\right|}{{\left|N_i\right| \choose 2}},
where :math:`d_G(u,v)` is the shortest distance from vertex :math:`u` to
:math:`v` in graph :math:`G`, and
......@@ -221,11 +221,11 @@ def extended_clustering(g, props=None, max_depth=3, undirected=False):
>>> for i in xrange(0, 5):
... print gt.vertex_average(g, clusts[i])
...
(0.0045633333333333333, 0.00041406305209606802)
(0.027705, 0.0010493633929938454)
(0.11730666666666667, 0.00201118990760307)
(0.41394666666666663, 0.0030157036105470745)
(0.41717499999999996, 0.0030272310298907366)
(0.005048478260869565, 0.00043544409486305209)
(0.025116811594202898, 0.00096935403523205497)
(0.11178014492753624, 0.0019836458026216146)
(0.40412130434782606, 0.0030616964103718316)
(0.43449992753623184, 0.003195885251613022)
References
----------
......@@ -303,11 +303,11 @@ def motifs(g, k, p=1.0, motif_list=None, undirected=None, seed=0):
Examples
--------
>>> g = gt.random_graph(1000, lambda: (5,5), seed=42)
>>> motifs, counts = gt.motifs(g, 4, undirected=True))
>>> motifs, counts = gt.motifs(g, 4, undirected=True)
>>> print len(motifs)
11
14
>>> print counts
[115708, 390659, 612, 696, 2872, 1556, 811, 4, 8, 6, 1]
[114942, 387657, 958, 1089, 2482, 2760, 844, 6, 16, 14, 8, 10, 16, 8]
References
----------
......@@ -445,7 +445,7 @@ def motif_significance(g, k, n_shuffles=10, p=1.0, motif_list=None,
z_i = \frac{N_i - \left<N^s_i\right>}
{\sqrt{\left<(N^s_i)^2\right> - \left<N^s_i\right>^2}},
where :math:`N_i` is the number of times motif $i$ found, and :math:`N^s_i`
where :math:`N_i` is the number of times motif i found, and :math:`N^s_i`
is the count of the same motif but on a shuffled network. It measures how
many standard deviations is each motif count, in respect to a ensemble of
randomly shuffled graphs with the same degree sequence.
......@@ -456,12 +456,12 @@ def motif_significance(g, k, n_shuffles=10, p=1.0, motif_list=None,
Examples
--------
>>> g = gt.random_graph(1000, lambda: (5,5), seed=42)
>>> g = gt.random_graph(100, lambda: (3,3), seed=42)
>>> motifs, zscores = gt.motif_significance(g, 3)
>>> print len(motifs)
11
10
>>> print zscores
[0.23425857453240315, 0.23849227914686885, 0.46705666396159251, 0.26171196129510765, -0.28131244310816039, -0.29007872608538582, -0.56694670951384085, -0.5, -0.33333333333333337, -0.46852128566581813, -0.5]
[-3.9501340809971031, -3.96459679349275, -5.95765904191577, -0.17407765595569785, 3.580195875015368, 3.5906624935876583, 2.2739701341354892, 1.8999999999999999, 0.0, -0.20000000000000001]
"""
from itertools import izip
from .. misc import random_rewire, isomorphism
......@@ -490,17 +490,21 @@ def motif_significance(g, k, n_shuffles=10, p=1.0, motif_list=None,
counts.append(0)
s_counts = [ x/float(n_shuffles) for x in s_counts ]
s_dev = [ sqrt(x[0]/float(n_shuffles) - x[1]**2) \
s_dev = [ max(sqrt(x[0]/float(n_shuffles) - x[1]**2),1) \
for x in izip(s_dev,s_counts) ]
list_hist = zip(s_ms, s_counts, s_dev)
# sort according to in-degree sequence
list_hist.sort(lambda x,y: cmp(sorted([v.in_degree() for v in x[0].vertices()]),
sorted([v.in_degree() for v in y[0].vertices()])))
list_hist.sort(lambda x,y: cmp(sorted([v.in_degree()\
for v in x[0].vertices()]),
sorted([v.in_degree()\
for v in y[0].vertices()])))
# sort according to out-degree sequence
list_hist.sort(lambda x,y: cmp(sorted([v.out_degree() for v in x[0].vertices()]),
sorted([v.out_degree() for v in y[0].vertices()])))
list_hist.sort(lambda x,y: cmp(sorted([v.out_degree()\
for v in x[0].vertices()]),
sorted([v.out_degree()\
for v in y[0].vertices()])))
# sort according to ascending number of edges
list_hist.sort(lambda x,y: cmp(x[0].num_edges(), y[0].num_edges()))
......
......@@ -16,6 +16,14 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
``graph_tool.community`` - Community structure
----------------------------------------------
This module contains algorithms for the computation of community structure on
graphs.
"""
from .. dl_import import dl_import
dl_import("import libgraph_tool_community")
......
......@@ -224,11 +224,11 @@ from libgraph_tool_core import Vertex, Edge, GraphError,\
new_graph_property
class Graph(object):
"""This class encapsulates either a directed multigraph (default) or an
undirected multigraph, with optional internal edge, vertex or graph
properties.
"""This class encapsulates either a directed multigraph (default or if
``directed=True``) or an undirected multigraph (if ``directed=False``), with
optional internal edge, vertex or graph properties.
It is implemented as a adjacency list, where both vertex and edge lists are
It is implemented as an adjacency list, where both vertex and edge lists are
C++ STL vectors.
"""
......@@ -480,7 +480,8 @@ class Graph(object):
>>> g.properties[("e", "foo")] = g.new_edge_property("vector<double>")
>>> g.vertex_properties["foo"] = g.new_vertex_property("double")
>>> g.vertex_properties["bar"] = g.new_vertex_property("python::object")
>>> g.graph_properties["gnat"] = g.new_graph_property("string")
>>> g.graph_properties["gnat"] = g.new_graph_property("string",\
"hi there!")
>>> g.list_properties()
gnat (graph) (type: string, val: hi there!)
bar (vertex) (type: python::object)
......
This diff is collapsed.
......@@ -16,9 +16,12 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
``graph_tool.draw`` - Graph Drawing
-----------------------------------
"""
import sys, os, os.path, time, warnings
import matplotlib.cm
import matplotlib.colors
from .. core import _degree, _prop, PropertyMap
from .. decorators import _limit_args
......@@ -27,6 +30,12 @@ try:
except ImportError:
warnings.warn("error importing gv module... graph_draw() will not work.",
ImportWarning)
try:
import matplotlib.cm
import matplotlib.colors
except ImportError:
warnings.warn("error importing matplotlib module... " + \
"graph_draw() will not work.", ImportWarning)
def graph_draw(g, pos=None, size=(15,15), pin=False, layout="neato",
maxiter=None, ratio="fill", overlap=False, splines=False,
......
......@@ -16,6 +16,11 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
``graph_tool.generation`` - Random Graph Generation
---------------------------------------------------
"""
from .. dl_import import dl_import
dl_import("import libgraph_tool_generation")
......
......@@ -16,6 +16,11 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
``graph_tool.misc`` - Miscellaneous functions
---------------------------------------------
"""
from .. dl_import import dl_import
dl_import("import libgraph_tool_misc")
......
......@@ -17,8 +17,11 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
``graph_tool.run_action`` - Inline C++ code embedding
-----------------------------------------------------
This module implements support for automatic ad-hoc code embedding into
graph-tool
graph-tool.
"""
__all__ = ["inline"]
......
......@@ -67,13 +67,43 @@ def get_graph_type(g):
return libgraph_tool_core.get_graph_type(g._Graph__graph)
def inline(code, arg_names=[], local_dict=None,
global_dict=None, force=0, compiler="gcc", verbose=0,
global_dict=None, force=False, compiler="gcc", verbose=False,
auto_downcast=1, support_code="", libraries=[],
library_dirs=[], extra_compile_args=[],
runtime_library_dirs=[], extra_objects=[],
extra_link_args=[], mask_ret=[], debug=False):
"""Compile (if necessary) and run the C++ action specified by 'code',
using weave."""
using weave. The (possibly modified) variables in 'arg_names' are returned.
Parameters
----------
code : string
C++ code to be used
arg_names : list, optional (default: [])
List of variables to be passed to the C++ code
local_dict : dict, optional (default: None)
Dictionary of variables to be used as local scope. If none is specified,
the calling functions' local variables are used.
global_dict : dict, optional (default: None)
Dictionary of variables to be used as global scope. If none is
specified, the calling functions' global variables are used.
force : bool, optional (default: False)
If true, compilation is forced.
compiler : string, optional (default: "gcc")
The name of compiler to use when compiling. On windows, it understands
'msvc' and 'gcc' as well as all the compiler names understood by
distutils. On Unix, it'll only understand the values understood by
distutils.
On windows, the compiler defaults to the Microsoft C++ compiler. If
this isn't available, it looks for mingw32 (the gcc compiler).
On Unix, it'll probably use the same compiler that was used when
compiling Python. Cygwin's behavior should be similar.
[...]
"""
# each term on the expansion will properly unwrap a tuple pointer value
# to a reference with the appropriate name and type
......@@ -200,9 +230,9 @@ def inline(code, arg_names=[], local_dict=None,
# call weave and pass all the updated kw arguments
ret_vals = \
scipy.weave.inline(inline_code, arg_alias, force=force,
scipy.weave.inline(inline_code, arg_alias, force=int(force),
local_dict=alias_dict, global_dict=global_dict,
compiler=compiler, verbose=verbose,
compiler=compiler, verbose=int(verbose),
auto_downcast=auto_downcast,
support_code=support_code,
libraries=libraries,
......
......@@ -16,6 +16,11 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
``graph_tool.stats`` - Graph Statistics
---------------------------------------
"""
from .. dl_import import dl_import
dl_import("import libgraph_tool_stats")
......@@ -27,30 +32,267 @@ __all__ = ["vertex_hist", "edge_hist", "vertex_average", "edge_average",
"label_self_loops", "remove_self_loops", "remove_labeled_edges"]
def vertex_hist(g, deg, bins=[1], float_count=True):
"""
Return the vertex histogram of the given degree type or property.
Parameters
----------
g : Graph
Graph to be used.
deg : string or PropertyMap
Degree or property to be used for the histogram. It can be either "in",
"out" or "total", for in-, out-, or total degree of the vertices. It can
also be a vertex property map.
bins : list of bins
List of bins to be used for the histogram. The values given represent
the edges of the bins (i,e, lower bounds). If the list contains only one
value, this will be used to automatically create an appropriate bin
range, with a constant lenght given by this value.
float_count : bool (optional, default: True)
If True, the counts in each histogram bin will be returned as floats. If
False, they will be returned as integers.
Returns
-------
counts : ndarray
The bin counts.
bins : ndarray
The bin edges.
See Also
--------
edge_hist: Edge histograms.
vertex_average: Average of vertex properties, degrees.
edge_average: Average of edge properties.
Notes
-----
The algorithm runs in :math:`O(|V|)` time.
If enabled during compilation, this algorithm runs in parallel.
Examples
--------
>>> from numpy.random import poisson, seed
>>> seed(42)
>>> g = gt.random_graph(1000, lambda: (poisson(5), poisson(5)), seed=42)
>>> print gt.vertex_hist(g, "out")
[array([ 10., 35., 92., 140., 162., 160., 150., 109., 66.,
37., 26., 10., 2., 1.]), array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], dtype=uint64)]
"""
ret = libgraph_tool_stats.\
get_vertex_histogram(g._Graph__graph, _degree(g, deg), bins)
return [array(ret[0], dtype="float64") if float_count else ret[0], ret[1]]
def edge_hist(g, eprop, bins=[1], float_count=True):
"""
Return the edge histogram of the given property.
Parameters
----------
g : Graph
Graph to be used.
eprop : PropertyMap
Edge property to be used for the histogram.
bins : list of bins
List of bins to be used for the histogram. The values given represent
the edges of the bins (i,e, lower bounds). If the list contains only one
value, this will be used to automatically create an appropriate bin
range, with a constant lenght given by this value.
float_count : bool (optional, default: True)
If True, the counts in each histogram bin will be returned as floats. If
False, they will be returned as integers.
Returns
-------
counts : ndarray
The bin counts.
bins : ndarray
The bin edges.
See Also
--------
vertex_hist : Vertex histograms.
vertex_average : Average of vertex properties, degrees.
edge_average : Average of edge properties.
Notes
-----
The algorithm runs in :math:`O(|E|)` time.
If enabled during compilation, this algorithm runs in parallel.