mixle.stats.graphs.random_dot_product_graph module

Create, estimate, and sample from a Random Dot Product Graph (RDPG) distribution.

Defines the RandomDotProductGraphDistribution, RandomDotProductGraphSampler, RandomDotProductGraphAccumulatorFactory, RandomDotProductGraphAccumulator, RandomDotProductGraphEstimator, and reuses the shared GraphDataEncoder for use with mixle.

Data type: a binary undirected graph on n nodes (a square adjacency matrix, a NetworkX-like graph, or any mapping accepted by GraphDataEncoder).

The RDPG is a latent-position graph model: each node i carries a latent vector x_i in R^d, and edges are independent Bernoulli draws with probability equal to the dot product of the endpoints’ positions,

P(A_ij = 1) = clip(<x_i, x_j>, 0, 1).

This generalizes Erdos-Renyi (rank-1, constant positions) and captures community / homophily structure through the geometry of the positions. Sampling draws independent Bernoulli edges from the probability matrix X X^T. Estimation uses Adjacency Spectral Embedding (ASE): the latent positions are the top-d scaled eigenvectors of the mean adjacency matrix, the standard consistent RDPG estimator.

class RandomDotProductGraphDistribution(positions, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Random Dot Product Graph over n nodes with d-dimensional latent positions X (edge prob X X^T).

Parameters:
classmethod compute_capabilities()[source]
edge_marginals()[source]

Return the n-by-n matrix of edge probabilities P(A_ij = 1).

Return type:

ndarray

density(x)[source]

Return the probability of a graph x.

Parameters:

x (Any)

Return type:

float

log_density(x)[source]

Return the log-probability of a binary undirected graph x.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)[source]

Return vectorized log-probabilities for a sequence of graph observations.

Parameters:

x (Sequence[GraphObservation])

Return type:

ndarray

backend_seq_log_density(x, engine)[source]

Engine-routed RDPG edge log-likelihood (reduction runs on the active engine).

Parameters:
Return type:

Any

sampler(seed=None)[source]

Return a sampler for drawing graphs from this distribution.

Parameters:

seed (int | None)

Return type:

RandomDotProductGraphSampler

estimator(pseudo_count=None)[source]

Return an ASE estimator that keeps the latent dimension fixed at this distribution’s d.

Parameters:

pseudo_count (float | None)

Return type:

RandomDotProductGraphEstimator

dist_to_encoder()[source]

Return the shared graph data encoder.

Return type:

GraphDataEncoder

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

Bases: DistributionSampler

Sample binary undirected graphs from an RDPG (independent Bernoulli edges with prob X X^T).

Parameters:

  • dist (RandomDotProductGraphDistribution)

  • seed (int | None)

sample_graph()[source]
Return type:

ndarray

sample(size=None)[source]

Draw graphs (adjacency matrices); a single matrix when size is None.

Parameters:

size (int | None)

Return type:

ndarray | list[ndarray]

class RandomDotProductGraphAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate the weighted sum of adjacency matrices (the sufficient statistic for ASE).

Parameters:

keys (str | None)

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

  • x (Any)

  • weight (float)

  • estimate (RandomDotProductGraphDistribution | 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 (RandomDotProductGraphDistribution | None)

Return type:

None

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

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[float, ndarray | None])

Return type:

RandomDotProductGraphAccumulator

value()[source]
Return type:

tuple[float, ndarray | None]

from_value(x)[source]
Parameters:

x (tuple[float, ndarray | None])

Return type:

RandomDotProductGraphAccumulator

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

Bases: StatisticAccumulatorFactory

Factory for RandomDotProductGraphAccumulator.

Parameters:

keys (str | None)

make()[source]
Return type:

RandomDotProductGraphAccumulator

class RandomDotProductGraphEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Adjacency Spectral Embedding estimator for the RDPG latent positions.

Parameters:

  • dim (int)

  • name (str | None)

  • keys (str | None)

accumulator_factory()[source]
Return type:

RandomDotProductGraphAccumulatorFactory

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

RandomDotProductGraphDistribution