mixle.stats.graphs.stochastic_block_graph module

Stochastic block graph distributions with explicit conditional or joint laws.

Fixed assignments define p(adjacency | assignments). Without fixed assignments, observations are (adjacency, assignments) pairs scored under the joint law p(assignments) p(adjacency | assignments). This family does not claim to marginalize assignments out of a bare adjacency observation.

class StochasticBlockGraphDistribution(block_probs, block_assignments=None, block_prior=None, directed=False, self_loops=False, include_assignment_prior=None, 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 | None)

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

np.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:

  • x (Sequence[GraphObservation])

  • engine (Any)

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

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=None)[source]

Draw one graph, optionally returning the assignments used.

Population models always return the joint (adjacency, assignments) outcome. Fixed-assignment models return the conditional adjacency by default; callers may request the redundant fixed assignments as well.

Parameters:

  • num_nodes (int | None)

  • block_assignments (Any | None)

  • return_assignments (bool | None)

Return type:

Any

sample(size=None, num_nodes=None, block_assignments=None, return_assignments=None, *, batched=True)[source]

Draw one graph or a list of graphs from the SBM.

See sample_graph() for how return_assignments=None (the default) auto-includes assignments only when they are not otherwise recoverable for scoring.

Parameters:

  • size (int | None)

  • num_nodes (int | None)

  • block_assignments (Any | None)

  • return_assignments (bool | None)

  • batched (bool)

Return type:

Any

class StochasticBlockGraphStatistics(schema_version, successes, totals, block_counts, total_nodes, num_graphs, directed, self_loops)[source]

Bases: NamedTuple

Versioned, configuration-bound sufficient statistics for an SBM.

Parameters:
schema_version: int

Alias for field number 0

successes: ndarray

Alias for field number 1

totals: ndarray

Alias for field number 2

block_counts: ndarray

Alias for field number 3

total_nodes: float

Alias for field number 4

num_graphs: float

Alias for field number 5

directed: bool

Alias for field number 6

self_loops: bool

Alias for field number 7

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 (np.ndarray)

  • estimate (StochasticBlockGraphDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize sufficient statistics from a weighted graph batch.

Parameters:

  • x (Sequence[GraphObservation])

  • weights (np.ndarray)

  • rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge serialized SBM sufficient statistics.

Parameters:

suff_stat (StochasticBlockGraphStatistics)

Return type:

StochasticBlockGraphAccumulator

value()[source]

Return serialized SBM sufficient statistics.

Return type:

StochasticBlockGraphStatistics

from_value(x)[source]

Restore accumulator state from serialized SBM sufficient statistics.

Parameters:

x (StochasticBlockGraphStatistics)

Return type:

StochasticBlockGraphAccumulator

key_merge(stats_dict)[source]

Merge this accumulator under its configured sharing key.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator from its configured sharing key.

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=None, 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 | None)

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

  • nobs (float | None)

  • suff_stat (StochasticBlockGraphStatistics)

Return type:

StochasticBlockGraphDistribution