Resources: InitErgmTerm.users.R

File InitErgmTerm.users.R, 8.2 KB (added by lxwang, 5 years ago)
Line 
1#################################################################
2#
3# !!USERS: READ THIS FIRST!!
4#
5# This is a file of examples. You can either add all functions to the bottom
6# of this file or have them in separate files (with the extension .R).
7# There are identical from "statnet"'s perspective.
8#
9# Each term must have its own InitErgmTerm function. This file contains
10# sample functions.
11#################################################################
12#
13# InitErgmTerm functions
14#
15# INPUT:
16# Each InitErgmTerm function takes two arguments, nw and arglist,
17# which are automatically supplied by ergm.getmodel.  There may be
18# other arguments passed by ergm.getmodel, so each InitErgmTerm
19# function must also include the ... argument in its list.
20#
21# OUTPUT:
22# Each InitErgmTerm function should return a list. 
23#    REQUIRED LIST ITEMS:
24#          name: Name of the C function that produces the change
25#                statistics.  (Note:  The name will have "d_"
26#                prepended.  For example, the C function for the
27#                absdiff change statistics is called "d_absdiff"
28#                even though InitErgmTerm.absdiff only returns
29#                names = "absdiff")
30#    coef.names: Vector of names for the coefficients (parameters)
31#                as they will be reported in the output.
32#
33#    OPTIONAL LIST ITEMS:
34#        inputs: Vector of (double-precision numeric) inputs that the
35#                changestat function called d_<name> will require
36#                (see WHAT THE C CHANGESTAT FUNCTION RECEIVES below).
37#                The default is NULL; no inputs are required.  But it MUST
38#                be a vector!  Thus, if some of the inputs are, say, matrices,
39#                they must be "flattened" to vectors; if some are categorical
40#                character-valued variables, they must be converted to numbers.
41#                Optionally, the inputs vector may have an attribute named
42#                "ParamsBeforeCov", which is the
43#                number that used to be the old Element 1 (number of input
44#                parameters BEFORE the beginning of the covariate vector)                                                         
45#                when using the old InitErgm specification; see the comment
46#                at the top of the InitErgm.R file for details.  This
47#                ParamsBeforeCov value is only necessary for compatibility
48#                with some of the existing d_xxx changestatistic functions.
49#        soname: This is the (text) name of the package containing the C function
50#                called d_[name].  Default is "ergm"
51#    dependence: Logical variable telling whether addition of this term to
52#                the model makes the model into a dyadic dependence model.
53#                If none of the terms sets dependence==TRUE, then the model
54#                is assumed to be a dyadic independence model, which means
55#                that the pseudolikelihood estimate coincides with the
56#                maximum likelihood estimate.  Default value:  TRUE
57#  emptynwstats: Vector of values (if nonzero) for the statistics evaluated
58#                on the empty network.  If all are zero for this term, this
59#                argument may be omitted.  Example:  If the degree0 term is
60#                among the statistics, this argument is necessary because
61#                degree0 = number of nodes for the empty network.
62#        params: For curved exponential family model terms only: This argument
63#                is a list:  Each item in the list should be named with the
64#                corresponding parameter name (one or more of these will
65#                probably coincide with the coef.names used when
66#                initialfit=TRUE; the initial values of such parameter values
67#                will be set by MPLE, so their values in params are ignored.)
68#                Any parameter not having its initial value set by MPLE
69#                should be given its initial value in this params list.
70#           map: For curved exponential family model terms only: A function
71#                that gives the map from theta (the canonical
72#                parameters associated with the statistics for this term)
73#                to eta (the corresponding curved parameters).  The length
74#                of eta is the same as the length of the params list above.
75#                This function takes two args:  theta and length(eta).
76#      gradient: For curved exponential family model terms only: A function
77#                that gives the gradient of the eta map above.
78#                If theta has length p and eta has length q, then gradient
79#                should return a p by q matrix.
80#                This function takes two args:  theta and length(eta).
81#
82# WHAT THE C CHANGESTAT FUNCTION RECEIVES:
83#                The changestat function, written in C and called d_<name>,
84#                where <name> is the character string passed as the required
85#                output item called "name" (see above), will have access to
86#                the vector of double-precision values created by the
87#                InitErgmTerm function as the optional output item called
88#                "inputs".  This array will be called INPUT_PARAMS in the C
89#                code and its entries may accessed as INPUT_PARAMS[0],
90#                INPUT_PARAMS[1], and so on.  The size of the INPUT_PARAMS
91#                array is equal to N_INPUT_PARAMS, a value which is
92#                automatically set for you and which is available inside the
93#                C function.  Thus INPUT_PARAMS[N_INPUT_PARAMS-1] is the last
94#                element in the vector. Note in particular that it is NOT
95#                necessary to add the number of inputs to the "inputs" vector
96#                since this is done automatically.
97
98#
99# A simple example
100# This is identical to the "edges" term already in "ergm"
101#
102InitErgmTerm.testme <- function(nw, arglist, ...) {
103  # Construct the output list
104  list(name="testme",             #name: required
105       coef.names = "testme",     #coef.names: required
106       inputs = NULL,             #There are no extra inputs for this term
107       soname = "ergmuserterms",  # So "ergm" knows where to find it!
108       dependence = FALSE # So we don't use MCMC if not necessary
109       )
110}
111#
112# A longer example
113# This is identical to the 2-star term already in "ergm"
114InitErgmTerm.m2star <- function(nw, arglist, ...) {
115#
116  # Check the network and arguments to make sure they are appropriate.
117  # make sure that the network is directed
118  a <- check.ErgmTerm(nw, arglist, directed=TRUE, bipartite=NULL,
119                      varnames = NULL,
120                      vartypes = NULL,
121                      defaultvalues = list(),
122                      required = NULL)
123  # Construct the output list
124  list(name="m2star",             #name: required
125       coef.names = "m2star",     #coef.names: required
126       inputs = NULL,             #There are no extra inputs for this term
127       soname = "ergmuserterms",  # So "ergm" knows where to find it!
128       dependence = TRUE # So we need to use MCMC
129       )
130}
131
132#
133# An example with covariates
134# This is identical to the "absdiff" term already in "ergm"
135#
136InitErgmTerm.absdiffme <- function(nw, arglist, ...) {
137  # Check the network and arguments to make sure they are appropriate.
138  a <- check.ErgmTerm(nw, arglist, directed=NULL, bipartite=NULL,
139                          varnames = c("attrname"),
140                          vartypes = c("character"),
141                          defaultvalues = list(NULL),
142                          required = c(TRUE)) 
143  assignvariables(a) # create local variables from names in 'varnames'
144  # Process the arguments
145  nodecov <- get.node.attr(nw, attrname)
146  ### Construct the list to return
147  list(name="absdiffme",                                     #name: required
148       coef.names = paste("absdiffme", attrname, sep="."), #coef.names: required
149       inputs = nodecov,  # We need to include the nodal covariate for this term
150       dependence = FALSE # So we don't use MCMC if not necessary
151       )
152}
153
154# See R/InitErgmTerm.R in the source distribution of the "ergm"
155# package for more examples.
156