set_algorithm_saom: Functions to create objects containing various aspects of...

In RSiena: Siena - Simulation Investigation for Empirical Network Analysis

Functions to create objects containing various aspects of algorithm specifications for parameter estimation in RSiena

Description

Create objects containing various aspects of algorithm specifications for parameter estimation in RSiena.
set_model_saom sets the specifications of the Stochastic Actor-oriented Model.
set_algorithm_saom sets the specifications of the algorithm for parameter estimation of the model.
set_output_saom sets the specifications of the generated output.

These three aspects are combined in the older functions sienaAlgorithmCreate and
sienaModelCreate, which are identical functions although having different names. The older functions are not preferred any more, but are kept for backward compatibility.

Usage

  set_model_saom(modelType = NULL, behModelType = NULL,
                        MaxDegree = NULL, Offset = NULL)

  set_algorithm_saom(maxlike = FALSE, gmm = FALSE,
    cond = NA, condvarno = 0, condname = "",
    simOnly = FALSE,
    targets = NULL, thetaValues = NULL, seed = NULL,
    n3 = 1000, nsub = 4, n2start = NULL, firstg = 0.2, reduceg = 0.5,
    truncation = 5, doubleAveraging = 0,
    diagonalize = 0.2*!maxlike, standardizeVar = (diagonalize<1),
    dolby = TRUE, splitDepvars = 0, 
	useStdInits = FALSE, findiff = FALSE,
    mult = 5, prML = 1, maximumPermutationLength = 40,
    minimumPermutationLength = 2, initialPermutationLength = 20,
    localML = FALSE)

set_output_saom(outputName = NULL, lessMem = FALSE,
    returnThetas = FALSE, 
    returnChains = FALSE, returnDataFrame = FALSE,
    returnChangeContributions = FALSE)

sienaAlgorithmCreate(fn, projname = "Siena", MaxDegree = NULL,
     Offset = NULL, useStdInits = FALSE, 
     n3 = 1000, nsub = 4, n2start = NULL,
     dolby = TRUE, splitDepvars = 0, 
	 maxlike = FALSE, gmm = FALSE, 
     diagonalize = 0.2*!maxlike,
     condvarno = 0, condname = "", firstg = 0.2, reduceg = 0.5,
     cond = NA, findiff = FALSE, seed = NULL,
     prML = 1, maximumPermutationLength = 40,
     minimumPermutationLength = 2, initialPermutationLength = 20,
     modelType = NULL, behModelType = NULL, mult = 5, simOnly = FALSE,
     localML = FALSE, truncation = 5, doubleAveraging = 0,
     standardizeVar = (diagonalize<1), lessMem = FALSE, silent = FALSE)

sienaModelCreate(fn, projname = "Siena", MaxDegree = NULL,
     Offset = NULL, useStdInits = FALSE, 
     n3 = 1000, nsub = 4, n2start = NULL,
     dolby = TRUE,  splitDepvars = 0, 
	 maxlike = FALSE, gmm = FALSE, 
     diagonalize = 0.2*!maxlike,
     condvarno = 0, condname = "", firstg = 0.2, reduceg = 0.5,
     cond = NA, findiff = FALSE, seed = NULL,
     prML = 1, maximumPermutationLength = 40,
     minimumPermutationLength = 2, initialPermutationLength = 20,
     modelType = NULL, behModelType = NULL, mult = 5, simOnly = FALSE,
     localML = FALSE, truncation = 5, doubleAveraging = 0,
     standardizeVar = (diagonalize<1), lessMem = FALSE, silent = FALSE)

Arguments

For set_model_saom:

modelType	Named vector indicating the type of model to be fitted for dependent network variables. (See the examples below for how to specify a named vector.) Possible values are: 1 = directed standard, 2:6 for symmetric networks only: 2 = dictatorial forcing (D.1), 3 = Initiative model with reciprocal confirmation (M.1), 4 = Pairwise dictatorial forcing model (D.2), 5 = Pairwise mutual model (M.2), 6 = Pairwise joint model (C.2), 7:10 for directed one-mode only: 7 = Double Step model with double step probability 0.25, 8 = Double Step model with double step probability 0.50, 9 = Double Step model with double step probability 0.75, 10 = Double Step model with double step probability 1.00, 11 = Contemporaneous evaluation statistics model. Names should be the names of all dependent network variables, in the same order as in the Siena data set. See Snijders and Pickup (2016) for the meanings of the various models for symmetric networks. Default NULL implies 1 for directed or two-mode, 2 for symmetric.
behModelType	Named vector indicating the type of model to be fitted for behavioral dependent variables. (See the examples below for how to specify a named vector.) Possible values are: 1 = standard (restricted), 2 = absorbing. Names should be the names of all dependent behavioral variables, in the same order as in the Siena data set. Default NULL implies values 1.
MaxDegree	Named vector of maximum degree values for corresponding networks. Allows to restrict the model to networks with degrees not higher than this maximum. Names should be the names of all dependent network variables, in the same order as in the Siena data set. Default as well as value 0 imply no restrictions. This option is not available for maximum likelihood estimation.
Offset	Named vector of offset values for symmetric networks with modelType = 3 (M.1), and for universal setting in Settings model. Names should be the names of all dependent network variables, in the same order as in the Siena data set. Default NULL implies values 0.

