sienaRI: Functions to assess the relative importance of effects at...
In RSienaTest: Siena - Simulation Investigation for Empirical Network Analysis

Description Usage Arguments Details Value Author(s) References Examples

The function sienaRI returns the relative importance of effects of a SAOM according to the measure of relative importance described in Section 3.1 of Indlekofer and Brandes (2013). The measure is based on the influence of effects on potential tie change or behavior change decisions of individual actors at the given observation moments. It takes the data as well as the complete model specification into account. Therefore, necessary arguments are the analysed data given as a siena data object as well as the complete model specification represented either by an estimated sienaFit object or by the triple consisting of a suitable parameter vector theta and the corresponding sienaAlgorithm and sienaEffects objects.
Entropy-based effect sizes as in Snijders (2004) and the within-ego standard deviations of change statistics are also computed. If getChangeStats=TRUE, the arrays of change statistics are stored in the sienaRI object.

sienaRI(data, ans=NULL, theta=NULL, algorithm=NULL, effects=NULL,
        getChangeStats=FALSE)
## S3 method for class 'sienaRI'
print(x, printSigma=FALSE,...)
## S3 method for class 'sienaRI'
plot(x, actors = NULL, col = NULL, addPieChart = FALSE,
              radius = 1, width = NULL, height = NULL, legend = TRUE,
              legendColumns = NULL, legendHeight = NULL,
              cex.legend = NULL, cex.names = NULL,...)

`data`	`siena` data object representing the analyzed data and resulting from a call to `sienaDataCreate`.
`ans`	`sienaFit` object resulting from a call to `siena07`. The `sienaFit` object contains all necessary information on the model specification, in particular, the vector of parameter values `ans$theta`, the used algorithm for estimation `ans$x`, and information on included model effects `ans$effects`. If `ans` is a valid `sienaFit` object, the calculations of relative importances are based on `ans$theta`, `ans$x`, and `ans$effects`. Alternatively, the necessary information can be given directly as a suitable parameter vector `theta`, a `sienaAlgorithm` object, and a `sienaEffects` object. In this case, `ans` has to be unspecified (i.e., `ans=NULL`).
`theta`	Vector of parameter values of effects included in the model. Length of `theta` has to be equal to the number of included effects.
`algorithm`	`sienaAlgorithm` object as resulting from a call to `sienaAlgorithmCreate`. Works only for estimation by Method of Moments (i.e., if `maxlike = FALSE`).
`effects`	`sienaEffects` object specifying which effects are included the model. Note that `sienaRI` does not yet work for endowment or creation effect, i.e., included effects have to be of type `eval` (or `rate`).
`getChangeStats`	Boolean: If `TRUE`, an array of change statistics is added to the `sienaRI` object.
`x`	`sienaRI` object resulting from a call to `sienaRI`.
`printSigma`	Boolean: If `TRUE`, average within-ego standard deviations of change statistics ('`sigma`'), are included in the print.
`actors`	vector of integers: set of actors to be included in the plot; if `NULL`, all actors.
`col`	Colors used in the plot. If `col=NULL` a default color scheme is used.
`addPieChart`	Boolean: If `TRUE`, pie charts of aggregated relative importances for the complete set of actors will be added to the plot.
`radius`	Radius of pie charts. Only effective if `addPieCharts = TRUE`.
`width`	Width of the plot. If `width=NULL` a default value is used.
`height`	Height of the plot. If `height=NULL` a default value is used.
`legend`	Boolean: if `TRUE` a legend is added to the plot. `x$effectNames` are used as labels.
`legendColumns`	Number of columns in legend. If `legendColumns=NULL` a default value is used. Only effective if `legend=TRUE`.
`legendHeight`	Height of legend. If `legendHeight=NULL` a default value is used. Only effective if `legend=TRUE`.
`cex.legend`	Specifies the relative font size of legend labels.
`cex.names`	Specifies the relative font size of bar graph labels.
`...`	Other arguments.

sienaRI takes the data as well as the complete model specification into account. Therefore, necessary arguments are the analyzed data given as a siena data object as well as the complete model specification represented either by an estimated sienaFit object or by the triple consisting of a suitable parameter vector theta and the corresponding sienaAlgorithm and sienaEffects objects.

A sienaFit object contains all necessary information on the model specification, in particular, the vector of parameter values ans$theta, the used algorithm for estimation ans$x, and information on included model effects ans$effects.

If ans is a valid sienaFit object, the calculations of relative importances are based on ans$theta, ans$x, and ans$effects. Alternatively, the necessary information can be given directly as a suitable parameter vector theta, a sienaAlgorithm object, and a sienaEffects object. In this case, ans has to be unspecified, i.e., ans=NULL.

