mixle.stats.graphs.stochastic_block_graph module

Create, estimate, and sample from a stochastic block graph distribution.

This module handles Bernoulli edges conditional on observed or fixed node block assignments. It does not marginalize over unknown block assignments.

class StochasticBlockGraphDistribution(block_probs, block_assignments=None, block_prior=None, directed=False, self_loops=False, include_assignment_prior=False, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Bernoulli stochastic block graph distribution.

The distribution can be used conditionally on observed block assignments, or as a population model that samples assignments from block_prior for new graphs. Exact marginal likelihood over unknown assignments is intentionally not implied.

Parameters:

  • block_probs (Any)

  • block_assignments (Any | None)

  • block_prior (Any | None)

  • directed (bool)

  • self_loops (bool)

  • include_assignment_prior (bool)

  • name (str | None)

  • keys (str | None)

classmethod compute_capabilities()[source]
classmethod from_model(model, block_prior=None, include_assignment_prior=False)[source]
Parameters:

  • model (Any)

  • block_prior (Any | None)

  • include_assignment_prior (bool)

Return type:

StochasticBlockGraphDistribution

to_model()[source]
Return type:

Any

density(x)[source]

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:

x (Any)

Return type:

float

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:

x (Sequence[GraphObservation])

Return type:

ndarray

backend_seq_log_density(x, engine)[source]

Engine-routed block-structured Bernoulli edge log-likelihood.

Each graph’s edges are flattened host-side into per-edge (value, block-pair probability) arrays with a graph-segment id; the Bernoulli terms and the segment reduction run on the active engine (differentiable in block_probs on torch). The optional assignment prior is added per graph.

Parameters:
Return type:

Any

link_probability(i, j, block_assignments=None)[source]
Parameters:

  • i (int)

  • j (int)

  • block_assignments (Any | None)

Return type:

float

edge_marginals(block_assignments=None, num_nodes=None)[source]
Parameters:

  • block_assignments (Any | None)

  • num_nodes (int | None)

Return type:

ndarray

block_marginals(x=None)[source]
Parameters:

x (Any)

Return type:

ndarray

posterior(x)[source]
Parameters:

x (Any)

Return type:

dict[str, Any]

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

StochasticBlockGraphSampler

enumerator()[source]

Enumerate binary graphs in descending probability order, for FIXED block assignments.

With the node block assignments fixed (block_assignments set on the distribution), each edge (i, j) is an independent Bernoulli with its own probability block_probs[a_i, a_j], so the graph distribution is a product of edge factors – enumerated by best-first over the per-edge supports and assembled into an adjacency matrix (mirrored when undirected). The constant assignment-prior term (when include_assignment_prior) enters as a score offset so each graph carries its exact log_density.

Marginalizing over UNKNOWN assignments is intentionally not modeled by this family, so enumeration requires fixed assignments; otherwise EnumerationError.

Return type:

DistributionEnumerator

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

StochasticBlockGraphEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:

GraphDataEncoder

class StochasticBlockGraphEnumerator(dist)[source]

Bases: DistributionEnumerator

Parameters:

dist (StochasticBlockGraphDistribution)

class StochasticBlockGraphSampler(dist, seed=None)[source]

Bases: DistributionSampler

Sample binary graphs from an SBM.

Parameters:

  • dist (StochasticBlockGraphDistribution)

  • seed (int | None)

sample_assignments(num_nodes)[source]
Parameters:

num_nodes (int)

Return type:

ndarray

sample_graph(num_nodes=None, block_assignments=None, return_assignments=False)[source]
Parameters:

  • num_nodes (int | None)

  • block_assignments (Any | None)

  • return_assignments (bool)

Return type:

Any

sample(size=None, num_nodes=None, block_assignments=None, return_assignments=False)[source]

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:

  • size (int | None)

  • num_nodes (int | None)

  • block_assignments (Any | None)

  • return_assignments (bool)

Return type:

Any

class StochasticBlockGraphAccumulator(num_blocks=None, block_assignments=None, directed=False, self_loops=False, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate block-pair edge counts for SBM fitting.

Parameters:

  • num_blocks (int | None)

  • block_assignments (Any | None)

  • directed (bool)

  • self_loops (bool)

  • name (str | None)

  • keys (str | None)

update(x, weight, estimate)[source]
Parameters:

  • x (Any)

  • weight (float)

  • estimate (StochasticBlockGraphDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:

  • x (Sequence[GraphObservation])

  • weights (ndarray)

  • estimate (StochasticBlockGraphDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[ndarray, ndarray, ndarray, float, float])

Return type:

StochasticBlockGraphAccumulator

value()[source]
Return type:

tuple[ndarray, ndarray, ndarray, float, float]

from_value(x)[source]
Parameters:

x (tuple[ndarray, ndarray, ndarray, float, float])

Return type:

StochasticBlockGraphAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]
Return type:

GraphDataEncoder

class StochasticBlockGraphAccumulatorFactory(num_blocks=None, block_assignments=None, directed=False, self_loops=False, name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for StochasticBlockGraphAccumulator.

Parameters:

  • num_blocks (int | None)

  • block_assignments (Any | None)

  • directed (bool)

  • self_loops (bool)

  • name (str | None)

  • keys (str | None)

make()[source]
Return type:

StochasticBlockGraphAccumulator

class StochasticBlockGraphEstimator(num_blocks=None, block_assignments=None, directed=False, self_loops=False, pseudo_count=None, prior_p=0.5, block_prior=None, estimate_block_prior=True, include_assignment_prior=False, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimate an SBM from graphs with observed block assignments.

Parameters:

  • num_blocks (int | None)

  • block_assignments (Any | None)

  • directed (bool)

  • self_loops (bool)

  • pseudo_count (float | None)

  • prior_p (float)

  • block_prior (Any | None)

  • estimate_block_prior (bool)

  • include_assignment_prior (bool)

  • name (str | None)

  • keys (str | None)

accumulator_factory()[source]
Return type:

StochasticBlockGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

StochasticBlockGraphDistribution