For set_algorithm_saom:

maxlike	Whether to use maximum likelihood method or Method of Moments estimation.
gmm	Whether to use the Generalized Method of Moments or the regular Method of Moments estimation.
cond	Boolean. Only relevant for Method of Moments simulation/estimation. If TRUE, use conditional simulation; if FALSE, unconditional simulation. If missing, decision is deferred until siena, when it is set to TRUE if there is only one dependent variable, FALSE otherwise.
condvarno	If cond (conditional simulation), the sequential number of the network or behavior variable on which to condition.
condname	If conditional, the name of the dependent variable on which to condition. Use one or other of condname or condvarno to specify the variable.
simOnly	Logical: If TRUE, then the calculation of the covariance matrix and standard errors of the estimates at the end of Phase 3 of the estimation algorithm is skipped. This is suitable if nsub = 0 and siena is used only for the purpose of simulation.
targets	Numeric vector of length equal to the number of estimated parameters, meant to supersede the targets calculated from the data set; see "Details". Not for regular use.
thetaValues	If not NULL, this should be a matrix with parameter values to be used in Phase 3. The number of columns must be equal to the number of estimated parameters in the effects object (if conditional estimation is used, without the rate parameters for the conditioning dependent variable). Can only be used if simOnly=TRUE.
seed	Integer. Starting value of random seed.
n3	Number of iterations in phase 3. For regular use with the Method of Moments, n3 = 1000 mostly suffices. For use in publications and for Maximum Likelihood, at least n3 = 3000 is advised. Sometimes much higher values are required for stable estimation of standard errors.
nsub	Number of subphases in phase 2.
n2start	Minimum number of iterations in subphase 1 of phase 2; default is 2.52*(p+7), where p = number of estimated parameters; if useCluster = TRUE in the call of siena07, this is divided by nbrNodes.
firstg	Initial value of scaling ("gain") parameter for updates in the Robbins-Monro procedure.
reduceg	Reduction factor for scaling ("gain") parameter for updates in the Robbins-Monro procedure (MoM only).
truncation	Used for step truncation in the Robbins Monro algorithm (applied to deviate/(standard deviation)).
doubleAveraging	subphase after which double averaging is used in the Robbins Monro algorithm, which probably increases algorithm efficiency.
diagonalize	Number between 0 and 1 (bounds included), values outside this interval will be truncated; for diagonalize = 0 the complete estimated derivative matrix will be used for updates in the Robbins-Monro procedure; for diagonalize = 1 only the diagonal entries will be used; for values between 0 and 1, the weighted average will be used with weight diagonalize for the diagonalized matrix. Has no effect for ML estimation. Higher values are more stable, lower values potentially more efficient. Default: for ML estimation, diagonalize = 0; for MoM estimation, diagonalize = 0.2.
standardizeVar	Logical: whether to limit deviations used in Robbins-Monro updates to unit variances.
dolby	Boolean. Should there be noise reduction by regression on augmented data score. In most cases dolby = TRUE yields better convergence, but takes some extra computing time; if convergence is problematic, however, dolby = FALSE may be tried. Just use whatever works best.
splitDepvars	Integer with possible values -1, 0, +1. If -1, obtain results as in versions prior to 1.3.6. If +1, Robbins-Monro updates for a given dependent variable will not depend on deviations for other dependent variables. See Details.
useStdInits	Boolean. If TRUE, the initial values in the effects object will be ignored and default values used instead. If FALSE, the initial values in the effects object will be used.
findiff	Boolean: If TRUE, estimate derivatives using finite differences. If FALSE, use scores.
mult	Multiplication factor for maximum likelihood and Bayes. Number of steps per iteration is set to this multiple of the total distance between the observations at start and finish of the wave (and rounded). Decreasing mult below a certain value has no further effect. mult can be either a number (which needs to be positive) or a vector of numbers, of length equal to the total number of periods. Note that for multi-group data, the total number of periods is equal to the number of groups times the number of periods per group (if the latter is constant).

