# 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 | # |

102 | InitErgmTerm.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" |

114 | InitErgmTerm.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 | # |

136 | InitErgmTerm.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 |