sample_ccm: Sample from a Congruence Class Model (CCM)

In CCMnet: Congruence Class Models for Networks

Sample from a Congruence Class Model (CCM)

Description

sample_ccm generates networks from a Congruence Class Model using a Metropolis-Hastings MCMC framework. Unlike traditional models that fit parameters to a single observed graph, CCM samples from the space of all possible networks where topological properties follow specified target probability distributions.

Usage

sample_ccm(
  network_stats,
  prob_distr,
  prob_distr_params,
  population,
  sample_size = 1000L,
  burnin = 200000L,
  interval = 1000L,
  cov_pattern = NULL,
  initial_g = NULL,
  use_initial_g = FALSE,
  partial_network = as.integer(0),
  obs_nodes = NULL,
  Obs_stats = NULL,
  remove_var_last_entry = FALSE,
  stats_only = TRUE
)

Arguments

network_stats	Character vector of statistic names to be targeted. For joint targets, use vectors like c("degmixing", "triangles").
prob_distr	Character vector of probability distribution names corresponding to each statistic.
prob_distr_params	List of parameter sets for each specified distribution.
population	Integer. The number of nodes in the network.
sample_size	Integer. Number of MCMC samples to return. Default is 1000.
burnin	Integer. Number of MCMC iterations to discard before sampling begins. Default is 200,000.
interval	Integer. Thinning interval (number of iterations between samples). Default is 1000.
cov_pattern	Integer vector. Optional nodal attributes (group IDs) required for mixing or degree-mixing targets.
initial_g	An igraph object. The starting graph for the MCMC chain.
use_initial_g	Logical. If TRUE, the MCMC chain starts from initial_g.
partial_network	Integer. Reserved for future use.
obs_nodes	Integer vector. Reserved for future use in specifying observed nodes.
Obs_stats	Character vector of additional network statistics to monitor (but not target) during sampling. Reserved for future use.
remove_var_last_entry	Logical. If TRUE, the last entry of the variance matrix is dropped to ensure invertibility for certain distributions.
stats_only	Logical. If TRUE, only sufficient statistics are returned; if FALSE, the list of sampled igraph objects is included.

Details

Target Distributions

The model treats network statistics as random variables following a target distribution. The following table summarizes the implemented network statistics and their compatible distributions:

Network Statistic	Compatible Target Distributions
"edges"	"poisson", "uniform", "np"
"density"	"normal", "beta"
"degreedist"	"dirmult"
"degmixing"	"mvn"
"mixing"	"poisson"
c("degmixing", "triangles")	c("mvn", "normal")
c("degreedist", "mixing")	c("mvn", "normal")

The returned ccm_sample object has associated plot and sample_theoretical methods for diagnostic and comparative analysis.

Value

An object of class ccm_sample containing:

• mcmc_stats: A data frame of sampled network statistics.

• population: The number of nodes in the network.

• prob_distr: The names of the target distributions used.

• prob_distr_params: The parameter values used for the target distributions.

• network_stats: The names of the network statistics targeted.

• cov_pattern: The nodal covariate pattern used (if any).

• theoretical: A list containing theoretical samples, populated by calling sample_theoretical().

• g: A list of sampled igraph objects (last network if stats_only = TRUE).

See Also

sample_theoretical, plot.ccm_sample

Examples

# 1. Define target distributions and sample from the CCM
ccm_sample <- sample_ccm(
  network_stats = "edges",
  prob_distr = "poisson",
  prob_distr_params = list(list(350)),
  population = 50
)

# 2. Generate theoretical samples for the same target
ccm_sample <- sample_theoretical(ccm_sample)

# 3. Visualize MCMC samples against theoretical target
plot(ccm_sample, type = "hist", include_theoretical = TRUE)

CCMnet documentation built on March 2, 2026, 9:06 a.m.