Note that sienaRI works only with Method of Moments (i.e., for sienaAlgorithm objects with maxlike = FALSE) and that it does not yet work for endowment or creation effects (i.e., included effects have to be of type eval), and also not for models with interaction effects. It does not allow two-mode (bipartite) networks as dependent variables; but these can be represented as one-mode networks using structural zeros. If the network is non-directed, the relative importances and entropy-based 'degrees of certainty' are calculated for modelType=2 ('forcing'; see sienaAlgorithmCreate).

If there are any missing tie values in the network data set, they are imputed by initial zeros and Last Observation Carried Forward. Structural zeros and ones are replaced by NA and treated as impossible choices in the probability vectors and ignored in the standard deviations; but the change statistics for these dyads still are given in changeStatistics (if requested).

If the model contains only one dependent variable, sienaRI returns an object of class sienaRI. Otherwise, it returns a list of objects of class sienaRI, each corresponding to one dependent variable.

A returned sienaRI object stores the expected relative importances of effects of one dependent variable at observation moments as defined in Section 3.1 of Indlekofer and Brandes (2013).

A sienaRI object is a list with the following components. For the components referred to as lists themselves, these are lists corresponding to the observation moments.

- dependentVariable: the name of the corresponding dependent variable.
- effectNames: the names of considered effects.
- RIActors: a list that contains the expected relative importances of effects for each potential actor decision at observation moments. This is equation (3) in Indlekofer and Brandes (2013).
- expectedRI: a list that contains the expected relative importances of effects aggregated over all actors for each network observation. These are the averages of the actor related values in RIActors. This is equation (4) in Indlekofer and Brandes (2013).
- IActors: a list that contains the expected importances of effects for each potential actor decision at observation moments. This is the numerator of equation (3) in Indlekofer and Brandes (2013).
- expectedI: is a list that contains the expected importances of effects aggregated over all actors in each observation. More precisely, it contains the averages of the actor related values in IActors.
- absoluteSumActors: a list that contains the sum of the (unstandardized) L1-differences calculated for each potential actor decision at observation moments. This is the denominator of equation (3) in Indlekofer and Brandes (2013).
- RHActors: a list that contains the degree of certainty in the potential ministep taken by an actor at the observation moments; this is R_H(i,x) of formula (6) in Snijders (2004). The mean over actors of these degrees of certainty, given by formula (7) in Snijders (2004), is printed by the print method for sienaRI objects.
- sigma: a list of effects by ego matrices of the values of the within-ego standard deviations of the change statistics. Their averages (over egos) are printed if printSigma=TRUE.
- changeStatistics: a list of arrays (effects by alters by egos) containing for each observation moment, the values of the change statistics for toggling the tie from actor to ego; this is produced only if getChangeStats=TRUE.

Natalie Indlekofer, some additions by Tom Snijders

Indlekofer, Natalie and Brandes, Ulrik (2013). Relative Importance of Effects in Stochastic Actor-oriented Models. Network Science, 1 (3), 278-304.
Snijders, Tom A.B. (2004). Explained Variation in Dynamic Network Models. Mathematics and Social Sciences, 168 (4), 31-41.

myalgorithm <- sienaAlgorithmCreate(nsub=1, n3=50)
mynet1 <- sienaDependent(array(c(tmp3, tmp4), dim=c(32, 32, 2)))
mydata <- sienaDataCreate(mynet1)
myeff <- getEffects(mydata)
myeff <- includeEffects(myeff, density, recip, transTies, nbrDist2)
ans <- siena07(myalgorithm, data=mydata, effects=myeff, batch=TRUE)

RI <- sienaRI(mydata, ans)
RI
## Not run: 
plot(RI, addPieChart=TRUE)
plot(RI, actors=1:20, addPieChart=TRUE, radius=1.08)

## End(Not run)

myalgorithm <- sienaAlgorithmCreate(nsub=1, n3=50)
mynet2 <- sienaDependent(array(c(s502, s503), dim=c(50, 50, 2)))
mybeh <- sienaDependent(s50a[,2:3], type="behavior")
mydata2 <- sienaDataCreate(mynet2, mybeh)
myeff2 <- getEffects(mydata2)
myeff2 <- includeEffects(myeff2, density, recip, transTies)
ans2 <- siena07(myalgorithm, data=mydata2, effects=myeff2, batch=TRUE)
# Use only the parameters for the evaluation function:
theta.eval <- ans2$theta[myeff2$type[myeff2$include]=="eval"]
RI <- sienaRI(mydata2, theta=theta.eval, algorithm=myalgorithm,
              effects = myeff2)
RI
## Not run: 
plot(RI[[2]], col = c("red", "green"), legend=FALSE)
plot(RI[[1]], addPieChart = TRUE, legendColumns=2)

## End(Not run)