This document describes the process by which
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.
$free_dyadseither an RLEBDM or a function with no arguments that returns an RLEBDM specifying which dyads are not constrained by this constraint.
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.