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
? ergm_proposal_table for documentation and
the meaning of its columns. Of particular interest is its
Constraints column, which encodes which constraints the
proposal does (always) enforce and which it
InitErgmReference.<REFERENCE> a family of
initializers for the reference distribution. For the purposes of the
proposal selection, among its outputs should be
specifying 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
$constrain (defaulting to
<CONSTRAINT>) a character vector specifying which
constraints are enforced, and can include several semantically nested
$dependence (defaulting to
specifying whether the constraint is dyad-dependent;
$priority (defaulting to
how important it is that the constraint is met (with
meaning that it must be met); and
$impliedby specifying which other
constraints this constraint enforces or is enforced by, and this can
include itself for constraints, such as
edges that can only
be applied once.
$free_dyads either 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
--separated list of
+ terms add additional constraints to the
- 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
+-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
reference=’s LHS, obtaining the name of the
InitErgmConstraint.<CONSTRAINT> function is called
and their outputs are stored in a list of initialized constraints (an
is added to dyad-independent constraints (not to hints with
$priority < Inf).
are filtered by
MCMC.prop.weights differs from
Proposal (if the LHS of
MCMC.prop is provided).
priority==Inf, it is discarded.
priority<Inf and that the proposal
doesn’t and can’t enforce, its
(innate, specified in the column of the
Priority value is
penalised by the
priority of that constraint.
InitErgmProposal.* functions are attempted. If
a call returns
NULL, next proposal is attempted. (This can
be useful if a proposal handles a particular special case that is not
accounted for by constraints.)