Skip to content

Commit

Permalink
Removed some vestigial comment blocks describing the Terms API, inste…
Browse files Browse the repository at this point in the history 
…ad directing the user to the vignette.
  • Loading branch information
@krivit
krivit committed Oct 12, 2024
1 parent 096a5f6 commit 79359f2
Show file tree
Hide file tree
Showing 3 changed files with 9 additions and 181 deletions.
71 changes: 1 addition & 70 deletions R/InitErgmTerm.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,77 +51,8 @@
#==========================================================================

################################################################################
# The <InitErgmTerm.X> functions initialize each ergm term, X, by
# 1) checking the validity of X and its arguments via <check.ErgmTerm> 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 <ergm_model>
#
# --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 <ergm_model>
#
# --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_<name> 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 <InitErgm> 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.
#
################################################################################

Expand Down
8 changes: 6 additions & 2 deletions R/InitErgmTerm.bipartite.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
111 changes: 2 additions & 109 deletions R/InitErgmTerm.dgw_sp.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down

0 comments on commit 79359f2

Please sign in to comment.