PottsBlockStateBase

class graph_tool.inference.PottsBlockStateBase(s, f=None, g=None, **kwargs)

Bases: DynamicsBlockStateBase

Base state for network reconstruction based on the generalized Potts model, using the stochastic block model as a prior.

This class is not supposed to be instantiated directly.

Instead one of its specialized subclasses must be used, which have the same signature: PottsGlauberBlockState, PseudoPottsBlockState.

Parameters:

sndarray of shape (N,M) or list of VertexPropertyMap or VertexPropertyMap

Time series or independent samples used for reconstruction.

If the type is ndarray, it should correspond to a (N,M) data matrix with M samples for all N nodes.

The values must correspond to Ising states: -1 or +1

If the parameter g is provided, this can be optionally a list of of VertexPropertyMap objects, where each entry in this list must be a VertexPropertyMap with type vector<int>. If a single property map is given, then a single time series is assumed.

If the parameter t below is given, each property map value for a given node should contain only the states for the same points in time given by that parameter.

fndarray of shape (q,q) (optional, default: identity(q))

Interaction strengths between spin values.

qint (optional, default: f.shape[0])

Number of spins.

gGraph (optional, default: None)

Initial graph state. If not provided, an empty graph will be assumed.

**kwargs(optional)

Remaining parameters to be passed to DynamicsBlockStateBase

References

[ising-model]

https://en.wikipedia.org/wiki/Ising_model

[peixoto-network-2019]

Tiago P. Peixoto, “Network reconstruction and community detection from dynamics”, Phys. Rev. Lett. 123 128301 (2019), DOI: 10.1103/PhysRevLett.123.128301 [sci-hub, @tor], arXiv: 1903.10833

[peixoto-network-2025]

Tiago P. Peixoto, “Network reconstruction via the minimum description length principle”, Phys. Rev. X 15, 011065 (2025) DOI: 10.1103/PhysRevX.15.011065 [sci-hub, @tor], arXiv: 2405.01015

[peixoto-scalable-2024]

Tiago P. Peixoto, “Scalable network reconstruction in subquadratic time”, arXiv: 2401.01404

[peixoto-uncertainty-2025]

Tiago P. Peixoto, “Uncertainty quantification and posterior sampling for network reconstruction” arXiv: 2503.07736

Methods

