sienaRI: Functions to assess the relative importance of effects at...

Description Usage Arguments Details Value Author(s) References Examples

View source: R/sienaRI.r

Description

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.

Usage

1
2
3
4
5
6
7
8
9
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,...)

Arguments

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.

Details

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).

Value

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.

Author(s)

Natalie Indlekofer, some additions by Tom Snijders

References

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
myalgorithm <- sienaAlgorithmCreate(nsub=1, n3=50, projname=NULL)
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, projname=NULL)
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)

Example output

Warning message:
no DISPLAY variable so Tk is not available 
siena07 will create an output file /work/tmp/tmp/RtmpH1ueQx/Siena3698a74769b390.txt .
This is a temporary file for this R session.
  effectName                 include fix   test  initialValue parm
1 outdegree (density)        TRUE    FALSE FALSE   -0.56039   0   
2 reciprocity                TRUE    FALSE FALSE    0.00000   0   
3 transitive ties            TRUE    FALSE FALSE    0.00000   0   
4 number of actors at dist 2 TRUE    FALSE FALSE    0.00000   0   

Start phase 0 
theta: -0.56  0.00  0.00  0.00 

Start phase 1 
Phase 1 Iteration 1 Progress: 0%
Phase 1 Iteration 2 Progress: 0%
Phase 1 Iteration 3 Progress: 1%
Phase 1 Iteration 4 Progress: 1%
Phase 1 Iteration 5 Progress: 1%
Phase 1 Iteration 10 Progress: 2%
Phase 1 Iteration 15 Progress: 3%
Phase 1 Iteration 20 Progress: 4%
Phase 1 Iteration 25 Progress: 5%
Phase 1 Iteration 30 Progress: 6%
Phase 1 Iteration 35 Progress: 7%
Phase 1 Iteration 40 Progress: 8%
Phase 1 Iteration 45 Progress: 9%
Phase 1 Iteration 50 Progress: 9%
theta: -0.7531  0.5537  0.2647 -0.0822 

Start phase 2.1
Phase 2 Subphase 1 Iteration 1 Progress: 48%
Phase 2 Subphase 1 Iteration 2 Progress: 48%
theta -0.804  0.855  0.390 -0.131 
ac -0.276  1.366  3.693  0.157 
Phase 2 Subphase 1 Iteration 3 Progress: 48%
Phase 2 Subphase 1 Iteration 4 Progress: 48%
theta -1.061  1.820  0.752 -0.303 
ac 0.139 1.124 1.323 0.203 
Phase 2 Subphase 1 Iteration 5 Progress: 48%
Phase 2 Subphase 1 Iteration 6 Progress: 49%
theta -1.445  2.425  1.053 -0.371 
ac 0.881 0.836 1.371 0.361 
Phase 2 Subphase 1 Iteration 7 Progress: 49%
Phase 2 Subphase 1 Iteration 8 Progress: 49%
theta -1.730  2.515  1.170 -0.358 
ac 0.866 0.740 1.083 0.362 
Phase 2 Subphase 1 Iteration 9 Progress: 49%
Phase 2 Subphase 1 Iteration 10 Progress: 49%
theta -2.050  2.679  1.304 -0.316 
ac 0.861 0.465 1.097 0.327 
theta -2.204  2.179  1.474 -0.264 
ac  0.0302 -0.2485 -0.1302 -0.2562 
theta: -2.204  2.179  1.474 -0.264 

Start phase 3 

  Expected relative importance of effects for dependent variable 'mynet1' at observation moments:


                                                               wave 1    wave 2    
 
  1. eval outdegree (density)                                  0.3490    0.3096  
  2. eval reciprocity                                          0.2228    0.2206  
  3. eval transitive ties                                      0.1771    0.2259  
  4. eval number of actors at dist 2                           0.2511    0.2439  


  Expected importance of effects for this dependent variable:

  1. eval outdegree (density)                                  0.8611    0.7320  
  2. eval reciprocity                                          0.5441    0.5303  
  3. eval transitive ties                                      0.5184    0.6259  
  4. eval number of actors at dist 2                           0.5891    0.5081  


 R_H ('degree of certainty')                                   0.2726    0.2483  
siena07 will create an output file /work/tmp/tmp/RtmpH1ueQx/Siena3698a72b52b6c1.txt .
This is a temporary file for this R session.
  effectName          include fix   test  initialValue parm
