Type: Package
Title: Congruence Class Models for Networks
Version: 1.0.0
Description: Provides an implementation of Congruence Class Models for generating networks. It facilitates sampling networks based on specific topological properties and attribute mixing patterns using a Markov Chain Monte Carlo framework. The implementation builds upon code from the 'ergm' package; see Handcock et al. (2008) <doi:10.18637/jss.v024.i01>.
License: GPL-3
Encoding: UTF-8
Imports: dplyr, ergm, ggplot2, gtools, igraph, intergraph, kableExtra, mvtnorm, network, RBesT, rlang, stats, tibble, tidyr, utils
Suggests: knitr, rmarkdown, testthat
VignetteBuilder: knitr
RoxygenNote: 7.3.2
NeedsCompilation: yes
Packaged: 2026-03-02 07:08:59 UTC; ravigoyal
Author: Ravi Goyal [aut, cre], Statnet Development Team [ctb, cph]
Maintainer: Ravi Goyal <ravi.j.goyal@gmail.com>
Repository: CRAN
Date/Publication: 2026-03-02 08:00:02 UTC

Methods for ccm_sample Objects

Description

Printing, summarizing, and plotting methods for results generated by sample_ccm.

Usage

## S3 method for class 'ccm_sample'
plot(
  x,
  stats = NULL,
  type = c("density", "hist", "trace"),
  include_theoretical = FALSE,
  ...
)

## S3 method for class 'ccm_sample'
print(x, ...)

## S3 method for class 'ccm_sample'
summary(object, ...)

Arguments

x, object

An object of class ccm_sample.

stats

Character vector of statistic names to plot. If NULL, all targeted statistics are plotted.

type

Character string specifying the plot type: "density", "hist", or "trace".

include_theoretical

Logical. If TRUE, overlays the theoretical target distribution (requires running sample_theoretical first).

...

Additional arguments passed to methods.

Details

For type = "trace", setting include_theoretical = TRUE adds a red dashed line for the theoretical mean and red dotted lines for the 2.5% and 97.5% quantiles.

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:

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)

Generate Samples from Target Distributions

Description

This function draws samples directly from the target probability distributions specified in a ccm_sample object. These samples serve as a "ground truth" to evaluate whether the MCMC chain has converged to the intended target.

Usage

sample_theoretical(object, n_sim = nrow(object$mcmc_stats))

Arguments

object

An object of class ccm_sample generated by sample_ccm.

n_sim

Integer. The number of independent samples to draw from the theoretical target distributions. Default is equal to the number of CCM samples.

Details

This function performs direct i.i.d. sampling (e.g., using rpois, rnorm, etc.) based on the parameters stored in the ccm_sample object. It does not use MCMC. The resulting samples are used by plot.ccm_sample when include_theoretical = TRUE is specified.

Value

The input ccm_sample object with the theoretical slot populated. This slot contains a data frame of statistics sampled directly from the target distributions.

Examples

# 1. Generate MCMC samples
ccm_sample <- sample_ccm(
  network_stats = "edges",
  prob_distr = "poisson",
  prob_distr_params = list(list(350)),
  population = 50 
)

# 2. Generate theoretical samples for comparison
ccm_sample <- sample_theoretical(ccm_sample, n_sim = 1000)

# 3. Compare MCMC to theoretical target
plot(ccm_sample, stats = "edges", type = "hist", include_theoretical = TRUE)