From 79359f26404d023d84aeb3611e6c5b3c030a883f Mon Sep 17 00:00:00 2001 From: "Pavel N. Krivitsky" Date: Sat, 12 Oct 2024 23:24:36 +1100 Subject: [PATCH] Removed some vestigial comment blocks describing the Terms API, instead directing the user to the vignette. --- R/InitErgmTerm.R | 71 +----------------------- R/InitErgmTerm.bipartite.R | 8 ++- R/InitErgmTerm.dgw_sp.R | 111 +------------------------------------ 3 files changed, 9 insertions(+), 181 deletions(-) diff --git a/R/InitErgmTerm.R b/R/InitErgmTerm.R index bbcaf2488..273ac2a41 100644 --- a/R/InitErgmTerm.R +++ b/R/InitErgmTerm.R @@ -51,77 +51,8 @@ #========================================================================== ################################################################################ -# The functions initialize each ergm term, X, by -# 1) checking the validity of X and its arguments via and -# 2) setting appropiate values for each of the components in the returned list -# X is initialized for inclusion into a model that is specified by formula F and -# built via -# -# --PARAMETERS-- -# nw : the network given in formula F -# arglist : the arguments given with term X in formula F # -# --IGNORED PARAMETERS-- -# ... : ignored, but necessary to accomodate other arguments -# passed by -# -# --RETURNED-- -# a list of term-specific elements required by the C changestats -# functions and other R rountines; the first two components of this -# list are required*, the remaining components are optional: -# *name : the name of term X; this is used to locate the C function -# calculating the change statistics for X, which will be -# 'name' prepended with "d_"; for example if X=absdiff, -# 'name'="absdiff", and the C function is "d_absdiff" -# *coef.names: the vector of names for the coefficients (parameters) -# as they will be reported in the output -# inputs : the vector of (double-precision numeric) inputs that the -# changestat function called d_ will require -# (see WHAT THE C CHANGESTAT FUNCTION RECEIVES below); -# this MUST be a vector!; thus, if the inputs are matrices, -# they must be "flattened" to vectors; if they are categorical -# character-valued variables, they must be converted to numbers; -# optionally, 'inputs' may have an attribute named -# "ParamsBeforeCov",which is the number that used to be the -# old Element 1 and is needed for backwards compatability -# (see the old for details); default=NULL -# soname : the name of the package containing the C function called -# d_'name'; default="ergm" -# dependence : whether the addition of term X to the model makes the model -# into a dyadic dependence model (T or F); if all terms have -# 'dependence' set FALSE, the model is assumed to be a -# dyadic independence model; default=TRUE -# emptynwstats: the vector of values (if nonzero) for the statistics evaluated -# on the empty network; if all are zero for this term, this -# argument may be omitted. Example: If the degree0 term is -# among the statistics, this argument is unnecessary because -# degree0 = number of nodes for the empty network -# minpar : the vector of minimal valid values for each of the model's parameters -# maxpar : the vector of maximal valid values for each of the model's parameters -# params : a list whose names correspond to parameter values for curved exponential family model -# terms only; the items in the list are there for historical reasons and are ignored; -# map : a function taking two arguments, theta and length('params'), which -# gives the map from the canonical parameters, theta, to the curved -# parameters, eta; 'map' is only necessary for curved exponential -# family model terms -# gradient : a function taking two arguments, theta and length('params'), which -# gives the gradient of the eta map above as a p by q matrix, where -# p=length(theta), q=length(params); 'gradient' is only necessary -# for curved exponential family model terms -# offset : a logical value; if TRUE, forces the term to be an offset -# offsettheta : a logical vector length equal to the number of parameters; if TRUE, -# the corresponding parameter is forced to be an offset -# offsetmap : a logical vector length equal to the number of statistics; if TRUE, -# the corresponding statistic is forced to be an offset -# WHAT THE C CHANGESTAT FUNCTION RECEIVES: -# The changestat function, written in C and called d_'name', -# will have access to 'inputs'; this array will be called INPUT_PARAMS -# in the C code and its entries may accessed as INPUT_PARAMS[0], -# INPUT_PARAMS[1], and so on; the size of INPUT_PARAMS=N_INPUT_PARAMS, -# a value which is automatically set for you and which is available -# inside the C function; thus INPUT_PARAMS[N_INPUT_PARAMS-1] is the last -# element in the vector; note in particular that it is NOT necessary -# to add the number of inputs to 'inputs' since this is done automatically +# See the Terms API vignette for an up to date documentation of the terms API. # ################################################################################ diff --git a/R/InitErgmTerm.bipartite.R b/R/InitErgmTerm.bipartite.R index 52b925d2e..ca3650269 100644 --- a/R/InitErgmTerm.bipartite.R +++ b/R/InitErgmTerm.bipartite.R @@ -7,8 +7,12 @@ # # Copyright 2003-2024 Statnet Commons ################################################################################ -# See InitErgmTerm.R for a general explanation -# of InitErgmTerm functions + +################################################################################ +# +# See the Terms API vignette for an up to date documentation of the terms API. +# +################################################################################ # NOTE: a number of undocumented terms from this file have been removed # but the terms are retained on the experimental_terms svn branch diff --git a/R/InitErgmTerm.dgw_sp.R b/R/InitErgmTerm.dgw_sp.R index b7fb9dd60..ce495f262 100644 --- a/R/InitErgmTerm.dgw_sp.R +++ b/R/InitErgmTerm.dgw_sp.R @@ -8,117 +8,10 @@ # Copyright 2003-2024 Statnet Commons ################################################################################ -# ------------------------------------------------------------------ -# Description of the input and output parameters of the -# InitErgmTerm.xxx function, where xxx is the name of your term -# ------------------------------------------------------------------ -# -# INPUTS: -# Each InitErgmTerm function takes three arguments: -# nw: The network of interest -# arglist: The list of arguments passed to the term xxx -# ... : There may be other arguments passed by -# ergm_model, so each InitErgmTerm function -# must include the ... argument -# These inputs are automatically supplied by ergm_model. -# -# OUTPUTS: -# Each InitErgmTerm function should return a list. -# REQUIRED LIST ITEMS: -# name: This names the C changestats function for term xxx, -# but does so by excluding the d_ prefix. The -# changestats function is named d_xxxy and 'name' is -# consequently "xxxy". For example, the b1starmix -# term has 2 changestats functions based on -# whether the homophily argument is set. These are -# d_b1starmix and d_b1starmixhomophily. The 'name' -# returned by InitErgmTerm.b1starmix is then one of -# "b1starmix" or "b1starmixhomophily" as appropriate. -# coef.names: Vector of names for the coefficients (parameters) -# as they will be reported in the output. -# pkgname: This names the package containing the C changestats -# function d_[name]. The default is "ergm", which means -# that if you have code that exists as part of the -# (say) "ergm.userterms" package, you MUST specify -# pkgname="ergm.userterms" +################################################################################ # -# OPTIONAL LIST ITEMS: -# inputs: Vector of (double-precision numeric) inputs that the -# changestat function called d_'name' may require. -# The default is NULL; no inputs are required. But it -# MUST be a vector! Thus, if some of the inputs are, -# say, matrices, they must be "flattened" to vectors; if -# some are categorical character-valued variables, they -# must be converted to numbers. Optionally, the inputs -# vector may have an attribute named "ParamsBeforeCov", -# which is the number of input parameters preceding the -# covariate vector in 'inputs'. This is necessary for -# compatibility with some of the existing d_xxx changestats -# functions in ergm, but is not necessary in general. -# dependence: Logical variable telling whether addition of this term to -# the model makes the model into a dyadic dependence model. -# If none of the terms sets dependence==TRUE, then the model -# is assumed to be a dyadic independence model, which means -# that the pseudolikelihood estimate coincides with the -# maximum likelihood estimate. The default value is TRUE. -# emptynwstats: Vector of values (if nonzero) for the statistics evaluated -# on the empty network. If all are zero for this term, this -# argument may be omitted. For example, the degree0 term -# would require 'emptynwstats' since degree0 = number of -# nodes for the empty network. -# params: For curved exponential family model terms only, a list of -# (numeric) initial values for the parameters of -# curved exponential family model terms. Each item in the -# list should be named with the corresponding parameter name -# (one or more of these will probably coincide with the -# coef.names). For example, the gwesp term returns -# params=list(gwesp=NULL,gwesp.decay=decay), where decay -# was specified as an argument to the gwesp term. -# map: For curved exponential family model terms only, a function -# giving the map from the canonical parameters, theta, -# associated with the statistics for this term, to eta, -# the corresponding curved parameters. The length of eta -# is the same as the length of the 'params' list above. -# The function takes two arguments: theta and length(eta). -# gradient: For curved exponential family model terms only, a function -# giving the gradient of the 'map'. If theta has length p -# and eta has length q, then gradient should return a -# p by q matrix. This function takes two arguments: theta -# and length(eta). +# See the Terms API vignette for an up to date documentation of the terms API. # - - -# ------------------------------------------------------------------------- -# Description of the input parameters to the d_xxxy changestats function, -# where xxxy corresponds to the 'name' returned by InitErgmTerm.xxx. -# -------------------------------------------------------------------------- -# -# INPUTS: -# Each d_xxxy function takes five arguments: -# ntoggles: the number of toggles as described in -# "ergm.userterms: A template package" -# heads: a pointer to the array of the head nodes of the -# proposed edges to be toggled -# tails: a pointer to the array of the tail nodes of the -# proposed edges to be toggled -# mtp: a pointer to the model, which includes the following: -# dstats : a pointer to the array of changestats, -# macro-ed as CHANGE_STAT -# nstats : the length of 'dstats', macro-ed as -# N_CHANGE_STATS -# inputparams : a pointer to the vector of input -# parameters. This is supplied by the -# 'inputs' returned by InitErgmTerm.xxx -# and is macro-ed as INPUT_PARAM -# ninputparams: the length of 'inputparams', macro-ed -# as N_INPUT_PARAMS -# nwp: a pointer to the network. This includes several -# components and several macros exist for accessing -# these. See the changestat.h file for a list of these -# components and their macros. -# These inputs are automatically supplied to the d_xxxy function by the -# network_stats_wrapper function - ################################################################################ #Type codes are as follows (where (i,j) is the focal edge):