Ongoing documentation improvement

This modified several docstrings and introduces a quick-start guide.

doc/.templates/layout.html

+{% 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 %}

doc/Makefile

+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/

doc/centrality.rst

+.. automodule:: graph_tool.centrality
+   :members:

doc/clustering.rst

 .. automodule:: graph_tool.clustering
    :members:
+   :undoc-members:

doc/community.rst

+.. automodule:: graph_tool.community
+   :members:
+   :undoc-members:

doc/conf.py

@@ -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}

doc/correlations.rst

+.. automodule:: graph_tool.correlations
+   :members:
+   :undoc-members:

doc/draw.rst

+.. automodule:: graph_tool.draw
+   :members:
+   :undoc-members:

doc/generation.rst

+.. automodule:: graph_tool.generation
+   :members:
+   :undoc-members:

doc/graph_tool.rst

@@ -6,4 +6,13 @@ Available subpackages
 
 .. toctree::
 
+   centrality
    clustering
+   community
+   correlations
+   draw
+   generation
+   misc
+   run_action
+   stats
+   util 
\ No newline at end of file

doc/misc.rst

+.. automodule:: graph_tool.misc
+   :members:
+   :undoc-members:

doc/price.py

+#! /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")
+

doc/run_action.rst

+.. automodule:: graph_tool.run_action
+   :members:
+   :undoc-members:

doc/stats.rst

+.. automodule:: graph_tool.stats
+   :members:
+   :undoc-members:

doc/util.rst

+.. automodule:: graph_tool.util
+   :members:
+   :undoc-members:

src/graph_tool/__init__.py

@@ -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>"

src/graph_tool/clustering/__init__.py

@@ -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()))

src/graph_tool/community/__init__.py

@@ -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")
 

src/graph_tool/core.py

@@ -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)

src/graph_tool/draw/__init__.py

@@ -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,

src/graph_tool/generation/__init__.py

@@ -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")
 

src/graph_tool/misc/__init__.py

@@ -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")
 

src/graph_tool/run_action/__init__.py

@@ -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"]

src/graph_tool/run_action/inline.py

@@ -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,

src/graph_tool/stats/__init__.py

@@ -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.