1 outdegree (density) TRUE    FALSE FALSE   -1.44421   0   
2 reciprocity         TRUE    FALSE FALSE    0.00000   0   
3 transitive ties     TRUE    FALSE FALSE    0.00000   0   

Start phase 0 
theta:  4.329 -1.444  0.000  0.000  0.849  0.316  0.000 

Start phase 1 
Phase 1 Iteration 1 Progress: 0%
Phase 1 Iteration 2 Progress: 0%
Phase 1 Iteration 3 Progress: 0%
Phase 1 Iteration 4 Progress: 1%
Phase 1 Iteration 5 Progress: 1%
Phase 1 Iteration 10 Progress: 1%
Phase 1 Iteration 15 Progress: 2%
Phase 1 Iteration 20 Progress: 3%
Phase 1 Iteration 25 Progress: 4%
Phase 1 Iteration 30 Progress: 4%
Phase 1 Iteration 35 Progress: 5%
Phase 1 Iteration 40 Progress: 6%
Phase 1 Iteration 45 Progress: 7%
Phase 1 Iteration 50 Progress: 7%
theta:  4.5425 -1.7103  0.7776  0.3807  0.9140  0.1854 -0.0819 

Start phase 2.1
Phase 2 Subphase 1 Iteration 1 Progress: 59%
Phase 2 Subphase 1 Iteration 2 Progress: 59%
theta  4.607 -1.875  1.354  0.663  1.057  0.132 -0.141 
ac 1.791 0.488 1.705 2.282 1.257 1.106 0.647 
Phase 2 Subphase 1 Iteration 3 Progress: 59%
Phase 2 Subphase 1 Iteration 4 Progress: 59%
theta  4.6518 -2.1916  2.0351  0.7737  1.4830  0.0431 -0.3163 
ac 0.270 1.488 1.411 0.620 1.369 1.255 0.684 
Phase 2 Subphase 1 Iteration 5 Progress: 59%
Phase 2 Subphase 1 Iteration 6 Progress: 59%
theta  4.80607 -2.46159  2.49309  0.99108  1.79058  0.00464 -0.39247 
ac -0.0717  1.3668  1.2873  0.5206  0.9508  1.0438  0.6731 
Phase 2 Subphase 1 Iteration 7 Progress: 59%
Phase 2 Subphase 1 Iteration 8 Progress: 60%
theta  4.904 -2.608  2.514  0.973  1.747  0.201 -0.429 
ac -0.045  1.433  1.325  0.657  0.979  1.121  0.484 
Phase 2 Subphase 1 Iteration 9 Progress: 60%
Phase 2 Subphase 1 Iteration 10 Progress: 60%
theta  4.890 -2.722  2.531  1.051  1.733  0.316 -0.348 
ac -0.0795  1.4296  1.2773  0.4994  0.8809  1.1221  0.4873 
theta  6.058 -3.136  2.804  1.359  1.478  0.461 -0.452 
ac -0.0404 -0.0721 -0.3706 -0.3859  0.0887  0.1223 -0.0297 
theta:  6.058 -3.136  2.804  1.359  1.478  0.461 -0.452 

Start phase 3 
more than one dependent variable
 return value is therefore not of class 'sienaRI'
 but a list of objects of class 'sienaRI'.
[[1]]

  Expected relative importance of effects for dependent variable 'mynet2' at observation moments:


                                                               wave 1    wave 2    
 
  1. eval outdegree (density)                                  0.4940    0.4638  
  2. eval reciprocity                                          0.2960    0.3412  
  3. eval transitive ties                                      0.2100    0.1950  


  Expected importance of effects for this dependent variable:

  1. eval outdegree (density)                                  1.0860    1.0152  
  2. eval reciprocity                                          0.7581    0.8662  
  3. eval transitive ties                                      0.5713    0.5264  


 R_H ('degree of certainty')                                   0.4650    0.4215  

[[2]]

  Expected relative importance of effects for dependent variable 'mybeh' at observation moments:


                                                               wave 1    wave 2    
 
  1. eval mybeh linear shape                                   0.3866    0.3825  
  2. eval mybeh quadratic shape                                0.6134    0.6175  


  Expected importance of effects for this dependent variable:

  1. eval mybeh linear shape                                   0.2003    0.1953  
  2. eval mybeh quadratic shape                                0.4107    0.4123  


 R_H ('degree of certainty')                                   0.1494    0.1547  

RSiena documentation built on Sept. 24, 2020, 3 p.m.