mixle.stats.graphs.stochastic_block_graph module

Stochastic block graph distributions with observed or fixed block assignments.

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]

Return backend capabilities for block-structured Bernoulli graph scoring.

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

Create a distribution wrapper from a random-graph SBM model.

Parameters:

  • model (Any)

  • block_prior (Any | None)

  • include_assignment_prior (bool)

Return type:

StochasticBlockGraphDistribution

to_model()[source]

Convert this distribution to the corresponding random-graph model.

Return type:

Any

density(x)[source]

Return the probability mass of one graph observation.

Parameters:

x (Any)

Return type:

float

log_density(x)[source]

Return the conditional block-model log probability of one graph.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)[source]

Score a batch of graph 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]

Return the marginal or assignment-conditional edge probability for node pair (i, j).

Parameters:

  • i (int)

  • j (int)

  • block_assignments (Any | None)

Return type:

float

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

Return the matrix of edge probabilities under fixed or prior-predictive assignments.

Parameters:

  • block_assignments (Any | None)

  • num_nodes (int | None)

Return type:

ndarray

block_marginals(x=None)[source]

Return empirical block proportions for x or the model block prior.

Parameters:

x (Any)

Return type:

ndarray

posterior(x)[source]

Return block counts, block proportions, and edge marginals for an observed graph.

Parameters:

x (Any)

Return type:

dict[str, Any]

sampler(seed=None)[source]

Return a sampler for SBM graph observations.

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 observed-assignment SBM fitting.

Parameters:

pseudo_count (float | None)

Return type:

StochasticBlockGraphEstimator

dist_to_encoder()[source]

Return the graph encoder used by vectorized scoring and fitting.

Return type:

GraphDataEncoder

class StochasticBlockGraphEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerator over binary graphs with fixed block assignments.

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]

Draw node block assignments from the block prior.

Parameters:

num_nodes (int)

Return type:

ndarray

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

Draw one graph, optionally returning the assignments used.

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 one graph or a list of graphs from the SBM.

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]

Accumulate weighted block-pair edge counts from one graph.

Parameters:

  • x (Any)

  • weight (float)

  • estimate (StochasticBlockGraphDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Initialize sufficient statistics from one weighted graph.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate weighted block-pair edge counts from a batch.

Parameters:

  • x (Sequence[GraphObservation])

  • weights (ndarray)

  • estimate (StochasticBlockGraphDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize sufficient statistics from a weighted graph batch.

Parameters:
Return type:

None

combine(suff_stat)[source]

Merge serialized SBM sufficient statistics.

Parameters:

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

Return type:

StochasticBlockGraphAccumulator

value()[source]

Return serialized SBM sufficient statistics.

Return type:

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

from_value(x)[source]

Restore accumulator state from serialized SBM sufficient statistics.

Parameters:

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

Return type:

StochasticBlockGraphAccumulator

key_merge(stats_dict)[source]

Merge tied SBM sufficient statistics into stats_dict.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace tied SBM sufficient statistics from stats_dict.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]

Return the encoder associated with this accumulator.

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]

Create a fresh SBM accumulator.

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 the accumulator factory used by this estimator.

Return type:

StochasticBlockGraphAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate block probabilities and the block prior from sufficient statistics.

Parameters:
Return type:

StochasticBlockGraphDistribution