PottsState#

class graph_tool.inference.PottsState(g, f, w=None, theta=None, b=None, **kwargs)[source]#

Bases: MCMCState, MultiflipMCMCState, GibbsMCMCState, DrawBlockState

Sample from a generalized Potts model.

Parameters:

gGraph: Graph to be modelled.
fndarray: \(q\times q\) spin iteraction strengths.
wEdgePropertyMap (optional, default: None): Edge property map with the edge weights. If not supplied, it will be assummed to be unity.
thetaVertexPropertyMap (optional, default: None): Vertex property map of type vector<double> with the node fields. If not supplied, it will be assummed to be zero.
bVertexPropertyMap (optional, default: None): Initial spin labels. If not supplied, a random distribution will be used.

Methods

`copy`(**kwargs)	Copies the state.
`draw`(**kwargs)	Convenience wrapper to `graph_draw()` that draws the state of the graph as colors on the vertices and edges.
`entropy`(**kwargs)	Returns the energy of generalized Potts model.
`get_entropy_args`()	Return the current default values for the parameters of the function `entropy()`, together with other operations that depend on them.
`gibbs_sweep`([beta, niter, entropy_args, ...])	Perform `niter` sweeps of a rejection-free Gibbs MCMC to sample network partitions.
`mcmc_sweep`([beta, c, d, niter, ...])	Perform `niter` sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample network partitions.
`multiflip_mcmc_sweep`([beta, c, psingle, ...])	Perform `niter` sweeps of a Metropolis-Hastings acceptance-rejection MCMC with multiple simultaneous moves (i.e. merges and splits) to sample network partitions.
`reset_entropy_args`()	Reset the current default values for the parameters of the function `entropy()`, together with other operations that depend on them.
`update_entropy_args`(**kwargs)	Update the default values for the parameters of the function `entropy()` from the keyword arguments, in a stateful way, together with other operations that depend on them.

copy(**kwargs)[source]#: Copies the state. The parameters override the state properties, and have the same meaning as in the constructor.

draw(**kwargs)#: Convenience wrapper to graph_draw() that draws the state of the graph as colors on the vertices and edges.

entropy(**kwargs)#

Returns the energy of generalized Potts model.

Warning

The default arguments of this function are overriden by those obtained from get_entropy_args(). To update the defaults in a stateful way, update_entropy_args() should be called.

Notes

The energy of the generalized Potts model is given by

\[H = -\sum_{i<j}w_{ij}A_{ij}f_{b_i,b_j} - \sum_i\theta^{(i)}_{b_i}.\]

get_entropy_args()#: Return the current default values for the parameters of the function entropy(), together with other operations that depend on them.

gibbs_sweep(beta=1.0, niter=1, entropy_args={}, allow_new_group=True, sequential=True, deterministic=False, vertices=None, verbose=False, **kwargs)#

Perform niter sweeps of a rejection-free Gibbs MCMC to sample network partitions.

Parameters:

betafloat (optional, default: 1.): Inverse temperature.
niterint (optional, default: 1): Number of sweeps to perform. During each sweep, a move attempt is made for each node.
entropy_argsdict (optional, default: {}): Entropy arguments, with the same meaning and defaults as in graph_tool.inference.BlockState.entropy().
allow_new_groupbool (optional, default: True): Allow the number of groups to increase and decrease.
sequentialbool (optional, default: True): If sequential == True each vertex move attempt is made sequentially, where vertices are visited in random order. Otherwise the moves are attempted by sampling vertices randomly, so that the same vertex can be moved more than once, before other vertices had the chance to move.
deterministicbool (optional, default: False): If sequential == True and deterministic == True the vertices will be visited in deterministic order.
verticeslist of ints (optional, default: None): If provided, this should be a list of vertices which will be moved. Otherwise, all vertices will.
verbosebool (optional, default: False): If verbose == True, detailed information will be displayed.

Returns:

dSfloat: Entropy difference after the sweeps.
nattemptsint: Number of vertex moves attempted.
nmovesint: Number of vertices moved.

Notes

This algorithm has an \(O(E\times B)\) complexity, where \(B\) is the number of groups, and \(E\) is the number of edges.

mcmc_sweep(beta=1.0, c=0.5, d=0.01, niter=1, entropy_args={}, allow_vacate=True, sequential=True, deterministic=False, vertices=None, verbose=False, **kwargs)#

Perform niter sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample network partitions.

Parameters:

