LVBlockState

class graph_tool.inference.LVBlockState(s, g=None, self_loops=True, sigma=1, **kwargs)

Bases: DynamicsBlockStateBase

Base state for network reconstruction based on dynamical or behavioral data, using the stochastic block model as a prior. This class is not meant to be instantiated directly, only indirectly via one of its subclasses. Nevertheless, its paramteres are inherited, and are documented as follows.

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.

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> or vector<double>, depending on wether the model has discrete or continuous state values. 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.

gGraph (optional, default: None)

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

directedboolean or None (optional, default: None)

If True, the inferred graph will be directed, or if False it will be undirected. If this option is None, the directionality will be the same as the parameter g, if it is provided, otherwise directed = False will be assumed.

tlist of VertexPropertyMap or VertexPropertyMap (optional, default: [])

If nonempty, this allows for a compressed representation of the time-series parameter s, corresponding only to points in time where the state of each node changes. Each entry in this list must be a VertexPropertyMap with type vector<int> containing the points in time where the state of each node change. The corresponding state of the nodes at these times are given by parameter s. If a single property map is given, then a single time series is assumed.

activendarray of shape (N,M) or list of VertexPropertyMap or VertexPropertyMap (optional, default: None)

If provided, this should contain binary valies specifing wether nodes are “active” or not at specific times/samples. An “active” node contributes normally to the likelihood, while an inactive one is removed from the likelihood computation, with its value being replaced by a standard “inactive” state (the value of s for that node/sample is ignored).

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>, with values interpreted in the same way as above. If a single property map is given, then a single time series is assumed.

xEdgePropertyMap or float (optional, default: 1.)

Initial value of the edge weights. If a float is given, the edge weights will be assumed to be the same for all edges.

x_rangepair of float``s (optional, default: ``(-np.inf, np.inf))

Determines the allowed range of edge weights.

thetaEdgePropertyMap or float (optional, default: 0.)

Initial value of the node parameters (a.k.a. node bias). If a float is given, the node biases will be assumed to be the same for all edges.

theta_rangepair of float``s (optional, default: ``(-np.inf, np.inf))

Determines the allowed range of the node parameters.

xdeltafloat (optional, default: 1e-8)

Initial value for the edge weight precision parameter.

xdelta_minfloat (optional, default: 1e-8)

Minimal value for the edge weight precision parameter.

tdeltafloat (optional, default: 1e-8)

Initial value for the node bias precision parameter.

tdelta_minfloat (optional, default: 1e-8)

Minimal value for the node bias precision parameter.

disable_xdistboolean (optional, default: False)

If True the, quantization of the edge weights will be turned off, and \(L_1\) regularization will be used instead.

disable_tdistboolean (optional, default: False)

If True the, quantization of the node parameters will be turned off, and \(L_1\) regularization will be used instead.

nestedboolean (optional, default: True)

If True, a NestedBlockState will be used, otherwise BlockState.

state_argsdict (optional, default: {})

Arguments to be passed to NestedBlockState or BlockState.

bstateNestedBlockState or BlockState (optional, default: None)

If passed, this will be used to initialize the block state directly.

self_loopsbool (optional, default: False)

If True, it is assumed that the inferred graph can contain self-loops.

max_mint (optional, default: 1 << 16)

Maximum latent edge multiplicity allowed.

entropy_argsdict (optional, default: {})

Override default arguments for entropy() method and releated operations.

Methods