add_edge(u, v, x[, dm])	Add edge \((u, v)\) with multiplicity dm and weight x.
bisect_t(v[, l, entropy_args, bisect_args, ...])	Perform a bisection search to find the best bias component l value for node v.
bisect_x(u, v[, entropy_args, bisect_args, ...])	Perform a bisection search to find the best weight value for edge \((u, v)\).
clear_candidates()	Clear candidate edges for MCMC.
collect_candidates([u])	Store current edges into the list of candidates for MCMC.
collect_marginal([g])	Collect marginal inferred network during MCMC runs.
collect_marginal_multigraph([g])	Collect marginal latent multigraph during MCMC runs.
copy(**kwargs)	Return a copy of the state.
edge_MI(u, v)	Return the mutual information between nodes \(u\) and \(v\), according to their time-series.
edge_TE(u, v)	Return the transfer entropy between nodes \(u\) and \(v\), according to their time-series.
edge_cov(u, v[, toffset, pearson])	Return the covariance (or Pearson correlation if pearson == True) between nodes \(u\) and \(v\), according to their time-series.
edge_mcmc_sweep([beta, niter, m, k, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample latent edges.
edge_multiflip_mcmc_sweep([beta, niter, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample discrete edge weight categories.
entropy([latent_edges, density, aE, sbm, ...])	Return the description length, i.e. the negative joint log-likelihood.
get_block_state()	Return the underlying block state, which can be either BlockState or NestedBlockState.
get_candidate_edges([k, r, max_rk, epsilon, ...])	Return the \(\lfloor\kappa N\rceil\) best edge candidates according to a stochastic second neighbor search.
get_dyn_state([s])	Return an PottsGlauberState instance corresponding to the inferred model, optionally with initial state given by s.
get_edge_prob(u, v, x[, entropy_args, epsilon])	Return conditional posterior log-probability of edge \((u,v)\).
get_edges_prob(elist[, entropy_args, epsilon])	Return conditional posterior log-probability of an edge list, with shape \((E,2)\).
get_entropy_args()	Return the current default values for the parameters of the function entropy(), together with other operations that depend on them.
get_graph()	Return the current inferred graph.
get_params(params)	Gets the model parameters via the dictionary params.
get_theta()	Return latent node values.
get_thist([l])	Return histogram of node categories for component l.
get_tvals([l])	Return latent node categories for component l.
get_x()	Return latent edge weights.
get_xhist()	Return histogram (i.e. counts) of edge weight categories.
get_xvals()	Return latent edge weight categories.
mcmc_sweep([beta, f, f_mcmc_args])	Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample latent edges and network partitions.
remove_edge(u, v[, dm])	Remove edge \((u, v)\) with multiplicity dm.
reset_entropy_args()	Reset the current default values for the parameters of the function entropy(), together with other operations that depend on them.
sample_f(r, s[, beta, entropy_args, ...])	Sample the entry (r,s) of the iteraction matrix f.
sample_t(v[, l, beta, entropy_args, ...])	Sample a value for node v.
sample_x(u, v[, beta, entropy_args, ...])	Sample a proposed weight value for edge \((u, v)\).
sbm_mcmc_sweep([multiflip])	Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample node partitions.
set_params(params)	Sets the model parameters via the dictionary params.
set_state(g, w)	Set all edge multiplicities via EdgePropertyMap w.
set_tdelta(delta[, l])	Set node bias precision parameter for component l.
set_xdelta(delta)	Set edge weight precision parameter.
swap_mcmc_sweep([beta, niter, preplace, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to swap edge endpoints.
tdelta_mcmc_sweep([l, beta, niter, step, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample the precision parameter of the node categories.
theta_mcmc_sweep([l, beta, niter, pold, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample node parameters.
theta_multiflip_mcmc_sweep([l, beta, niter, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample discrete node value categories.
tvals_sweep([l, beta, niter, min_size, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample the node bias category values, based on a bisection search.
update_edge(u, v, nx)	update edge \((u, v)\) with weight nx.
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.
update_node(v, nt[, l])	update node \((u, v)\) with value nt for component l.
virtual_add_edge(u, v, x[, dm, entropy_args])	Return the difference in description length if edge \((u, v)\) would be added with multiplicity dm and weight x.
virtual_remove_edge(u, v[, dm, entropy_args])	Return the difference in description length if edge \((u, v)\) with multiplicity dm would be removed.
virtual_update_edge(u, v, nx[, entropy_args])	Return the difference in description length if edge \((u, v)\) would take a new weight nx.
virtual_update_node(v, nt[, l, entropy_args])	Return the difference in description length if node v would take a new value nt for component l.
xdelta_mcmc_sweep([beta, niter, step, pold, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample the precision parameter of the edge categories.
xvals_sweep([beta, niter, bisect_args, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample the edge weight category values, based on a bisection search.

add_edge(u, v, x, dm=1)

Add edge \((u, v)\) with multiplicity dm and weight x.

bisect_t(v, l=0, entropy_args={}, bisect_args={}, fb=False, ret_sampler=False)

Perform a bisection search to find the best bias component l value for node v.

Parameters:

vint or Vertex

Vertex to consider.

lint (optional, default: 0)

Component of node parameters to be considered.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

fbboolean (optional, default: False)

Perform a Fibonacci (a.k.a. golden ratio) search among the current node categories, instead of a bisection search among all possible values.

ret_samplerboolean (optional, default: False)

If True, a BisectionSampler object will be returned as well (for debugging purposes).

bisect_x(u, v, entropy_args={}, bisect_args={}, fb=False, ret_sampler=False)

Perform a bisection search to find the best weight value for edge \((u, v)\).

Parameters:

uint or Vertex

Source

vint or Vertex

Target

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search use to optimize/sample edge weights. The recognized parameters and their default values are as follows:

maxiterint (default: 0)

Maximum number of iterations for bisection search (0 means unlimited).

tolfloat (default: 2e-3)

Relative tolerance for bisection search.

ftolfloat (default: 100)

Absolute tolerance used to extend the search range.

nmax_extendint (default: 8)

Maximum number of min/max range extensions.

min_boundfloat (default: -np.inf)

Minimum bound for bisection search.

max_boundfloat (default: np.inf)

Maximum bound for bisection search.

min_initfloat (default: -np.inf)

Iniital minimum bound for bisection search.

max_initfloat (default: np.inf)

Initial maximum bound for bisection search.

reversibleboolean (default: True)

Perform search in a manner that is usable for a reversible Markov chain.

fbboolean (optional, default: False)

Perform a Fibonacci (a.k.a. golden ratio) search among the current edge categories, instead of a bisection search among all possible values.

ret_samplerboolean (optional, default: False)

If True, a BisectionSampler object will be returned as well (for debugging purposes).

clear_candidates()

Clear candidate edges for MCMC.

collect_candidates(u=None)

Store current edges into the list of candidates for MCMC. If Graph u is provided, its edges will be added instead.

collect_marginal(g=None, **kwargs)

Collect marginal inferred network during MCMC runs.

See DynamicsBlockStateBase.collect_marginal() for documentation.

This version in addition also keeps the marginal estimate of the interaction matrix f via an internal graph property map, as well as its standard deviation fdev.

collect_marginal_multigraph(g=None)

Collect marginal latent multigraph during MCMC runs.

Parameters:

gGraph (optional, default: None)

Previous marginal multigraph.

Returns:

gGraph

New marginal graph, with internal edge EdgePropertyMap "wcount", containing the edge multiplicity counts.

Notes

The mean posterior marginal multiplicity distribution of a multi-edge \((i,j)\) is defined as

\[\pi_{ij}(w) = \sum_{\boldsymbol G}\delta_{w,G_{ij}}P(\boldsymbol G|\boldsymbol D)\]

where \(P(\boldsymbol G|\boldsymbol D)\) is the posterior probability of a multigraph \(\boldsymbol G\) given the data.

copy(**kwargs)

Return a copy of the state.

edge_MI(u, v)

Return the mutual information between nodes \(u\) and \(v\), according to their time-series.

edge_TE(u, v)

Return the transfer entropy between nodes \(u\) and \(v\), according to their time-series.

edge_cov(u, v, toffset=True, pearson=False)

Return the covariance (or Pearson correlation if pearson == True) between nodes \(u\) and \(v\), according to their time-series.

edge_mcmc_sweep(beta=1.0, niter=1, m=1, k=1, elist_args={}, keep_elist=False, pold=1, pnew=1, pxu=0.1, pm=1, premove=1, pself=0.1, puniform=1, pedge=1, pnearby=1, d=2, pcandidates=1, bisect_args={}, binary=False, deterministic=False, sequential=True, parallel=True, pseudo=False, verbose=False, entropy_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample latent edges.

If beta is np.inf, the algorithm switches to a greedy heuristic based on iterated nearest-neighbor searches.

Parameters:

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

mdouble (optional, default: 1)

Multiplicative factor to the number of nodes yielding the number of attempted moves at every sweep. This parameter is ignored if beta is np.inf.

kint (optional, default: 1)

\(\kappa\) parameter to be passed to get_candidate_edges(). This parameter is ignored if beta is not np.inf.

elist_argsdict (optional, default: {})

Paramters to pass to call get_candidate_edges(). This parameter is ignored if beta is not np.inf.

keep_elistboolean (optional, default: False)

If True, the candidate edge list from last call will be re-used (if it exists).

poldfloat (optional, default: 1)

Relative probability of proposing a new edge weight from existing categories.

pnewfloat (optional, default: 1)

Relative probability of proposing a new edge weight from a new categories.

pxufloat (optional, default: .1)

Probability of choosing from an existing category uniformly at random (instead of doing a bisection search).

pmfloat (optional, default: 1)

Relative probability of doing edge multiplicity updates.

premovefloat (optional, default: 1)

Relative probability of removing edges.

pselffloat (optional, default: .1)

Relative probability to search for self-loops as candidate node “pairs”.

puniformfloat (optional, default: 1)

Relative probability to search for candidate node pairs uniformly at random.

pedgefloat (optional, default: 1)

Relative probability to search for candidate node pairs among the current edges.

pnearbyfloat (optional, default: 1)

Relative probability to search for candidate node pairs among the neighborhood of current nodes up to distance d.

dint (optional, default: 2)

Maximum distance used to search for candidate node pairs.

pcandidatesfloat (optional, default: 1)

Relative probability to search for candidate node pairs among currently stored list of candidate edges (obtained with collect_candidates()).

bisect_argsdict (optional, default: {})

Parameter for the bisection search use to optimize/sample edge weights. See bisect_x()) for documentation.

binaryboolean (optional, default: False)

If True, the latent graph will be assumed to be a simple graph, otherwise a multigraph.

deterministicboolean (optional, default: False)

If True, the the order of edge updates will be determinisitc, otherwise uniformly at random.

sequentialboolean (optional, default: True)

If True, a sweep will visit every edge candidate once, otherwise individiual updates will be chosen at random.

parallelboolean (optional, default: True)

If True, the updates are performed in parallel, using locks on edges candidate incident on the same node.

pseudoboolean (optional, default: False)

If True, detailed balance will no longer be stricly perserved, in favor of higher parallelism.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

edge_multiflip_mcmc_sweep(beta=1.0, niter=1, pmerge=1, psplit=1, pmergesplit=1, gibbs_sweeps=5, c=0.1, bisect_args={}, accept_stats=None, verbose=False, entropy_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample discrete edge weight categories.

Parameters:

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

pmergefloat (optional, default: 1)

Relative probability of merging two discrete categories.

psplitfloat (optional, default: 1)

Relative probability of splitting two discrete categories.

pmergesplitfloat (optional, default: 1)

Relative probability of simultaneoulsly merging and splitting two discrete categories.

gibbs_sweepsint (optional, default: 5)

Number of Gibbs sweeps performed to achieve a split proposal.

cdouble (optional, default: .1)

Probability of choosing a category uniformly at random to perform a merge, otherwise an adjacent one is chosen.

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

accept_statsdict (optional, default: None)

If provided, the dictionary will be updated with acceptance statistics.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

entropy(latent_edges=True, density=False, aE=1, sbm=True, xdist=True, tdist=[True], xdist_uniform=False, tdist_uniform=[False], xl1=1.0, tl1=[1.0], alpha=1, normal=False, mu=0, sigma=1, active=True, **kwargs)

Return the description length, i.e. the negative joint log-likelihood.

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.

Parameters:

latent_edgesboolean (optional, default: True)

If True, the adjacency term of the description length will be included.

densityboolean (optional, default: False)

If True, a geometric prior for the total number of edges will be included.

aEdouble (optional, default: 1)

If density=True, this will correspond to the expected number of edges according to the geometric prior.

sbmboolean (optional, default: True)

If True, SBM description length will be included.

xdistboolean (optional, default: True)

If True, the quantized edge weight distribution description length will be included.

xdist_uniformboolean (optional, default: False)

If True, a uniform prior for the edge weight distribution will be used.

tdistlist of boolean (optional, default: True)

If True, the quantized node parameter distribution description length will be included.

tdist_uniformlist of boolean (optional, default: False)

If True, a uniform prior for the node parameter distribution will be used.

xl1float (optional, default: 1)

Specifies the \(\lambda\) parameter for \(L_1\) regularization for the edge weights if xdist == False, or the Laplace hyperprior for the discrete categories if xdist == True.

tl1list of float (optional, default: 1)

Specifies the \(\lambda\) parameter for \(L_1\) regularization for the node paraemters if tdist == False, or the Laplace hyperprior for the discrete categories if tdist == True.

normalboolean (optional, default: False)

If True, a normal distribution will be used for the weight priors.

mudouble (optional, default: 0)

If normal == True, this will be the mean of the normal distribution.

sigmadouble (optional, default: 1)

If normal == True, this will be the standard deviation of the normal distribution.

activeboolean (optional, default: True)

If True, the contribution of the active/inactive node states will be added to the description length.

Notes

The “entropy” of the state is the negative log-likelihood of the generative model for the data \(\boldsymbol S\), that includes the inferred weighted adjacency matrix \(\boldsymbol{X}\), the node parameters \(\boldsymbol{\theta}\), and the SBM node partition \(\boldsymbol{b},\) given by

\[\begin{split}\begin{aligned} \Sigma(\boldsymbol{S},\boldsymbol{X},\boldsymbol{\theta}|\lambda_x,\lambda_{\theta},\Delta) = &- \ln P(\boldsymbol{S}|\boldsymbol{X},\boldsymbol{\theta})\\ &- \ln P(\boldsymbol{X}|\boldsymbol{A},\lambda_x, \Delta)\\ &- \ln P(\boldsymbol{A},\boldsymbol{b})\\ &- \ln P(\boldsymbol{\theta}, \lambda_{\theta}, \Delta). \end{aligned}\end{split}\]

The term \(P(\boldsymbol{S}|\boldsymbol{X},\boldsymbol{\theta})\) is given by the particular generative model being used and \(P(\boldsymbol{A},\boldsymbol{b})\) by the SBM. The weight ditribution is given by the quantized model

\[P(\boldsymbol X|\boldsymbol A,\lambda_x,\Delta) = \left[\frac{\left(\prod_{k}m_{k}!\right) \mathrm{e}^{-\lambda (|z_1| + |z_K|)}(\mathrm{e}^{\lambda\Delta} - 1)^{2}(2-\delta_{z_1, z_K})} {4\times E!{E-1 \choose K-1}{{(z_K - z_1)/\Delta - 1 - \mathbb{1}_{z_1z_K < 0}} \choose {K-2}} \left[(z_K - z_1)/\Delta + 1 - \mathbb{1}_{z_1z_K < 0}\right]} \right]^{1-\delta_{E(\boldsymbol A),0}} \prod_{i<j}\delta_{W_{ij},0}^{\delta_{A_{ij}, 0}},\]

where \(\boldsymbol z\) are the \(K\) discrete weight categories, and analogously

\[P(\boldsymbol\theta|\lambda_{\theta},\Delta) = \frac{\left(\prod_{k}n_{k}!\right) \mathrm{e}^{-\lambda (|u_1| + |u_{K_{\theta}}|)}(\mathrm{e}^{\lambda\Delta} - 1)^{2}(2-\delta_{u_1, u_{K_{\theta}}})} {4\times N!{N-1 \choose {K_{\theta}}-1}{{(u_{K_{\theta}} - u_1)/\Delta - 1 - \mathbb{1}_{u_1u_{K_{\theta}} < 0}} \choose {{K_{\theta}}-2}} \left[(u_{K_{\theta}} - u_1)/\Delta + 1 - \mathbb{1}_{u_1u_{K_{\theta}} < 0}\right]}\]

is the node parameter quantized distribution, with \(\boldsymbol u\) being the \(K_\theta\) discrete node parameter catergories. For more details see [peixoto-network-2025] and [peixoto-uncertainty-2025].

References

[peixoto-network-2025]

Tiago P. Peixoto, “Network reconstruction via the minimum description length principle”, Phys. Rev. X 15, 011065 (2025) DOI: 10.1103/PhysRevX.15.011065 [sci-hub, @tor], arXiv: 2405.01015

[peixoto-scalable-2024]

Tiago P. Peixoto, “Scalable network reconstruction in subquadratic time”, arXiv: 2401.01404

[peixoto-uncertainty-2025]

Tiago P. Peixoto, “Uncertainty quantification and posterior sampling for network reconstruction” arXiv: 2503.07736

get_block_state()

Return the underlying block state, which can be either BlockState or NestedBlockState.

get_candidate_edges(k=1, r=1, max_rk='k', epsilon=0.01, c_stop=False, maxiter=0, knn=False, gradient=None, h=0.002, allow_edges=False, include_edges=True, use_hint=True, nrandom=0, keep_all=False, exact=False, return_graph=False, keep_iter=False, entropy_args={}, bisect_args={}, verbose=False)

Return the \(\lfloor\kappa N\rceil\) best edge candidates according to a stochastic second neighbor search.

Parameters:

kfloat (optional, default: 1)

\(\kappa\) parameter.

rfloat (optional, default: 1)

Fraction of second neighbors to consider during the search.

max_rkfloat (optional, default: "k")

Maximum number of second-neighbors to be considered per iteration. A string value "k" means that this will match the number of first neighbors.

epsilonfloat (optional, default: .01)

Convergence criterion.

c_stopboolean (optional, default: False)

If True, the clustering coefficient will be used for the convergence criterion.

maxiterint (optional, default: 0)

Maximum number of iterations allowed (0 means unlimited).

knnboolean (optional, default: False)

If True, the KNN graph will be returned.

gradientboolean (optional, default: None)

Whether to use the gradient to rank edges. If None, it defaults to True if the number of edge categories is empty.

hfloat (optional, default: 1e-8)

Step length used to compute the gradient with central finite difference.

allow_edgesboolean (optional, default: False)

Permit currently present edges to be included in the search.

include_edgesboolean (optional, default: True)

Include currently present edges in the result.

use_hintboolean (optional, default: True)

Use current edges as a hint during the search.

nrandomint (optional, default: 0)

Add this many random entries to the list.

keep_allboolean (optional, default: False)

Keep all entries seen during the search, not only the best.

exactboolean (optional, default: False)

If True an exact quadratic algorithm will be used.

return_graphboolean (optional, default: False)

If True the result will be returned as graph and a property map.

keep_iterboolean (optional, default: False)

If True the results contain the iteration at which an entry has been found.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search use to optimize/sample edge weights. See bisect_x()) for documentation.

Returns:

elist:class:~numpy.ndarray of shape (E, 2)

Best entries.

a:class:~numpy.ndarray

Edge scores.

get_dyn_state(s=None)

Return an PottsGlauberState instance corresponding to the inferred model, optionally with initial state given by s.

get_edge_prob(u, v, x, entropy_args={}, epsilon=1e-08)

Return conditional posterior log-probability of edge \((u,v)\).

get_edges_prob(elist, entropy_args={}, epsilon=1e-08)

Return conditional posterior log-probability of an edge list, with shape \((E,2)\).

get_entropy_args()

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

get_graph()

Return the current inferred graph.

get_params(params)

Gets the model parameters via the dictionary params.

get_theta()

Return latent node values.

get_thist(l=0)

Return histogram of node categories for component l.

get_tvals(l=0)

Return latent node categories for component l.

get_x()

Return latent edge weights.

get_xhist()

Return histogram (i.e. counts) of edge weight categories.

get_xvals()

Return latent edge weight categories.

mcmc_sweep(beta=1, f=1, f_mcmc_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample latent edges and network partitions.

If beta is np.inf, the algorithm switches to a greedy heuristic based on iterated nearest-neighbor searches.

Parameters:

betafloat (optional, default: 1)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

kint (optional, default: 1)

\(\kappa\) parameter to be passed to get_candidate_edges(). This parameter is ignored if beta is not np.inf.

elist_argsdict (optional, default: {})

Paramters to pass to call get_candidate_edges(). This parameter is ignored if beta is not np.inf.

keep_elistboolean (optional, default: False)

If True, the candidate edge list from last call will be re-used (if it exists).

edgefloat (optional, default: 1)

Probability with which edge_mcmc_sweep() will be called.

edge_mcmc_argsdict (optional, default: {})

Paramters to pass to call edge_mcmc_sweep().

edge_swapfloat (optional, default: 1.)

Probability with which swap_mcmc_sweep() will be called.

edge_mcmc_argsdict (optional, default: {})

Paramters to pass to call swap_mcmc_sweep().

edge_multiflipfloat (optional, default: 1 if np.isinf(beta) else .1)

Probability with which edge_multiflip_mcmc_sweep() will be called.

edge_multiflip_mcmc_argsdict (optional, default: {})

Paramters to pass to call edge_multiflip_mcmc_sweep().

thetafloat (optional, default: 1.)

Probability with which theta_mcmc_sweep() will be called.

theta_mcmc_argsdict (optional, default: {})

Paramters to pass to call theta_mcmc_sweep().

theta_multiflipfloat (optional, default: 1.)

Probability with which theta_multiflip_mcmc_sweep() will be called.

theta_multiflip_mcmc_argsdict (optional, default: {})

Paramters to pass to call theta_multiflip_mcmc_sweep().

sbmfloat (optional, default: 1.)

Probability with which sbm_mcmc_sweep() will be called.

sbm_mcmc_argsdict (optional, default: {})

Paramters to pass to call sbm_mcmc_sweep().

xvalsfloat (optional, default: 1.)

Probability with which xvals_sweep() will be called.

xvals_mcmc_argsdict (optional, default: {})

Paramters to pass to call xvals_sweep().

tvalsfloat (optional, default: 1.)

Probability with which tvals_sweep() will be called.

tvals_mcmc_argsdict (optional, default: {})

Paramters to pass to call tvals_sweep().

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

**kwargsdict (optional, default: {})

Remaining keyword parameters will be passed to all individual MCMC functions.

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

remove_edge(u, v, dm=1)

Remove edge \((u, v)\) with multiplicity dm.

reset_entropy_args()

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

sample_f(r, s, beta=1, entropy_args={}, bisect_args={}, verbose=False)

Sample the entry (r,s) of the iteraction matrix f.

Parameters:

rint

First entry.

sint

Second entry.

betafloat (optional, default: 1)

Inverse temperature.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

verbosebool (optional, default: False)

If True, verbose information will be displayed.

Returns:

dSfloat

Entropy difference

sample_t(v, l=0, beta=1, entropy_args={}, bisect_args={}, fb=False, ret_sampler=False)

Sample a value for node v.

Parameters:

vint or Vertex

Node to be considered.

lint (optional, default: 0)

Component of node parameters to be considered.

betafloat (optional, default: 1)

Inverse temperature.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

fbbool (optional, default: False)

If True, the search will be confined to a Fibonacci search over the discrete values given by get_xvals().

ret_samplerboolean (optional, default: False)

If True, a BisectionSampler object will be returned as well (for debugging purposes).

sample_x(u, v, beta=1, entropy_args={}, bisect_args={}, fb=False, ret_sampler=False)

Sample a proposed weight value for edge \((u, v)\).

Parameters:

uint or Vertex

Source node.

vint or Vertex

Target node.

betafloat (optional, default: 1)

Inverse temperature.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

fbbool (optional, default: False)

If True, the search will be confined to a Fibonacci search over the discrete values given by get_xvals().

ret_samplerboolean (optional, default: False)

If True, a BisectionSampler object will be returned as well (for debugging purposes).

sbm_mcmc_sweep(multiflip=True, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample node partitions. The remaining keyword parameters will be passed to mcmc_sweep() or multiflip_mcmc_sweep(), if multiflip=True.

set_params(params)

Sets the model parameters via the dictionary params.

set_state(g, w)

Set all edge multiplicities via EdgePropertyMap w.

set_tdelta(delta, l=0)

Set node bias precision parameter for component l.

set_xdelta(delta)

Set edge weight precision parameter.

swap_mcmc_sweep(beta=1, niter=1, preplace=1, pswap=1, pself=0.1, puniform=1, pedge=1, pnearby=1, d=2, pcandidates=1, parallel=True, verbose=False, entropy_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to swap edge endpoints.

Parameters:

betafloat (optional, default: np.inf)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

preplacefloat (optional, default: 1)

Relative probability of swaping the weights between an edge and another node pair incident on one of the same two endpoints.

pswapfloat (optional, default: 1)

Relative probability of swapping the endpoints of two selected edges or node pairs.

pselffloat (optional, default: .1)

Relative probability to search for self-loops as candidate node “pairs”.

puniformfloat (optional, default: 1)

Relative probability to search for candidate node pairs uniformly at random.

pedgefloat (optional, default: 1)

Relative probability to search for candidate node pairs among the current edges.

pnearbyfloat (optional, default: 1)

Relative probability to search for candidate node pairs among the neighborhood of current nodes up to distance d.

dint (optional, default: 2)

Maximum distance used to search for candidate node pairs.

pcandidatesfloat (optional, default: 1)

Relative probability to search for candidate node pairs among currently stored list of candidate edges (obtained with collect_candidates()).

parallelboolean (optional, default: True)

If True, the updates are performed in parallel, using locks on edges candidate incident on the same node.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

tdelta_mcmc_sweep(l=0, beta=1.0, niter=1, step=10, pold=0.5, ptu=0.1, intra_sweeps=10, verbose=False, entropy_args={}, bisect_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample the precision parameter of the node categories.

Parameters:

lint (optional, default: 0)

Component of node parameters to be considered.

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

stepfloat (optional, default: 10)

Multiplicative move step size.

poldfloat (optional, default: 1)

Relative probability of proposing a new edge weight from existing categories.

ptufloat (optional, default: .1)

Probability of choosing from an existing category uniformly at random (instead of doing a bisection search).

intra_sweepsint (optional, default: 10)

Number of Metropolis-Hastings sweeps performed to achieve a staging proposal.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

theta_mcmc_sweep(l=0, beta=1.0, niter=1, pold=1, pnew=1, ptu=0.1, bisect_args=None, deterministic=False, sequential=True, parallel=True, pseudo=False, verbose=False, entropy_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample node parameters.

Parameters:

lint (optional, default: 0)

Component of node parameters to be considered.

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

poldfloat (optional, default: 1)

Relative probability of proposing a new node value from existing categories.

pnewfloat (optional, default: 1)

Relative probability of proposing a new node value from a new categories.

ptufloat (optional, default: .1)

Probability of choosing from an existing category uniformly at random (instead of doing a bisection search).

bisect_argslist of dict (optional, default: None)

Parameters for the bisection search use to optimize/sample node paramters. See bisect_t()) for documentation.

deterministicboolean (optional, default: False)

If True, the the order of node updates will be determinisitc, otherwise uniformly at random.

sequentialboolean (optional, default: True)

If True, a sweep will visit every node once, otherwise individiual updates will be chosen at random.

parallelboolean (optional, default: True)

If True, the updates are performed in parallel.

pseudoboolean (optional, default: False)

If True, detailed balance will no longer be stricly perserved, in favor of higher parallelism.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

theta_multiflip_mcmc_sweep(l=0, beta=1.0, niter=1, pmerge=1, psplit=1, pmergesplit=1, gibbs_sweeps=5, c=0.1, bisect_args={}, accept_stats=None, verbose=False, entropy_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample discrete node value categories.

Parameters:

lint (optional, default: 0)

Component of node parameters to be considered.

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

pmergefloat (optional, default: 1)

Relative probability of merging two discrete categories.

psplitfloat (optional, default: 1)

Relative probability of splitting two discrete categories.

pmergesplitfloat (optional, default: 1)

Relative probability of simultaneoulsly merging and splitting two discrete categories.

gibbs_sweepsint (optional, default: 5)

Number of Gibbs sweeps performed to achieve a split proposal.

cdouble (optional, default: .1)

Probability of choosing a category uniformly at random to perform a merge, otherwise an adjacent one is chosen.

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

accept_statsdict (optional, default: None)

If provided, the dictionary will be updated with acceptance statistics.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

tvals_sweep(l=0, beta=1.0, niter=100, min_size=1, bisect_args={}, entropy_args={})

Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample the node bias category values, based on a bisection search.

Parameters:

lint (optional, default: 0)

Component of node parameters to be considered.

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 100)

Maximum number of categories to update.

bisect_argsdict (optional, default: {})

Parameter for the bisection search use to optimize/sample node biases. See bisect_x()) for documentation.

min_sizeint (optional, default: 1)

Minimum size of node categories that will be updated.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

update_edge(u, v, nx)

update edge \((u, v)\) with weight nx.

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.

update_node(v, nt, l=0)

update node \((u, v)\) with value nt for component l.

virtual_add_edge(u, v, x, dm=1, entropy_args={})

Return the difference in description length if edge \((u, v)\) would be added with multiplicity dm and weight x.

virtual_remove_edge(u, v, dm=1, entropy_args={})

Return the difference in description length if edge \((u, v)\) with multiplicity dm would be removed.

virtual_update_edge(u, v, nx, entropy_args={})

Return the difference in description length if edge \((u, v)\) would take a new weight nx.

virtual_update_node(v, nt, l=0, entropy_args={})

Return the difference in description length if node v would take a new value nt for component l.

xdelta_mcmc_sweep(beta=1.0, niter=1, step=10, pold=0.5, pxu=0.1, intra_sweeps=10, verbose=False, entropy_args={}, bisect_args={}, **kwargs)

Perform sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample the precision parameter of the edge categories.

Parameters:

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 1)

Number of sweeps.

stepfloat (optional, default: 10)

Multiplicative move step size.

poldfloat (optional, default: 1)

Relative probability of proposing a new edge weight from existing categories.

pxufloat (optional, default: .1)

Probability of choosing from an existing category uniformly at random (instead of doing a bisection search).

intra_sweepsint (optional, default: 10)

Number of Metropolis-Hastings sweeps performed to achieve a staging proposal.

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

bisect_argsdict (optional, default: {})

Parameter for the bisection search. See bisect_x()) for documentation.

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.

xvals_sweep(beta=1.0, niter=100, bisect_args={}, min_size=1, entropy_args={}, verbose=False)

Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample the edge weight category values, based on a bisection search.

Parameters:

betafloat (optional, default: 1.)

Inverse temperature parameter.

niterint (optional, default: 100)

Maximum number of categories to update.

bisect_argsdict (optional, default: {})

Parameter for the bisection search use to optimize/sample edge weights. See bisect_x()) for documentation.

min_sizeint (optional, default: 1)

Minimum size of edge categories that will be updated.

entropy_argsdict (optional, default: {})

Entropy arguments, with the same meaning and defaults as in entropy().

verboseboolean (optional, default: False)

If verbose == True, detailed information will be displayed.

Returns:

dSfloat

Entropy difference after the sweeps.

nmovesint

Number of variables moved.