betafloat (optional, default: 1.): Inverse temperature.
cfloat (optional, default: .5): Sampling parameter c for move proposals: For \(c\to 0\) the blocks are sampled according to the local neighborhood of a given node and their block connections; for \(c\to\infty\) the blocks are sampled randomly. Note that only for \(c > 0\) the MCMC is guaranteed to be ergodic.
dfloat (optional, default: .01): Probability of selecting a new (i.e. empty) group for a given move.
niterint (optional, default: 1): Number of sweeps to perform. During each sweep, a move attempt is made for each node.
entropy_argsdict (optional, default: {}): Entropy arguments, with the same meaning and defaults as in graph_tool.inference.BlockState.entropy().
allow_vacatebool (optional, default: True): Allow groups to be vacated.
sequentialbool (optional, default: True): If sequential == True each vertex move attempt is made sequentially, where vertices are visited in random order. Otherwise the moves are attempted by sampling vertices randomly, so that the same vertex can be moved more than once, before other vertices had the chance to move.
deterministicbool (optional, default: False): If sequential == True and deterministic == True the vertices will be visited in deterministic order.
verticeslist of ints (optional, default: None): If provided, this should be a list of vertices which will be moved. Otherwise, all vertices will.
verbosebool (optional, default: False): If verbose == True, detailed information will be displayed.

Returns:

dSfloat: Entropy difference after the sweeps.
nattemptsint: Number of vertex moves attempted.
nmovesint: Number of vertices moved.

Notes

This algorithm has an \(O(E)\) complexity, where \(E\) is the number of edges (independent of the number of groups).

References

[peixoto-efficient-2014]

Tiago P. Peixoto, “Efficient Monte Carlo and greedy heuristic for the inference of stochastic block models”, Phys. Rev. E 89, 012804 (2014), DOI: 10.1103/PhysRevE.89.012804 [sci-hub, @tor], arXiv: 1310.4378

multiflip_mcmc_sweep(beta=1.0, c=0.5, psingle=None, psplit=1, pmerge=1, pmergesplit=1, pmovelabel=0, d=0.01, gibbs_sweeps=10, niter=1, entropy_args={}, accept_stats=None, verbose=False, **kwargs)#

Perform niter sweeps of a Metropolis-Hastings acceptance-rejection MCMC with multiple simultaneous moves (i.e. merges and splits) to sample network partitions.

Parameters:

betafloat (optional, default: 1.): Inverse temperature.
cfloat (optional, default: .5): Sampling parameter c for move proposals: For \(c\to 0\) the blocks are sampled according to the local neighborhood of a given node and their block connections; for \(c\to\infty\) the blocks are sampled randomly. Note that only for \(c > 0\) the MCMC is guaranteed to be ergodic.
psinglefloat (optional, default: None): Relative probability of proposing a single node move. If None, it will be selected as the number of nodes in the graph.
psplitfloat (optional, default: 1): Relative probability of proposing a group split.
pmergefloat (optional, default: 1): Relative probability of proposing a group merge.
pmergesplitfloat (optional, default: 1): Relative probability of proposing a marge-split move.
pmovelabelfloat (optional, default: 0): Relative probability of proposing a group label move.
dfloat (optional, default: 1): Probability of selecting a new (i.e. empty) group for a given single-node move.
gibbs_sweepsint (optional, default: 10): Number of sweeps of Gibbs sampling to be performed (i.e. each node is attempted once per sweep) to refine a split proposal.
niterint (optional, default: 1): Number of sweeps to perform. During each sweep, a move attempt is made for each node, on average.
entropy_argsdict (optional, default: {}): Entropy arguments, with the same meaning and defaults as in graph_tool.inference.BlockState.entropy().
accept_statsdict (optional, default: None): If provided, this dictionary will be updated with the proposal and acceptance counts for each kind of move.
verbosebool (optional, default: False): If verbose == True, detailed information will be displayed.

Returns:

dSfloat: Entropy difference after the sweeps.
nattemptsint: Number of vertex moves attempted.
nmovesint: Number of vertices moved.

Notes

This algorithm has an \(O(E)\) complexity, where \(E\) is the number of edges (independent of the number of groups).

References

[peixoto-merge-split-2020]

Tiago P. Peixoto, “Merge-split Markov chain Monte Carlo for community detection”, Phys. Rev. E 102, 012305 (2020), DOI: 10.1103/PhysRevE.102.012305 [sci-hub, @tor], arXiv: 2003.07070

reset_entropy_args()#: Reset the current default values for the parameters of the function entropy(), together with other operations that depend on them.

update_entropy_args(**kwargs)#

Update the default values for the parameters of the function entropy() from the keyword arguments, in a stateful way, together with other operations that depend on them.

Values updated in this manner are preserved by the copying or pickling of the state.

PottsState

Contents

PottsState#