Algorithm parameters only relevant for maximum likelihood and Bayesian estimation:

prML	Either one real number, or a vector of 7 numbers. Determines update probabilities used in Metropolis-Hastings routine in ML estimation. Should be nonnegative; if a vector, the sum should be < = 1. See Details.
maximumPermutationLength	Maximum length of permutation in steps in ML estimation.
minimumPermutationLength	Minimum length of permutation in steps in MLestimation.
initialPermutationLength	Initial length of permutation in steps in MLestimation.
localML	Logical: If TRUE, and maxlike, then calculations are sped up for models with all local effects.

For set_output_saom:

outputName	If outputName = NULL and the Siena data set has name dataName, output will be written by siena to a file with name dataName_out.txt in the working directory, appending if this file already exists. If outputName is not NULL, it should be a character string without embedded spaces, and output will be written to a file with name outputName_out.txt.
lessMem	Logical: whether to reduce storage during operation of siena, and of the object produced, by leaving out arrays by iteration and by period of simulated statistics sf2 and scores ssc. if lessMem = TRUE, it will be impossible to run test_time or test_gof on the object produced by siena.
returnThetas	Boolean: whether to return theta values and generated estimation statistics of Phase 2 runs.
returnChains	Boolean. Whether to return the chains generated in the Phase 3 runs.
returnDataFrame	Boolean. Whether to return the chains as lists or data frames.
returnChangeContributions	Boolean. Whether to return the change contributions. See interpret_size_dynamics.

And additional, for sienaAlgorithmeCreate:

fn	Function to do one simulation in the Robbins-Monro algorithm. Not to be touched.
projname	Character string name of project; the output file will be called projname.txt. No embedded spaces!!! If projname = NULL, output will be written to a file in the temporary session directory, created as tempfile(Siena).
silent	Logical: whether to give a note about the output file.

Details

Model specification is done via this object for siena, which calls function simstats0c. This function creates an object with the elements required to control the Robbins-Monro algorithm. Those not available as arguments can be changed manually when desired.
The matrix D transforming deviations from targets to updates in the Robbins Monro steps are partially diagonalized if diagonalize > 0; and its between-dependent variable blocks are put to 0 if splitDepvars=1. Diagonalization is omitted for the update step immediately at the end of Phase if splitDepvars=-1.

The value prML = 1 defines the defaults valid in RSiena up to version 1.3.16. For ML estimation with only one dependent variable, prML = 2 may be more efficient.
If prML is given as a vector of 7 probabilities, these are, consecutively: the probabilities of inserting a diagonal step, deleting a diagonal step, permuting, inserting a CCP, deleting a CCP, inserting random missing, deleting random missing; the residual (1 minus the sum) is the probability of a move step.
Further information about the implementation of the algorithm is in
https://www.stats.ox.ac.uk/~snijders/siena/Siena_algorithms.pdf.
Some of the examples use projname = NULL; this is just for the sake of checking the examples, not necessarily intended for normal use.

Value

set_model_saom returns an object of class sienaModel, set_algorithm_saom returns an object of class sienaAlgorithmSettings, set_output_saom returns an object of class sienaOutputOptions, and sienaAlgorithmCreate returns an object of class
sienaAlgorithm, all being lists containing values implied by the parameters.

Author(s)

Ruth Ripley and Tom A.B. Snijders

References

For modelType:
Snijders, T.A.B., and Pickup, M. (2016), Stochastic Actor-Oriented Models for Network Dynamics. In: Victor, J.N., Lubell, M., and Montgomery, A.H., Oxford Handbook of Political Networks. Oxford University Press.

Also see https://www.stats.ox.ac.uk/~snijders/siena/

See Also

siena, simstats0c.

Examples

CondAlgorithm <- set_algorithm_saom(cond = TRUE, condvarno = 1)
Max10Model <- set_model_saom(MaxDegree = c(mynet = 10),
                                modelType = c(mynet = 1))
Beh2Model <- set_model_saom(behModelType = c(mybeh = 2))
# where mynet is the name of the network object
# created by as_dependent_rsiena,
# and mybeh the name of the behavior object created by the same function.
Algorithm2 <- set_algorithm_saom(nsub = 2, n2start = 2000)
OutAlgorithm <- set_output_saom(outputName = "LaterEstimation",
                        returnThetas = TRUE)

RSiena documentation built on April 20, 2026, 5:07 p.m.