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:
Globals
: 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_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 **can** enforce. * `InitErgmReference.<REFERENCE>` a family of initializers for the reference distribution. For the purposes of the proposal selection, among its outputs should be `$name` 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 elements; * `$dependence` (defaulting to `TRUE`) specifying whether the constraint is dyad-dependent; * `$priority` (defaulting to `Inf`) specifying how important it is that the constraint is met (with `Inf` meaning that it *must* be met); and * `$implies`/`$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
: arguments and settings passed to the call or as control parameters.
* `constraints=` argument (top-level): A one-sided formula containing a `+`- or `-`-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 ergm_proposal.formula()
method:
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 ergm_conlist
object). .dyads
pseudo-constraint is added to dyad-independent constraints (not to hints with $priority < Inf
). For hints, $dependence
element is overwritten to FALSE
. The list is named, with the name taken from the first element of the $constrains
.constraints=
MCMC.prop=
$implies
/$impliedby
settings.ergm_proposal_table()
are filtered by Class
, Reference
, Weights
(if MCMC.prop.weights
differs from "default"
), and 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 ergm_proposal_table()
) 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.)Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.