Skip to content

GitLab

graph-tool
graph-tool
Commit d70825df authored by Tiago Peixoto's avatar Tiago Peixoto
Browse files
Options

Docstring cross-reference cleanup

parent b7f1f2a9
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 359 additions and 271 deletions
doc/conf.py
View file @ d70825df
......@@ -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/demos/inference/inference.rst
View file @ d70825df
This diff is collapsed.
doc/inference.rst
View file @ d70825df
.. 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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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.py
View file @ d70825df
This diff is collapsed.
src/graph_tool/inference/blockmodel_em.py
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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
View file @ d70825df
......@@ -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`.