Generally, ergm constraint specifications can now be term_lists and potentially heterogeneous lists of term_lists, formulas (one- or two-sided), and character strings. A new helper function, ergm_flatten_conterm_list() can be used to take any of these and conver them to a flat term_list of unique constraints. Also, control.ergm(obs.MCMC.prop=) argument's default is now NULL, since MCMC.prop's hints will carry over anyway.

Author: krivit

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: ergm
-Version: 4.13.0-8019
+Version: 4.13.0-8020
 Date: 2026-03-20
 Title: Fit, Simulate and Diagnose Exponential-Family Models for Networks
 Authors@R: c(

NAMESPACE

@@ -59,8 +59,10 @@ S3method(ergm_attr_levels,logical)
 S3method(ergm_attr_levels,matrix)
 S3method(ergm_attr_levels,numeric)
 S3method(ergm_conlist,"NULL")
+S3method(ergm_conlist,character)
 S3method(ergm_conlist,ergm_conlist)
 S3method(ergm_conlist,formula)
+S3method(ergm_conlist,list)
 S3method(ergm_conlist,term_list)
 S3method(ergm_get_vattr,"function")
 S3method(ergm_get_vattr,AsIs)
@@ -246,6 +248,7 @@ export(ergm_conlist)
 export(ergm_cutoff_message)
 export(ergm_dyadgen_select)
 export(ergm_edgecov_args)
+export(ergm_flatten_conterm_list)
 export(ergm_get_vattr)
 export(ergm_keyword)
 export(ergm_mk_std_op_namewrap)

R/control.ergm.R

@@ -588,7 +588,7 @@ control.ergm<-function(drop=TRUE,
                        obs.MCMC.interval=EVL(round(MCMC.interval*obs.MCMC.interval.mul)),
                        obs.MCMC.burnin.mul=sqrt(obs.MCMC.mul),
                        obs.MCMC.burnin=EVL(round(MCMC.burnin*obs.MCMC.burnin.mul)),
-                       obs.MCMC.prop=MCMC.prop, obs.MCMC.prop.weights=MCMC.prop.weights, obs.MCMC.prop.args=MCMC.prop.args,
+                       obs.MCMC.prop=NULL, obs.MCMC.prop.weights=MCMC.prop.weights, obs.MCMC.prop.args=MCMC.prop.args,
                        obs.MCMC.impute.min_informative = function(nw) network.size(nw)/4,
                        obs.MCMC.impute.default_density = function(nw) 2/network.size(nw),
 

R/ergm.R

@@ -368,13 +368,13 @@ ergm <- function(formula, response=NULL,
 
   if(!is(constraints, "ergm_proposal")){
     # Handle the observation process and other "automatic" constraints.
-    tmp <- .handle.auto.constraints(nw, constraints, obs.constraints, target.stats)
+    tmp <- .handle.auto.constraints(nw, constraints, obs.constraints, target.stats, control)
     nw <- tmp$nw
     conterms.obs <- tmp$conterms.obs
     conterms <- tmp$conterms
   }else if(!is(obs.constraints, "ergm_proposal")){
     # Handle the observation process and other "automatic" constraints.
-    tmp <- .handle.auto.constraints(nw, trim_env(~.), obs.constraints, target.stats)
+    tmp <- .handle.auto.constraints(nw, trim_env(~.), obs.constraints, target.stats, control)
     nw <- tmp$nw
     conterms.obs <- tmp$conterms.obs
     conterms <- tmp$conterms
@@ -388,15 +388,19 @@ ergm <- function(formula, response=NULL,
     warn(paste0("The default Bernoulli reference distribution operates in the binary (",sQuote("response=NULL"),") mode only. Did you specify the ",sQuote("reference")," argument?"))
   }
 
-    proposal <- ergm_proposal(conterms, hints=control$MCMC.prop, weights=control$MCMC.prop.weights, control$MCMC.prop.args, nw, class=proposalclass,reference=reference, term.options=control$term.options)
+    proposal <- ergm_proposal(conterms, weights = control$MCMC.prop.weights,
+                              control$MCMC.prop.args, nw, class = proposalclass,
+                              reference = reference, term.options = control$term.options)
   }else proposal <- constraints
 
   if (verbose) message(sQuote(paste0(proposal$pkgname,":MH_",proposal$name)),".")
 
   if(!is(obs.constraints, "ergm_proposal")){
     if(!is.null(conterms.obs)){
       if (verbose) message("Initializing constrained Metropolis-Hastings proposal: ", appendLF=FALSE)
-      proposal.obs <- ergm_proposal(conterms.obs, hints=control$obs.MCMC.prop, weights=control$obs.MCMC.prop.weights, control$obs.MCMC.prop.args, nw, class=proposalclass, reference=reference, term.options=control$term.options)
+      proposal.obs <- ergm_proposal(conterms.obs, weights = control$obs.MCMC.prop.weights,
+                                    control$obs.MCMC.prop.args, nw, class = proposalclass,
+                                    reference = reference, term.options = control$term.options)
     }else proposal.obs <- NULL
   }else proposal.obs <- obs.constraints
 

R/ergm.san.R

@@ -213,11 +213,13 @@ san.formula <- function(object, response=NULL, reference=~Bernoulli, constraints
   if(!is(nw,"ergm_state")) ergm_preprocess_response(nw, response)
 
   # Inherit constraints from nw if needed.
-  tmp <- .handle.auto.constraints(nw, constraints, NULL, NULL)
+  tmp <- .handle.auto.constraints(nw, constraints, NULL, NULL, control, "SAN")
   nw <- tmp$nw; conterms <- tmp$conterms
 
   if (verbose) message("Initializing unconstrained Metropolis-Hastings proposal: ", appendLF=FALSE)
-  proposal<-ergm_proposal(conterms,arguments=control$SAN.prop.args,nw=nw, hints=control$SAN.prop, weights=control$SAN.prop.weights, class="c",reference=reference, term.options=control$term.options)
+  proposal <- ergm_proposal(conterms, arguments = control$SAN.prop.args, nw = nw,
+                            weights = control$SAN.prop.weights, class = "c",
+                            reference = reference, term.options = control$term.options)
   if (verbose) message(sQuote(paste0(proposal$pkgname,":MH_",proposal$name)),".")
   if (verbose) message("Initializing model...")
   model <- ergm_model(formula, nw, extra.aux=list(proposal=proposal$auxiliaries), term.options=control$term.options)
@@ -274,11 +276,13 @@ san.ergm_model <- function(object, reference=~Bernoulli, constraints=~., target.
   if(inherits(constraints, "ergm_proposal")) proposal <- constraints
   else{
     # Inherit constraints from nw if needed.
-    tmp <- .handle.auto.constraints(nw, constraints, NULL, NULL)
+    tmp <- .handle.auto.constraints(nw, constraints, NULL, NULL, control, "SAN")
     nw <- tmp$nw; conterms <- tmp$conterms
     if (verbose) message("Initializing unconstrained Metropolis-Hastings proposal: ", appendLF=FALSE)
-    proposal <- ergm_proposal(conterms,arguments=control$SAN.prop.args,
-                              nw=nw, hints=control$SAN.prop, weights=control$SAN.prop.weights, class="c",reference=reference, term.options=control$term.options)
+    proposal <- ergm_proposal(conterms, arguments = control$SAN.prop.args,
+                              nw = nw, weights = control$SAN.prop.weights,
+                              class = "c", reference = reference,
+                              term.options = control$term.options)
     if (verbose) message(sQuote(paste0(proposal$pkgname,":MH_",proposal$name)),".")
   }
 

R/ergm_proposal.R

@@ -62,6 +62,11 @@
 #'   `ergm_proposal_table()`, it also sets a call-back to remove all
 #'   of its proposals from the table should the package be unloaded.
 #'
+#' @return If called without arguments, a table of the above. Note
+#'   that `Constraints` column is preprocessed into a [`list`] column
+#'   with character vector elements `$does` and `$can` and a logical
+#'   element `$can_any` indicating that it's a meta constraint.
+#'
 #' @keywords internal
 #' @export
 ergm_proposal_table <- local({
@@ -156,13 +161,19 @@ prune.ergm_conlist <- function(conlist){
 #
 ########################################################################################
 
-# If the constraints formula is two-sided, add a term .select(LHS) and remove LHS.
-.embed_constraint_lhs <- function(formula){
-  if(length(formula) > 2){
-    lhs <- try(eval_lhs.formula(formula), silent = TRUE)
-    if (is(lhs, "try-error") || !is.character(lhs)) stop("Constraint formula must be either one-sided or have a string expression as its LHS.")
-    nonsimp_update.formula(formula, substitute(~. + .select(..), list(..=lhs)))
-  }else formula
+# If the constraints formula is two-sided, add a term .select(LHS) and
+# remove LHS. Also, if the result is a character string, we construct
+# a one-sided formula with .select(x). term_lists get passed through.
+.embed_constraint_lhs <- function(x) {
+  if (is(x, "formula")) {
+    if (length(x) > 2L) {
+      lhs <- try(eval_lhs.formula(x), silent = TRUE)
+      if (is(lhs, "try-error") || !is.character(lhs)) stop("Constraint formula must be either one-sided or have a string expression as its LHS.")
+      nonsimp_update.formula(x, substitute(~. + .select(..), list(.. = lhs)))
+    } else x
+  } else if (is.character(x)) as.formula(call("~", call(".select", x)), baseenv())
+  else if (is(x, "term_list")) x
+  else stop("Constraint must be either a formula or a string.")
 }
 
 .delete_term <- function(tl, terms) discard(tl, ~any(as.character(.)[1] %in% terms))
@@ -283,6 +294,18 @@ ergm_proposal.character <- function(object, arguments, nw, ..., reference=ergm_r
 #' @export
 ergm_conlist <- function(object, ...) UseMethod("ergm_conlist")
 
+#' @describeIn ergm_conlist list of other eligible inputs: concatenates.
+#' @export
+ergm_conlist.list <- function(object, ...) {
+  object <- compact(object)
+  OK <- map_lgl(object,  \(x) is.character(x) || is(x, "formula") || is(x, "term_list"))
+  if (any(!OK))
+    stop("Invalid list element(s) ", deparse1(object[!OK]), " passed to ",
+         sQuote("ergm_conlist()"), "'s ", sQuote("list"), "method.")
+
+  object |> ergm_flatten_conterm_list() |> ergm_conlist(...)
+}
+
 #' @describeIn ergm_conlist identity method.
 #' @export
 ergm_conlist.ergm_conlist <- function(object, ...) object
@@ -299,8 +322,12 @@ ergm_conlist.NULL <- function(object, ...) NULL
 #' @template term_options
 #'
 #' @export
-ergm_conlist.formula <- function(object, nw, ...)
-  object |> .embed_constraint_lhs() |> list_rhs.formula() |> ergm_conlist(nw, ...)
+ergm_conlist.formula <- function(object, ...)
+  object |> ergm_flatten_conterm_list() |> ergm_conlist(...)
+
+#' @describeIn ergm_conlist specify the proposal name directly.
+#' @export
+ergm_conlist.character <- ergm_conlist.formula
 
 #' @describeIn ergm_conlist initialize from [`term_list`].
 #' @export
@@ -495,13 +522,10 @@ call.ErgmReference <- function(term, env, nw, ..., term.options=list()){
 #' documentation for a similar argument for [ergm()] and see
 #' [`ergmConstraint`] for more information.
 #' @export
-ergm_proposal.formula <- function(object, arguments, nw, hints=trim_env(~sparse), ..., term.options=list()) {
-  NVL(hints) <- trim_env(~sparse)
-
+ergm_proposal.formula <- function(object, arguments, nw, ..., term.options = list()) {
   conlist <- if("constraints" %in% names(arguments))
                prune.ergm_conlist(arguments$constraints)
-             else c(ergm_conlist(object, nw, term.options=term.options, ...),
-                    ergm_conlist(hints, nw, term.options=term.options, ...))
+             else ergm_conlist(object, nw, term.options = term.options, ...)
 
   ## Hand it off to the class ergm_conlist method.
   ergm_proposal(conlist, arguments, nw, ..., term.options = term.options)
@@ -621,3 +645,37 @@ free_dyads <- function(con){
   else if(is.function(fd)) fd()
   else stop("Unsupported free_dyad type; this is probably a programming error.")
 }
+
+
+#' Convert a list of constraint formulas or terms to a flat term list
+#'
+#' This helper function processes the usual constraint specifications
+#' ([`formula`]s, [`term_list`]s, [`character`] strings) or a list
+#' thereof into a flat [`term_list`] of distinct values.
+#'
+#' @param l a [`formula`], a [`term_list`], a [`character`], [`NULL`],
+#'   or a (potentially heterogeneous) list thereof.
+#'
+#' @return a [`term_list`].
+#'
+#' @examples
+#' z <- 5
+#' ergm_flatten_conterm_list(list(
+#'   NULL,
+#'   ~a(x) - b,
+#'   statnet.common::base_env(~c),
+#'   NULL,
+#'   term_list(call("f", z), env = baseenv(), sign = -1)
+#' ))
+#'
+#' @export
+ergm_flatten_conterm_list <- function(l) {
+  enlist(l) |>
+    compact() |>
+    map(.embed_constraint_lhs) |>
+    map_if(\(tlf) is(tlf, "formula"),
+           list_rhs.formula) |>
+    do.call(c, args = _) |>
+    compact() |>
+    unique()
+}

R/obs.constraints.R

@@ -8,53 +8,67 @@
 #  Copyright 2003-2026 Statnet Commons
 ################################################################################
 
-.handle.auto.constraints <- function(nw,
-                                     constraints=trim_env(~.),
-                                     obs.constraints=trim_env(~.-observed),
-                                     target.stats=NULL,
-                                     default.dot=c("first", "last", "none")){
+dot_sub_constraints <- function(nw, ..., default.dot = c("first", "last", "none")) {
   default.dot <- match.arg(default.dot)
 
-  .preproc_constraints <- function(...){
-    # Embed the LHS as a .select() constraint.
-    tll <- list(...) %>% compact() %>% map(.embed_constraint_lhs) %>% map(list_rhs.formula)
-    # If no missing edges, remove the "observed" constraint.
-    if(network.naedgecount(nw)==0) tll <- map(tll, .delete_term, "observed")
+  # Ensure that each argument is a term_list with LHS embedded.
+  tll <- list(...) |> map(ergm_flatten_conterm_list) |> compact()
+  # If no missing edges, remove the "observed" constraint.
+  if (network.naedgecount(nw) == 0L) tll <- map(tll, .delete_term, "observed")
 
-    if(length(tll) == 0) return(NULL)
+  if(all(lengths(tll) == 0L)) return(NULL)
 
-    # Go through the constraint lists, substituting the earlier ones into the dots in the later ones.
-    otl <- tll[[1]]
-    for(i in seq_along(tll)[-1]){
-      ntl <- tll[[i]]
+  # Go through the constraint lists, substituting the earlier ones into the dots in the later ones.
+  otl <- tll[[1]]
+  for (i in seq_along(tll)[-1]) {
+    ntl <- tll[[i]]
 
-      # Find the substitution positions.
-      pos <- which(ntl %>% map_chr(~as.character(.)[1]) == ".")
+    # Find the substitution positions.
+    pos <- which(ntl |> map_chr(\(x) as.character(x)[1]) == ".")
 
-      # Don't substitute at negative dots.
-      pos_sign <- attr(ntl, "sign")[pos]
-      pos <- pos[pos_sign>0]
+    # Don't substitute at negative dots.
+    pos_sign <- attr(ntl, "sign")[pos]
+    pos <- pos[pos_sign>0]
 
-      # If no dots, use default behaviour unless there is a negative dot.
-      if(!length(pos) && all(pos_sign>0))
-        ntl <- switch(default.dot,
-                     first = c(otl, ntl),
-                     last = c(ntl, otl),
-                     none = ntl)
+    # If no dots, use default behaviour unless there is a negative dot.
+    if (!length(pos) && all(pos_sign > 0))
+      ntl <- switch(default.dot,
+                    first = c(otl, ntl),
+                    last = c(ntl, otl),
+                    none = ntl)
 
-      # Substitute (working backwards, to prevent pos from changing).
-      for(p in rev(pos))
-        ntl <- c(ntl[seq_len(pos-1)], otl, ntl[-seq_len(pos)])
+    # Substitute (working backwards, to prevent pos from changing).
+    for(p in rev(pos))
+      ntl <- c(ntl[seq_len(pos-1)], otl, ntl[-seq_len(pos)])
 
-      otl <- ntl
-    }
-
-    # Delete remaining dots (including the negative ones).
-    .delete_term(otl, ".")
+    otl <- ntl
   }
 
-  tl <- .preproc_constraints(nw%ergmlhs%"constraints", constraints)
-  obs.tl <- .preproc_constraints(nw%ergmlhs%"obs.constraints", obs.constraints)
+  # Delete remaining dots (including the negative ones).
+  .delete_term(otl, ".")
+}
+
+
+.handle.auto.constraints <- function(nw,
+                                     constraints=trim_env(~.),
+                                     obs.constraints=trim_env(~.-observed),
+                                     target.stats=NULL,
+                                     control = control.ergm(),
+                                     control.prop = "MCMC",
+                                     default.dot=c("first", "last", "none")){
+  default.dot <- match.arg(default.dot)
+
+  tl <- dot_sub_constraints(nw,
+                            nw%ergmlhs%"constraints",
+                            c(enlist(constraints),
+                              enlist(control[[paste0(control.prop, ".prop")]])),
+                            default.dot = default.dot)
+
+  obs.tl <- dot_sub_constraints(nw,
+                                nw%ergmlhs%"obs.constraints",
+                                c(enlist(obs.constraints),
+                                  enlist(control[[paste0("obs.", control.prop, ".prop")]])),
+                                default.dot = default.dot)
 
   # Do any of the observational constraints formulas have terms?
   if(length(obs.tl)){

R/simulate.ergm.R

@@ -319,12 +319,13 @@ simulate_formula <- function(object, ..., basis=eval_lhs.formula(object)) {
     if(!is.list(constraints)) constraints <- list(constraints)
     constraints <- rep(constraints, length.out=2)
     # Inherit constraints from nw if needed.
-    tmp <- .handle.auto.constraints(nw, constraints[[1]], constraints[[2]], NULL)
+    tmp <- .handle.auto.constraints(nw, constraints[[1]], constraints[[2]], NULL, control)
     nw <- tmp$nw; conterms <- if(observational) tmp$conterms.obs else tmp$conterms
 
     if (verbose) message("Initializing unconstrained Metropolis-Hastings proposal: ", appendLF=FALSE)
-    proposal <- ergm_proposal(conterms, arguments=if(observational) control$obs.MCMC.prop.args else control$MCMC.prop.args,
-                              nw=nw, hints=if(observational) control$obs.MCMC.prop else control$MCMC.prop, weights=if(observational) control$obs.MCMC.prop.weights else control$MCMC.prop.weights, class="c",reference=reference, term.options=control$term.options)
+    proposal <- ergm_proposal(conterms, arguments = if(observational) control$obs.MCMC.prop.args else control$MCMC.prop.args,
+                              nw = nw, weights = if (observational) control$obs.MCMC.prop.weights else control$MCMC.prop.weights,
+                              class = "c", reference = reference, term.options = control$term.options)
     if (verbose) message(sQuote(paste0(proposal$pkgname,":MH_",proposal$name)),".")
   }
 
@@ -432,12 +433,13 @@ simulate.ergm_model <- function(object, nsim=1, seed=NULL,
     if(!is.list(constraints)) constraints <- list(constraints)
     constraints <- rep(constraints, length.out=2)
     # Inherit constraints from nw if needed.
-    tmp <- .handle.auto.constraints(nw0, constraints[[1]], constraints[[2]], NULL)
+    tmp <- .handle.auto.constraints(nw0, constraints[[1]], constraints[[2]], NULL, control)
     nw0 <- tmp$nw; conterms <- if(observational) tmp$conterms.obs else tmp$conterms
 
     if (verbose) message("Initializing unconstrained Metropolis-Hastings proposal: ", appendLF=FALSE)
     proposal <- ergm_proposal(conterms, arguments=control$MCMC.prop.args,
-                              nw=nw0, hints=control$MCMC.prop, weights=control$MCMC.prop.weights, class="c",reference=reference, term.options=control$term.options)
+                              nw = nw0, weights = control$MCMC.prop.weights, class = "c",
+                              reference = reference, term.options = control$term.options)
     if (verbose) message(sQuote(paste0(proposal$pkgname,":MH_",proposal$name)),".")
   }