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. CCM samples networks where topological properties follow specified target probability distributions.

Usage

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

Arguments

network_stats	Character vector of statistic names to be targeted. See ccm_properties for the full list of available network properties.
prob_distr	Character vector of probability distribution names corresponding to each statistic. See ccm_distributions for details on implemented probability distributions and parameter requirements.
prob_distr_params	List of parameter sets for each specified distribution. Each element must be a list containing the parameters required by the chosen distribution (e.g., list(shape, rate) for "gamma"). See ccm_distributions for details on implemented probability distributions and parameter requirements.
population	Integer. The number of nodes in the network.
cov_pattern	Integer vector. Optional nodal attributes (group IDs) required for mixing or degree-mixing targets.
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.
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.
stats_only	Logical. If TRUE, only sufficient statistics are returned; if FALSE, the list of sampled igraph objects is included.
verbose	Integer. Level of output logging (0 = silent, 1 = basic, 2 = detailed).
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.

Details

The CCM framework allows generation of networks under flexible specifications for network structures. The framework decouples network properties from their probability distributions, enabling users can model a range of probability distributions for network properties (e.g., a Gamma or Multivariate-Normal distributions for degree mixing).

For specific mathematical details on how distributions like "dirmult" and "gamma" are implemented, refer to ccm_distributions.

The returned ccm_sample object has associated plot and sample_target_distr 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).

• target_distr: A list containing target distribution samples, populated by calling sample_target_distr().

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

See Also

ccm_properties, ccm_distributions, sample_target_distr, plot.ccm_sample

Other ccm_core: ccm_distributions, ccm_properties

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_target_distr(ccm_sample)

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

CCMnet documentation built on June 9, 2026, 9:07 a.m.