add_edge(u, v, x[, dm])	Add edge \((u, v)\) with multiplicity dm and weight x.
bisect_t(v[, entropy_args, bisect_args, fb, ...])	Perform a bisection search to find the best bias 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, 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 LVState 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()	Return histogram of node categories.
get_tvals()	Return latent node categories.
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, niter, k, keep_elist, ...])	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_t(v[, beta, entropy_args, bisect_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)	Set node bias precision parameter.
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([beta, niter, step, pold, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection MCMC to sample the precision parameter of the node categories.
theta_mcmc_sweep([beta, niter, pold, pnew, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection sampling MCMC to sample node parameters.
theta_multiflip_mcmc_sweep([beta, niter, ...])	Perform sweeps of a Metropolis-Hastings acceptance-rejection merge-split MCMC to sample discrete node value categories.
tvals_sweep([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)	update node \((u, v)\) with value nt.
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[, entropy_args])	Return the difference in description length if node v would take a new value nt.
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, entropy_args={}, bisect_args={}, fb=False, ret_sampler=False)

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

Parameters:

vint or Vertex

Vertex to consider.

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)

Collect marginal inferred network during MCMC runs.

Parameters:

gGraph (optional, default: None)

Previous marginal graph.

Returns:

gGraph

New marginal graph, with internal edge EdgePropertyMap "eprob", "x", and "xdev" containing the marginal probabilities, mean weight, and weight standard deviation, respectively, for each edge, and VertexPropertyMap "t" and "tdev", for the mean and standard deviation, respectively, for the node biases.

Notes

The posterior marginal probability of an edge \((i,j)\) is defined as

\[\pi_{ij} = \sum_{\boldsymbol x}{\boldsymbol 1}_{x_{ij}>0}P(\boldsymbol x|\boldsymbol D)\]

where \(P(\boldsymbol x|\boldsymbol D)\) is the posterior probability of the edge weights \(\boldsymbol x\) given the data. Likewise, the marginal mean \(\left<x_{ij}\right>\) and standard deviation \(\sigma_{ij}\) for the edge weights are given by

\[\begin{split}\begin{aligned} \left<x_{ij}\right> &= \sum_{\boldsymbol x}x_{ij}P(\boldsymbol x|\boldsymbol D)\\ \sigma_{ij}^2 &= \sum_{\boldsymbol x}(x_{ij} - \left<x_{ij}\right>)^2 P(\boldsymbol x|\boldsymbol D). \end{aligned}\end{split}\]

The mean and standard deviation for the node biases are entirely analogous.

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 "w" and "wcount", containing the edge multiplicities and their respective 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, 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, 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.

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.

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, tl1=1, 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.

tdistboolean (optional, default: True)

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

tdist_uniformboolean (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.

tl1float (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) = \frac{\prod_{k}m_{k}!\times \mathrm{e}^{-\lambda_x \sum_k |z_k|}(\mathrm{e}^{\lambda\Delta} - 1)^{K}} {E!{E-1 \choose K-1}2^{K}\max(E,1)}\]

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

\[P(\boldsymbol\theta|\lambda_{\theta},\Delta) =\frac{\prod_{k}n_{k}!\times \mathrm{e}^{-\lambda \sum_k |u_k|} \sinh(\lambda_{\theta}\Delta)^{K_{\theta}-\mathbb{1}_{0\in\boldsymbol u}} (1-\mathrm{e}^{-\lambda_{\theta}\Delta})^{\mathbb{1}_{0\in\boldsymbol u}}} {N!{N-1 \choose K_{\theta}-1}N},\]

is the node parameter quantized distribution. For more details see [peixoto-network-2024].

References

[peixoto-network-2024]

Tiago P. Peixoto, “Network reconstruction via the minimum description length principle”, arXiv: 2405.01015

[peixoto-scalable-2024]

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

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

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

Return histogram of node categories.

get_tvals()

Return latent node categories.

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, niter=1, k=1, keep_elist=False, edge=True, edge_swap=True, edge_multiflip=True, theta=True, theta_multiflip=True, sbm=True, xvals=True, tvals=True, verbose=False, elist_args={}, edge_mcmc_args={}, edge_swap_mcmc_args={}, edge_multiflip_mcmc_args={}, xvals_mcmc_args={}, theta_mcmc_args={}, theta_multiflip_mcmc_args={}, tvals_mcmc_args={}, sbm_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 (optiona, 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).

edgeboolean (optiona, default: True)

Whether to call edge_mcmc_sweep().

edge_mcmc_argsdict (optiona, default: {})

Paramters to pass to call edge_mcmc_sweep().

edge_swapboolean (optiona, default: True)

Whether to call swap_mcmc_sweep().

edge_mcmc_argsdict (optiona, default: {})

Paramters to pass to call swap_mcmc_sweep().

edge_multiflipboolean (optiona, default: True)

Whether to call edge_multiflip_mcmc_sweep().

edge_multiflip_mcmc_argsdict (optiona, default: {})

Paramters to pass to call edge_multiflip_mcmc_sweep().

thetaboolean (optiona, default: True)

Whether to call theta_mcmc_sweep().

theta_mcmc_argsdict (optiona, default: {})

Paramters to pass to call theta_mcmc_sweep().

theta_multiflipboolean (optiona, default: True)

Whether to call theta_multiflip_mcmc_sweep().

theta_multiflip_mcmc_argsdict (optiona, default: {})

Paramters to pass to call theta_multiflip_mcmc_sweep().

sbmboolean (optiona, default: True)

Whether to call sbm_mcmc_sweep().

sbm_mcmc_argsdict (optiona, default: {})

Paramters to pass to call sbm_mcmc_sweep().

xvalsboolean (optiona, default: True)

Whether to call xvals_sweep().

xvals_mcmc_argsdict (optiona, default: {})

Paramters to pass to call xvals_sweep().

tvalsboolean (optiona, default: True)

Whether to call tvals_sweep().

tvals_mcmc_argsdict (optiona, 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_t(v, beta=1, entropy_args={}, bisect_args={})

Sample a value for node v.

Parameters:

vint or Vertex

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

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={}, 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.

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)

Set node bias precision parameter.

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(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:

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(beta=1.0, niter=1, pold=1, pnew=1, ptu=0.1, bisect_args={}, deterministic=False, sequential=True, parallel=True, verbose=False, entropy_args={}, **kwargs)

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

Parameters:

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_argsdict (optional, default: {})

Parameter for the bisection search use to optimize/sample edge weights. See bisect_x()) 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.

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(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:

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(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:

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)

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

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, entropy_args={})

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

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.