This document describes the process by which
ergm and related packages selects the MCMC proposal for a particular analysis. Note that it is not intended to be a tutorial as much as a description of what inputs and outputs different parts of the system expect. Nor does it cover the C API.
There is a number of factors that can affect MCMC sampling, some of them historical and some of them new:
functions and other structures defined in an accessible namespace
ergm_proposal_table()a function that if called with no arguments returns a table of registered proposals and updates it otherwise. See
? ergm_proposal_tablefor documentation and the meaning of its columns. Of particular interest is its
Constraintscolumn, which encodes which constraints the proposal does (always) enforce and which it can enforce.
InitErgmReference.<REFERENCE>a family of initializers for the reference distribution. For the purposes of the proposal selection, among its outputs should be
$namespecifying the name of the reference distribution.
InitErgmConstraint.<CONSTRAINT>a family of initializers for constraints, weightings, and other high-level specifiers of the proposal distribution. Hard constraints, probabilistic weights, and hints all use this API. For the purposes of the proposal selection, its outputs include
<CONSTRAINT>) a character vector specifying which constraints are enforced, and can include several semantically nested elements;
TRUE) specifying whether the constraint is dyad-dependent;
Inf) specifying how important it is that the constraint is met (with
Infmeaning that it must be met); and
$impliedbyspecifying which other constraints this constraint enforces or is enforced by, and this can include itself for constraints, such as
edgesthat can only be applied once.
arguments and settings passed to the call or as control parameters.
constraints=argument (top-level): A one-sided formula containing a
--separated list of constraints.
+terms add additional constraints to the model whereas
-constraints relax them.
-constraints are primarily used internally observational process estimation and are not described in detail, except to note that 1) they must be dyad-independent and 2) they necessitate falling back to the RLEBDM sampling API.
reference=argument (top-level): A one-sided formula specifying the ERGM reference distribution, usually as a name with parameters if appropriate.
control$MCMC.prop=control parameter: A formula whose RHS containing
+-separated “hints” to the sampler; an optional LHS may contain the proposal name directly.
control$MCMC.prop.weights=control parameter: A string selecting proposal weighting (probably deprecated)
control$MCMC.prop.args=control parameter: A list specifying information to be passed to the proposal
Most of this is implemented in the
InitErgmReference.<REFERENCE>is called with arguments of
reference=’s LHS, obtaining the name of the reference.
InitErgmConstraint.<CONSTRAINT>function is called and their outputs are stored in a list of initialized constraints (an
.dyadspseudo-constraint is added to dyad-independent constraints (not to hints with
$priority < Inf).
ergm_proposal_table()are filtered by
Proposal(if the LHS of
priority=Inf, it is discarded.
priority<Infand that the proposal doesn’t and can’t enforce, its (innate, specified in the column of the
Priorityvalue is penalised by the
priorityof that constraint.