Docstring cross-reference cleanup

doc/conf.py

@@ -54,7 +54,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'graph-tool'
-copyright = u'2017, Tiago de Paula Peixoto <tiago@skewed.de>'
+copyright = u'2018, Tiago de Paula Peixoto <tiago@skewed.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
@@ -174,12 +174,12 @@ htmlhelp_basename = 'graph-tooldoc'
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'numpy': ('http://docs.scipy.org/doc/numpy', None),
-                       'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
-                       'matplotlib': ('http://matplotlib.org', None),
+                       'numpy': ('https://docs.scipy.org/doc/numpy', None),
+                       'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
+                       'matplotlib': ('https://matplotlib.org', None),
                        'cairo': ('https://www.cairographics.org/documentation/pycairo/3', None),
-                       'ipython': ('http://ipython.org/ipython-doc/stable/', None),
-                       'panda': ('http://pandas.pydata.org/pandas-docs/stable/', None)}
+                       'ipython': ('https://ipython.org/ipython-doc/stable/', None),
+                       'panda': ('https://pandas.pydata.org/pandas-docs/stable/', None)}
 
 extlinks_fancy = {'ticket': (['https://graph-tool.skewed.de/tickets/ticket/{0}'],
                              ['ticket {0}']),
@@ -189,17 +189,6 @@ extlinks_fancy = {'ticket': (['https://graph-tool.skewed.de/tickets/ticket/{0}']
                           ['DOI: {0}', "sci-hub", "@tor"]),
                   'arxiv': (['https://arxiv.org/abs/{0}'], ['arXiv: {0}'])}
 
-
-# def process_docstring(app, what, name, obj, options, lines):
-#     for i, line in enumerate(lines):
-#         if "arg1" in line and "->" in line:
-#             lines[i] = ""
-#         if "C++ signature :" in line or "graph_tool::Python" in line:
-#             lines[i] = ""
-
-# def setup(app):
-#     app.connect('autodoc-process-docstring', process_docstring)
-
 # plot directive
 import pyenv
 plot_rcparams = pyenv.rcParams
@@ -220,3 +209,5 @@ def linkcode_resolve(domain, info):
         return None
     modname = info['module'].replace('.', '/')
     return "https://git.skewed.de/count0/graph-tool/tree/master/src/%s/__init__.py" % modname
+
+nitpicky = True

doc/inference.rst

 .. automodule:: graph_tool.inference
     :no-undoc-members:
-    :show-inheritance:
+    :no-members:
 
 ..
    .. testcode:: inference_detailed
@@ -24,3 +24,50 @@
       :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
 
       OK
+
+.. automodule:: graph_tool.inference.blockmodel
+    :no-undoc-members:
+    :show-inheritance:
+
+    .. autoclass:: graph_tool.inference.blockmodel.PartitionHist
+    .. autoclass:: graph_tool.inference.blockmodel.BlockPairHist
+
+.. automodule:: graph_tool.inference.overlap_blockmodel
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.layered_blockmodel
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.nested_blockmodel
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.uncertain_blockmodel
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.mcmc
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.bisection
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.minimize
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.blockmodel_em
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.util
+    :no-undoc-members:
+    :show-inheritance:
+
+.. automodule:: graph_tool.inference.modularity
+    :no-undoc-members:
+    :show-inheritance:

src/graph_tool/__init__.py

@@ -703,7 +703,7 @@ class PropertyMap(object):
                   instead a :class:`~numpy.ma.MaskedArray` object is returned,
                   which contains only entries for vertices/edges which are not
                   filtered out. If there are no filters in place, a regular
-                  :class:`:class:`~graph_tool.PropertyArray`` is returned, which
+                  :class:`~graph_tool.PropertyArray` is returned, which
                   is identical to the :attr:`~PropertyMap.a` attribute.""")
 
     def get_2d_array(self, pos):
@@ -3347,6 +3347,8 @@ Edge.__name__ = "Edge"
 VertexBase.__doc__ = Vertex.__doc__
 VertexBase.out_neighbors = Vertex.out_neighbors
 VertexBase.in_neighbors = Vertex.in_neighbors
+VertexBase.out_edges = Vertex.out_edges
+VertexBase.in_edges = Vertex.in_edges
 VertexBase.all_edges = Vertex.all_edges
 VertexBase.all_neighbors = Vertex.all_neighbors
 VertexBase.in_degree = Vertex.in_degree

src/graph_tool/clustering/__init__.py

@@ -523,6 +523,13 @@ def motif_significance(g, k, n_shuffles=100, p=1.0, motif_list=None,
     11
     >>> print(zscores)
     [0.22728646681107012, 0.21409572051644973, 0.007022040788902111, 0.5872141967123348, -0.37770179603294357, -0.3484733504783734, 0.8861811801325502, -0.08, -0.2, -0.38, -0.2]
+
+    References
+    ----------
+    .. [wernicke-efficient-2006] S. Wernicke, "Efficient detection of network
+       motifs", IEEE/ACM Transactions on Computational Biology and
+       Bioinformatics (TCBB), Volume 3, Issue 4, Pages 347-359, 2006.
+       :doi:`10.1109/TCBB.2006.51`
     """
 
     s_ms, counts = motifs(g, k, p, motif_list)

src/graph_tool/collection/__init__.py

@@ -95,7 +95,7 @@ Examples
                                                                  representing the neural network of C. Elegans.
                                                                  Data compiled by D. Watts and S. Strogatz and
                                                                  made available on the web `here
-                                                                 <http://cdg.columbia.edu/cdg/datasets>`_. Please
+                                                                 <http://cdg.columbia.edu/cdg/datasets>`__. Please
                                                                  cite D. J. Watts and S. H. Strogatz, Nature 393,
                                                                  440-442 (1998). Original experimental data taken
                                                                  from J. G. White, E. Southgate, J. N. Thompson,
@@ -179,7 +179,7 @@ Examples
                                                                  Retrieved from `Mark Newman's website
                                                                  <http://www-personal.umich.edu/~mejn/netdata/>`_,
                                                                  with corrections by T. S. Evans, available 
-                                                                 `here <http://figshare.com/articles/American_College_Football_Network_Files/93179>`_.
+                                                                 `here <http://figshare.com/articles/American_College_Football_Network_Files/93179>`__.
         hep-th               8361         15751        False     High-energy theory collaborations: weighted
                                                                  network of coauthorships between scientists
                                                                  posting preprints on the High-Energy Theory
@@ -208,7 +208,7 @@ Examples
                                                                  and experiment, as compiled by M. Newman in May
                                                                  2006. A figure depicting the largest component
                                                                  of this network can be found `here
-                                                                 <http://www-personal.umich.edu/~mejn/centrality/>`_.
+                                                                 <http://www-personal.umich.edu/~mejn/centrality/>`__.
                                                                  These data can be cited as M. E. J. Newman,
                                                                  Phys. Rev. E 74, 036104 (2006). Retrieved from
                                                                  `Mark Newman's website
@@ -243,7 +243,7 @@ Examples
                                                                  Power Grid of the United States. Data compiled
                                                                  by D. Watts and S. Strogatz and made available
                                                                  on the web `here
-                                                                 <http://cdg.columbia.edu/cdg/datasets>`_. Please
+                                                                 <http://cdg.columbia.edu/cdg/datasets>`__. Please
                                                                  cite D. J. Watts and S. H. Strogatz, Nature 393,
                                                                  440-442 (1998). Retrieved from `Mark Newman's
                                                                  website

src/graph_tool/draw/__init__.py

@@ -229,7 +229,7 @@ def fruchterman_reingold_layout(g, weight=None, a=None, r=1., scale=None,
     ----------
     g : :class:`~graph_tool.Graph`
         Graph to be used.
-    weight : :class:`PropertyMap` (optional, default: ``None``)
+    weight : :class:`~graph_tool.PropertyMap` (optional, default: ``None``)
         An edge property map with the respective weights.
     a : float (optional, default: :math:`V`)
         Attracting force between adjacent vertices.
@@ -248,7 +248,7 @@ def fruchterman_reingold_layout(g, weight=None, a=None, r=1., scale=None,
         displacement at each iteration.
     n_iter : int (optional, default: ``100``)
         Total number of iterations.
-    pos : :class:`PropertyMap` (optional, default: ``None``)
+    pos : :class:`~graph_tool.PropertyMap` (optional, default: ``None``)
         Vector vertex property maps where the coordinates should be stored. If
         provided, this will also be used as the initial position of the
         vertices.

src/graph_tool/draw/cairo_draw.py

@@ -579,10 +579,10 @@ def cairo_draw(g, pos, cr, vprops=None, eprops=None, vorder=None, eorder=None,
         If provided, defines the relative order in which the edges are drawn.
     nodesfirst : bool (optional, default: ``False``)
         If ``True``, the vertices are drawn first, otherwise the edges are.
-    vcmap : :class:`matplotlib.colors.Colormap` or tuple (optional, default: :class:`default_cm`)
+    vcmap : :class:`matplotlib.colors.Colormap` or tuple (optional, default: :obj:`~graph_tool.draw.default_cm`)
         Vertex color map. Optionally, this may be a
         (:class:`matplotlib.colors.Colormap`, alpha) tuple.
-    ecmap : :class:`matplotlib.colors.Colormap` or tuple (optional, default: :class:`default_cm`)
+    ecmap : :class:`matplotlib.colors.Colormap` or tuple (optional, default: :obj:`~graph_tool.draw.default_cm`)
         Edge color map. Optionally, this may be a
         (:class:`matplotlib.colors.Colormap`, alpha) tuple.
     loop_angle : float or :class:`~graph_tool.PropertyMap` (optional, default: ``nan``)
@@ -1582,7 +1582,7 @@ def draw_hierarchy(state, pos=None, layout="radial", beta=0.8, node_weight=None,
 
     Parameters
     ----------
-    state : :class:`~graph_tool.community.NestedBlockState`
+    state : :class:`~graph_tool.inference.nested_blockmodel.NestedBlockState`
         Nested block state to be drawn.
     pos : :class:`~graph_tool.PropertyMap` (optional, default: ``None``)
         If supplied, this specifies a vertex property map with the positions of

src/graph_tool/draw/graphviz_draw.py

@@ -224,11 +224,11 @@ def graphviz_draw(g, pos=None, size=(15, 15), pin=False, layout=None,
         Drawing color for edges. If the valued supplied is a property map,
         the values must be scalar types, whose color values are obtained from
         the ``ecmap`` argument.
-    vcmap : :class:`matplotlib.colors.Colormap` (default: :class:`matplotlib.cm.jet`)
+    vcmap : :class:`matplotlib.colors.Colormap` (default: :obj:`matplotlib.cm.jet`)
         Vertex color map.
     vnorm : bool (default: ``True``)
         Normalize vertex color values to the [0,1] range.
-    ecmap : :class:`matplotlib.colors.Colormap` (default: :class:`matplotlib.cm.jet`)
+    ecmap : :class:`matplotlib.colors.Colormap` (default: :obj:`matplotlib.cm.jet`)
         Edge color map.
     enorm : bool (default: ``True``)
         Normalize edge color values to the [0,1] range.

src/graph_tool/inference/__init__.py

@@ -39,8 +39,8 @@ High-level functions
 .. autosummary::
    :nosignatures:
 
-   minimize_blockmodel_dl
-   minimize_nested_blockmodel_dl
+   ~graph_tool.inference.minimize.minimize_blockmodel_dl
+   ~graph_tool.inference.minimize.minimize_nested_blockmodel_dl
 
 State classes
 =============
@@ -48,14 +48,11 @@ State classes
 .. autosummary::
    :nosignatures:
 
-   BlockState
-   OverlapBlockState
-   LayeredBlockState
-   NestedBlockState
-   UncertainBlockState
-   MeasuredBlockState
-   MixedMeasuredBlockState
-   TemperingState
+   ~graph_tool.inference.blockmodel.BlockState
+   ~graph_tool.inference.overlap_blockmodel.OverlapBlockState
+   ~graph_tool.inference.layered_blockmodel.LayeredBlockState
+   ~graph_tool.inference.nested_blockmodel.NestedBlockState
+   ~graph_tool.inference.mcmc.TemperingState
 
 Sampling and minimization
 =========================
@@ -63,13 +60,13 @@ Sampling and minimization
 .. autosummary::
    :nosignatures:
 
-   mcmc_equilibrate
-   mcmc_anneal
-   mcmc_multilevel
-   multicanonical_equilibrate
-   MulticanonicalState
-   bisection_minimize
-   hierarchy_minimize
+   ~graph_tool.inference.mcmc.mcmc_equilibrate
+   ~graph_tool.inference.mcmc.mcmc_anneal
+   ~graph_tool.inference.mcmc.mcmc_multilevel
+   ~graph_tool.inference.mcmc.multicanonical_equilibrate
+   ~graph_tool.inference.mcmc.MulticanonicalState
+   ~graph_tool.inference.bisection.bisection_minimize
+   ~graph_tool.inference.nested_blockmodel.hierarchy_minimize
 
 Auxiliary functions
 ===================
@@ -77,12 +74,12 @@ Auxiliary functions
 .. autosummary::
    :nosignatures:
 
-   model_entropy
-   mf_entropy
-   bethe_entropy
-   microstate_entropy
-   half_edge_graph
-   get_block_edge_gradient
+   ~graph_tool.inference.blockmodel.model_entropy
+   ~graph_tool.inference.blockmodel.mf_entropy
+   ~graph_tool.inference.blockmodel.bethe_entropy
+   ~graph_tool.inference.blockmodel.microstate_entropy
+   ~graph_tool.inference.overlap_blockmodel.half_edge_graph
+   ~graph_tool.inference.overlap_blockmodel.get_block_edge_gradient
 
 Auxiliary classes
 =================
@@ -90,9 +87,22 @@ Auxiliary classes
 .. autosummary::
    :nosignatures:
 
-   PartitionHist
-   BlockPairHist
-   UncertainBaseState
+   ~graph_tool.inference.blockmodel.PartitionHist
+   ~graph_tool.inference.blockmodel.BlockPairHist
+
+Nonparametric network reconstruction
+++++++++++++++++++++++++++++++++++++
+
+State classes
+=============
+
+.. autosummary::
+   :nosignatures:
+
+   ~graph_tool.inference.uncertain_blockmodel.MeasuredBlockState
+   ~graph_tool.inference.uncertain_blockmodel.MixedMeasuredBlockState
+   ~graph_tool.inference.uncertain_blockmodel.UncertainBlockState
+   ~graph_tool.inference.uncertain_blockmodel.UncertainBaseState
 
 Semiparametric stochastic block model inference
 +++++++++++++++++++++++++++++++++++++++++++++++
@@ -103,7 +113,7 @@ State classes
 .. autosummary::
    :nosignatures:
 
-   EMBlockState
+   ~graph_tool.inference.blockmodel_em.EMBlockState
 
 Expectation-maximization Inference
 ==================================
@@ -111,7 +121,7 @@ Expectation-maximization Inference
 .. autosummary::
    :nosignatures:
 
-   em_infer
+   ~graph_tool.inference.blockmodel_em.em_infer
 
 Large-scale descriptors
 +++++++++++++++++++++++
@@ -119,7 +129,7 @@ Large-scale descriptors
 .. autosummary::
    :nosignatures:
 
-   modularity
+   ~graph_tool.inference.modularity.modularity
 
 Contents
 ++++++++

src/graph_tool/inference/bisection.py

@@ -94,13 +94,13 @@ def bisection_minimize(init_states, random_bisection=False,
 
     Parameters
     ----------
-    init_states : Any state class (e.g. :class:`~graph_tool.inference.BlockState`)
+    init_states : Any state class (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         List with two or more states that will be used to bracket the search.
     random_bisection : ``bool`` (optional, default: ``False``)
         If ``True``, the bisection will be done randomly in the interval,
         instead of using the golden rule.
     mcmc_multilevel_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_multilevel`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_multilevel`.
     verbose : ``bool`` or ``tuple`` (optional, default: ``False``)
         If ``True``, progress information will be shown. Optionally, this
         accepts arguments of the type ``tuple`` of the form ``(level, prefix)``
@@ -110,15 +110,16 @@ def bisection_minimize(init_states, random_bisection=False,
 
     Returns
     -------
-    min_state : Any state class (e.g. :class:`~graph_tool.inference.BlockState`)
+    min_state : Any state class (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         State with minimal entropy in the interval.
 
     Notes
     -----
 
-    This function calls :func:`~graph_tool.inference.mcmc_multilevel` to reduce
-    the order of a given state, and uses the value of ``state.entropy(**args)``
-    for the minimization, with ``args`` obtained from ``mcmc_multilevel_args``.
+    This function calls :func:`~graph_tool.inference.mcmc.mcmc_multilevel` to
+    reduce the order of a given state, and uses the value of
+    ``state.entropy(**args)`` for the minimization, with ``args`` obtained from
+    ``mcmc_multilevel_args``.
 
     References
     ----------
@@ -129,6 +130,7 @@ def bisection_minimize(init_states, random_bisection=False,
        greedy heuristic for the inference of stochastic block models", Phys.
        Rev. E 89, 012804 (2014), :doi:`10.1103/PhysRevE.89.012804`,
        :arxiv:`1310.4378`
+
     """
 
     b_cache = {}

src/graph_tool/inference/blockmodel_em.py

@@ -50,7 +50,7 @@ class EMBlockState(object):
         Graph to be modelled.
     B : ``int``
         Number of blocks (or vertex groups).
-    init_state : :class:`~graph_tool.inference.BlockState` (optional, default: ``None``)
+    init_state : :class:`~graph_tool.inference.blockmodel.BlockState` (optional, default: ``None``)
         Optional block state used for initialization.
 
     Notes
@@ -227,7 +227,7 @@ def em_infer(state, max_iter=1000, max_e_iter=1, epsilon=1e-3,
     Parameters
     ----------
     state : model state
-        State object, e.g. of type :class:`graph_tool.inference.EMBlockState`.
+        State object, e.g. of type :class:`graph_tool.inference.blockmodel_em.EMBlockState`.
     max_iter : ``int`` (optional, default: ``1000``)
         Maximum number of iterations.
     max_e_iter : ``int`` (optional, default: ``1``)

src/graph_tool/inference/layered_blockmodel.py

@@ -67,7 +67,7 @@ class LayeredBlockState(OverlapBlockState, BlockState):
         ``"discrete-poisson"`` or ``"discrete-binomial"``.
     rec_params : list of ``dict`` (optional, default: ``[]``)
         Model hyperparameters for edge covariates. This should a list of
-        ``dict`` instances. See :class:`~graph_tool.inference.BlockState` for
+        ``dict`` instances. See :class:`~graph_tool.inference.blockmodel.BlockState` for
         more details.
     eweight : :class:`~graph_tool.PropertyMap` (optional, default: ``None``)
         Edge multiplicities (for multigraphs or block graphs).
@@ -554,9 +554,10 @@ class LayeredBlockState(OverlapBlockState, BlockState):
 
     def get_block_state(self, b=None, vweight=False, deg_corr=False,
                         overlap=False, layers=None, **kwargs):
-        r"""Returns a :class:`~graph_tool.inference.LayeredBlockState`` corresponding
-        to the block graph. The parameters have the same meaning as the in the
-        constructor."""
+        r"""Returns a :class:`~graph_tool.inference.layered_blockmodel.LayeredBlockState`
+        corresponding to the block graph. The parameters have the same meaning
+        as the in the constructor.
+        """
 
 
         copy_bg = kwargs.pop("copy_bg", True)
@@ -802,7 +803,7 @@ class LayeredBlockState(OverlapBlockState, BlockState):
                 **kwargs):
         r"""Calculate the entropy associated with the current block partition. The
         meaning of the parameters are the same as in
-        :meth:`graph_tool.inference.BlockState.entropy`.
+        :meth:`graph_tool.inference.blockmodel.BlockState.entropy`.
         """
 
         if _bm_test() and kwargs.get("test", True):
@@ -837,7 +838,7 @@ class LayeredBlockState(OverlapBlockState, BlockState):
         return u
 
     def get_edges_prob(self, missing, spurious=[], entropy_args={}):
-        """Compute the joint log-probability of the missing and spurious edges given by
+        r"""Compute the joint log-probability of the missing and spurious edges given by
         ``missing`` and ``spurious`` (a list of ``(source, target, layer)``
         tuples, or :meth:`~graph_tool.Edge` instances), together with the
         observed edges.
@@ -852,7 +853,7 @@ class LayeredBlockState(OverlapBlockState, BlockState):
         (with missing edges added and spurious edges deleted).
 
         The values in ``entropy_args`` are passed to
-        :meth:`graph_tool.BlockState.entropy()` to calculate the
+        :meth:`graph_tool.inference.blockmodel.BlockState.entropy()` to calculate the
         log-probability.
         """
 
@@ -1001,7 +1002,7 @@ class LayeredBlockState(OverlapBlockState, BlockState):
         network partitions. If ``bundled == True`` and the state is an
         overlapping one, the half-edges incident of the same node that belong to
         the same group are moved together. All remaining parameters are passed
-        to :meth:`graph_tool.inference.BlockState.mcmc_sweep`."""
+        to :meth:`graph_tool.inference.blockmodel.BlockState.mcmc_sweep`."""
 
         self.__bundled = bundled
         return BlockState.mcmc_sweep(self, **kwargs)
@@ -1108,8 +1109,8 @@ class LayeredBlockState(OverlapBlockState, BlockState):
     def shrink(self, B, **kwargs):
         """Reduces the order of current state by progressively merging groups, until
         only ``B`` are left. All remaining keyword arguments are passed to
-        :meth:`graph_tool.inference.BlockState.shrink` or
-        :meth:`graph_tool.inference.OverlapBlockState.shrink`, as appropriate.
+        :meth:`graph_tool.inference.blockmodel.BlockState.shrink` or
+        :meth:`graph_tool.inference.overlap_blockmodel.OverlapBlockState.shrink`, as appropriate.
 
         This function leaves the current state untouched and returns instead a
         copy with the new partition.
@@ -1122,8 +1123,8 @@ class LayeredBlockState(OverlapBlockState, BlockState):
 
     def draw(self, **kwargs):
         """Convenience function to draw the current state. All keyword arguments are
-        passed to :meth:`graph_tool.inference.BlockState.draw` or
-        :meth:`graph_tool.inference.OverlapBlockState.draw`, as appropriate.
+        passed to :meth:`graph_tool.inference.blockmodel.BlockState.draw` or
+        :meth:`graph_tool.inference.overlap_blockmodel.OverlapBlockState.draw`, as appropriate.
         """
 
         self.agg_state.draw(**kwargs)

src/graph_tool/inference/mcmc.py

@@ -37,7 +37,7 @@ def mcmc_equilibrate(state, wait=1000, nbreaks=2, max_niter=numpy.inf,
 
     Parameters
     ----------
-    state : Any state class (e.g. :class:`~graph_tool.inference.BlockState`)
+    state : Any state class (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         Initial state. This state will be modified during the algorithm.
     wait : ``int`` (optional, default: ``1000``)
         Number of iterations to wait for a record-breaking event.
@@ -84,8 +84,8 @@ def mcmc_equilibrate(state, wait=1000, nbreaks=2, max_niter=numpy.inf,
     event.
 
     This function calls ``state.mcmc_sweep`` (or ``state.gibbs_sweep``) at each
-    iteration (e.g. :meth:`graph_tool.inference.BlockState.mcmc_sweep` and
-    :meth:`graph_tool.inference.BlockState.gibbs_sweep`), and keeps track of
+    iteration (e.g. :meth:`graph_tool.inference.blockmodel.BlockState.mcmc_sweep` and
+    :meth:`graph_tool.inference.blockmodel.BlockState.gibbs_sweep`), and keeps track of
     the value of ``state.entropy(**args)`` with ``args`` corresponding to
     ``mcmc_args["entropy_args"]``.
 
@@ -187,7 +187,7 @@ def mcmc_anneal(state, beta_range=(1., 10.), niter=100, history=False,
 
     Parameters
     ----------
-    state : Any state class (e.g. :class:`~graph_tool.inference.BlockState`)
+    state : Any state class (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         Initial state. This state will be modified during the algorithm.
     beta_range : ``tuple`` of two floats (optional, default: ``(1., 10.)``)
         Inverse temperature range.
@@ -197,7 +197,7 @@ def mcmc_anneal(state, beta_range=(1., 10.), niter=100, history=False,
     history : ``bool`` (optional, default: ``False``)
         If ``True``, a list of tuples of the form ``(nattempts, nmoves, beta, entropy)``
     mcmc_equilibrate_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_equilibrate`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_equilibrate`.
     verbose : ``bool`` or ``tuple`` (optional, default: ``False``)
         If ``True``, progress information will be shown. Optionally, this
         accepts arguments of the type ``tuple`` of the form ``(level, prefix)``
@@ -214,7 +214,7 @@ def mcmc_anneal(state, beta_range=(1., 10.), niter=100, history=False,
     iterations.
 
     At each iteration, the function
-    :func:`~graph_tool.inference.mcmc_equilibrate` is called with the current
+    :func:`~graph_tool.inference.mcmc.mcmc_equilibrate` is called with the current
     value of `beta` (via the ``mcmc_args`` parameter).
 
     Returns
@@ -283,7 +283,7 @@ def mcmc_multilevel(state, B, r=2, b_cache=None, anneal=False,
 
     Parameters
     ----------
-    state : Any state class (e.g. :class:`~graph_tool.inference.BlockState`)
+    state : Any state class (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         Initial state. This state will **not** be modified during the algorithm.
     B : ``int``
         Desired model order (i.e. number of groups).
@@ -296,15 +296,15 @@ def mcmc_multilevel(state, B, r=2, b_cache=None, anneal=False,
         order. This dictionary will be modified during the algorithm.
     anneal : ``bool`` (optional, default: ``False``)
         If ``True``, the equilibration steps will use simulated annealing, by
-        calling :func:`~graph_tool.inference.mcmc_anneal`, instead of
-        :func:`~graph_tool.inference.mcmc_equilibrate`.
+        calling :func:`~graph_tool.inference.mcmc.mcmc_anneal`, instead of
+        :func:`~graph_tool.inference.mcmc.mcmc_equilibrate`.
     mcmc_equilibrate_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_equilibrate`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_equilibrate`.
     mcmc_anneal_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_anneal`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_anneal`.
     shrink_args : ``dict`` (optional, default: ``{}``)
         Arguments to be passed to ``state.shrink``
-        (e.g. :meth:`graph_tool.inference.BlockState.shrink`).
+        (e.g. :meth:`graph_tool.inference.blockmodel.BlockState.shrink`).
     verbose : ``bool`` or ``tuple`` (optional, default: ``False``)
         If ``True``, progress information will be shown. Optionally, this
         accepts arguments of the type ``tuple`` of the form ``(level, prefix)``
@@ -317,7 +317,7 @@ def mcmc_multilevel(state, B, r=2, b_cache=None, anneal=False,
 
     This algorithm alternates between equilibrating the MCMC state and reducing
     the state order (via calls to ``state.shrink``,
-    e.g. :meth:`graph_tool.inference.BlockState.shrink`).
+    e.g. :meth:`graph_tool.inference.blockmodel.BlockState.shrink`).
 
     This greatly reduces the changes of getting trapped in metastable states if
     the starting point if far away from equilibrium, as discussed in
@@ -386,7 +386,7 @@ def mcmc_multilevel(state, B, r=2, b_cache=None, anneal=False,
 
 class MulticanonicalState(object):
     r"""The density of states of a multicanonical Monte Carlo algorithm. It is used
-    by :func:`graph_tool.inference.multicanonical_equilibrate`.
+    by :func:`graph_tool.inference.mcmc.multicanonical_equilibrate`.
 
     Parameters
     ----------
@@ -515,9 +515,9 @@ def multicanonical_equilibrate(state, m_state, f_range=(1., 1e-6), r=2,
 
     Parameters
     ----------
-    state : Any state class (e.g. :class:`~graph_tool.inference.BlockState`)
+    state : Any state class (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         Initial state. This state will be modified during the algorithm.
-    m_state :  :class:`~graph_tool.inference.MulticanonicalState`
+    m_state :  :class:`~graph_tool.inference.mcmc.MulticanonicalState`
         Initial multicanonical state, where the state density will be stored.
     f_range : ``tuple`` of two floats (optional, default: ``(1., 1e-6)``)
         Range of density updates.
@@ -534,7 +534,7 @@ def multicanonical_equilibrate(state, m_state, f_range=(1., 1e-6), r=2,
         function must accept the current ``state`` and ``m_state`` as arguments.
     multicanonical_args : ``dict`` (optional, default: ``{}``)
         Arguments to be passed to ``state.multicanonical_sweep`` (e.g.
-        :meth:`graph_tool.inference.BlockState.multicanonical_sweep`).
+        :meth:`graph_tool.inference.blockmodel.BlockState.multicanonical_sweep`).
     verbose : ``bool`` or ``tuple`` (optional, default: ``False``)
         If ``True``, progress information will be shown. Optionally, this
         accepts arguments of the type ``tuple`` of the form ``(level, prefix)``
@@ -593,11 +593,11 @@ class TemperingState(object):
     inverse-temperature values to implement `parallel tempering MCMC
     <https://en.wikipedia.org/wiki/Parallel_tempering>`_.
 
-    This is meant to be used with :func:`~graph-tool.inference.mcmc_equilibrate`.
+    This is meant to be used with :func:`~graph_tool.inference.mcmc.mcmc_equilibrate`.
 
     Parameters
     ----------
-    states : list of state objects (e.g. :class:`~graph_tool.inference.BlockState`)
+    states : list of state objects (e.g. :class:`~graph_tool.inference.blockmodel.BlockState`)
         Initial parallel states.
     betas : list of floats
         Inverse temperature values.

src/graph_tool/inference/minimize.py

@@ -119,7 +119,8 @@ def minimize_blockmodel_dl(g, B_min=None, B_max=None, b_min=None, b_max=None,
                            mcmc_args={}, anneal_args={},
                            mcmc_equilibrate_args={}, shrink_args={},
                            mcmc_multilevel_args={}, verbose=False):
-    """Fit the stochastic block model.
+    """Fit the stochastic block model, by minimizing its description length using an
+    agglomerative heuristic.
 
     Parameters
     ----------
@@ -144,23 +145,23 @@ def minimize_blockmodel_dl(g, B_min=None, B_max=None, b_min=None, b_max=None,
         If ``True``, the layered version of the model will be used.
     state_args : ``dict`` (optional, default: ``{}``)
         Arguments to be passed to appropriate state constructor (e.g.
-        :class:`~graph_tool.inference.BlockState`,
-        :class:`~graph_tool.inference.OverlapBlockState` or
-        :class:`~graph_tool.inference.LayeredBlockState`)
+        :class:`~graph_tool.inference.blockmodel.BlockState`,
+        :class:`~graph_tool.inference.overlap_blockmodel.OverlapBlockState` or
+        :class:`~graph_tool.inference.layered_blockmodel.LayeredBlockState`)
     bisection_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.bisection_minimize`.
+        Arguments to be passed to :func:`~graph_tool.inference.bisection.bisection_minimize`.
     mcmc_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :meth:`graph_tool.inference.BlockState.mcmc_sweep`,
-        :meth:`graph_tool.inference.OverlapBlockState.mcmc_sweep` or
-        :meth:`graph_tool.inference.LayeredBlockState.mcmc_sweep`.
+        Arguments to be passed to :meth:`graph_tool.inference.blockmodel.BlockState.mcmc_sweep`,
+        :meth:`graph_tool.inference.overlap_blockmodel.OverlapBlockState.mcmc_sweep` or
+        :meth:`graph_tool.inference.layered_blockmodel.LayeredBlockState.mcmc_sweep`.
     mcmc_equilibrate_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_equilibrate`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_equilibrate`.
     shrink_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :meth:`graph_tool.inference.BlockState.shrink`,
-        :meth:`graph_tool.inference.OverlapBlockState.shrink` or
-        :meth:`graph_tool.inference.LayeredBlockState.shrink`.
+        Arguments to be passed to :meth:`graph_tool.inference.blockmodel.BlockState.shrink`,
+        :meth:`graph_tool.inference.overlap_blockmodel.OverlapBlockState.shrink` or
+        :meth:`graph_tool.inference.layered_blockmodel.LayeredBlockState.shrink`.
     mcmc_multilevel_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_multilevel`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_multilevel`.
     verbose : ``bool`` or ``tuple`` (optional, default: ``False``)
         If ``True``, progress information will be shown. Optionally, this
         accepts arguments of the type ``tuple`` of the form ``(level, prefix)``
@@ -170,14 +171,14 @@ def minimize_blockmodel_dl(g, B_min=None, B_max=None, b_min=None, b_max=None,
 
     Returns
     -------
-    min_state : :class:`~graph_tool.inference.BlockState` or  :class:`~graph_tool.inference.OverlapBlockState` or  :class:`~graph_tool.inference.LayeredBlockState`
+    min_state : :class:`~graph_tool.inference.blockmodel.BlockState` or  :class:`~graph_tool.inference.overlap_blockmodel.OverlapBlockState` or  :class:`~graph_tool.inference.layered_blockmodel.LayeredBlockState`
         State with minimal description length.
 
     Notes
     -----
 
     This function is a convenience wrapper around
-    :func:`~graph_tool.inference.bisection_minimize`.
+    :func:`~graph_tool.inference.bisection.bisection_minimize`.
 
     See [peixoto-efficient-2014]_ for details on the algorithm.
 
@@ -319,7 +320,8 @@ def minimize_nested_blockmodel_dl(g, B_min=None, B_max=None, b_min=None,
                                   mcmc_args={}, anneal_args={},
                                   mcmc_equilibrate_args={}, shrink_args={},
                                   mcmc_multilevel_args={}, verbose=False):
-    """Fit the nested stochastic block model.
+    """Fit the nested stochastic block model, by minimizing its description length
+    using an agglomerative heuristic.
 
     Parameters
     ----------
@@ -347,26 +349,26 @@ def minimize_nested_blockmodel_dl(g, B_min=None, B_max=None, b_min=None,
     layers : ``bool`` (optional, default: ``False``)
         If ``True``, the layered version of the model will be used.
     hierarchy_minimize_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.hierarchy_minimize`.
+        Arguments to be passed to :func:`~graph_tool.inference.nested_blockmodel.hierarchy_minimize`.
     state_args : ``dict`` (optional, default: ``{}``)
         Arguments to be passed to appropriate state constructor (e.g.
-        :class:`~graph_tool.inference.BlockState`,
-        :class:`~graph_tool.inference.OverlapBlockState` or
-        :class:`~graph_tool.inference.LayeredBlockState`)
+        :class:`~graph_tool.inference.blockmodel.BlockState`,
+        :class:`~graph_tool.inference.overlap_blockmodel.OverlapBlockState` or
+        :class:`~graph_tool.inference.layered_blockmodel.LayeredBlockState`)
     bisection_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.bisection_minimize`.
+        Arguments to be passed to :func:`~graph_tool.inference.bisection.bisection_minimize`.
     mcmc_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :meth:`graph_tool.inference.BlockState.mcmc_sweep`,
-        :meth:`graph_tool.inference.OverlapBlockState.mcmc_sweep` or
-        :meth:`graph_tool.inference.LayeredBlockState.mcmc_sweep`.
+        Arguments to be passed to :meth:`graph_tool.inference.blockmodel.BlockState.mcmc_sweep`,
+        :meth:`graph_tool.inference.overlap_blockmodel.OverlapBlockState.mcmc_sweep` or
+        :meth:`graph_tool.inference.layered_blockmodel.LayeredBlockState.mcmc_sweep`.
     mcmc_equilibrate_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_equilibrate`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_equilibrate`.
     shrink_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :meth:`graph_tool.inference.BlockState.shrink`,
-        :meth:`graph_tool.inference.OverlapBlockState.shrink` or
-        :meth:`graph_tool.inference.LayeredBlockState.shrink`.
+        Arguments to be passed to :meth:`graph_tool.inference.blockmodel.BlockState.shrink`,
+        :meth:`graph_tool.inference.overlap_blockmodel.OverlapBlockState.shrink` or
+        :meth:`graph_tool.inference.layered_blockmodel.LayeredBlockState.shrink`.
     mcmc_multilevel_args : ``dict`` (optional, default: ``{}``)
-        Arguments to be passed to :func:`~graph_tool.inference.mcmc_multilevel`.
+        Arguments to be passed to :func:`~graph_tool.inference.mcmc.mcmc_multilevel`.
     verbose : ``bool`` or ``tuple`` (optional, default: ``False``)
         If ``True``, progress information will be shown. Optionally, this
         accepts arguments of the type ``tuple`` of the form ``(level, prefix)``
@@ -376,14 +378,14 @@ def minimize_nested_blockmodel_dl(g, B_min=None, B_max=None, b_min=None,
 
     Returns
     -------
-    min_state : :class:`~graph_tool.inference.NestedBlockState`
+    min_state : :class:`~graph_tool.inference.nested_blockmodel.NestedBlockState`
         Nested state with minimal description length.
 
     Notes
     -----
 
     This function is a convenience wrapper around
-    :func:`~graph_tool.inference.hierarchy_minimize`.
+    :func:`~graph_tool.inference.nested_blockmodel.hierarchy_minimize`.
 
     See [peixoto-hierarchical-2014]_ for details on the algorithm.
 

src/graph_tool/inference/nested_blockmodel.py

@@ -42,11 +42,11 @@ class NestedBlockState(object):
         Graph to be modeled.