Ported the example term to the ergm 4.0 API and documentation system.

references #3

.Rbuildignore

@@ -1,5 +1,23 @@
+^Meta$
+^doc$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+.RSession
+^.*/\.RData$
+^.*/\.Rhistory
+^.*/Rplots.pdf
+^.*/figure/
 .travis.yml
 appveyor.yml
+.*\.orig$
+.*\.rej$
+.gdb_history
 ^revdep$
+^.github$
+^man-roxygen$
+^codecov\.yml$
+^vignettes/.*_cache$
+^vignettes/.*_files$
+^README.md$
+_snaps
+^src/.*\.s?o$

DESCRIPTION

@@ -1,22 +1,25 @@
 Package: ergm.userterms
-Version: 3.10.0-111
+Version: 4.0.0
 Date: 2019-05-15
-Title:  User-specified Terms for the statnet Suite of Packages
+Title: User-specified Terms for the statnet Suite of Packages
 Authors@R: c(
 	   person("Mark S.", "Handcock", role=c("aut"), email="handcock@stat.ucla.edu"),
            person("David R.", "Hunter", role=c("aut"), email="dhunter@stat.psu.edu"),
    	   person("Carter T.", "Butts", role=c("aut"), email="buttsc@uci.edu"),
            person("Steven M.", "Goodreau", role=c("aut"), email="goodreau@u.washington.edu"),
-           person("Pavel N.", "Krivitsky", role=c("aut","cre"), email="pavel@uow.edu.au", comment=c(ORCID="0000-0002-9101-3362")),
+           person("Pavel N.", "Krivitsky", role=c("aut","cre"), email="pavel@statnet.org", comment=c(ORCID="0000-0002-9101-3362")),
      	   person("Martina", "Morris", role=c("aut"), email="morrism@u.washington.edu"))
 Depends:
-    network (>= 1.15),
-    ergm (>= 3.10.1)
+    network (>= 1.19),
+    ergm (>= 4.8.0)
 Imports:
-    statnet.common (>= 4.2.0)
+    statnet.common (>= 4.11.0)
 LinkingTo:
     ergm
-Description:  A template package to demonstrate the use of user-specified statistics for use in 'ergm' models as part of the Statnet suite of packages.
+Description: A template package to demonstrate the use of user-specified statistics for use in 'ergm' models as part of the Statnet suite of packages.
 License: GPL-3 + file LICENSE
 URL: http://statnet.org
 BugReports: https://github.com/statnet/ergm.userterms/issues
+RoxygenNote: 7.3.2.9000
+Roxygen: list(markdown = TRUE)
+Encoding: UTF-8

R/InitErgmTerm.users.R

@@ -15,137 +15,76 @@
 # add all functions to the bottom of this file or have them in 
 # separate files (with the extension .R).
 #
-# This file contains 
-#    - a description of the input and output parameters to each
-#      InitErgmTerm function
-#    - a description of the input parameters that the C changestats
-#      function will receive
-#    - sample InitErgmTerm functions. These are identical from 
-#      "statnet"'s perspective.
+# See the Terms API vignette in the 'ergm' package for the latest API.
 #
 ######################################################################
 
 
-#  ------------------------------------------------------------------ 
-#   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.getmodel, so each InitErgmTerm function 
-#               must include the ... argument
-#  These inputs are automatically supplied by ergm.getmodel.
-#
-#  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.alpha=alpha), where alpha
-#                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).
-#
-
-
-#  ------------------------------------------------------------------------- 
-#   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 
-
-
-
 #  ------------------------------------------------------------------------- 
-#  Sample InitErgmTerm function(s)
-#  -------------------------------------------------------------------------- 
+#  Sample InitErgmTerm function(s) and annotated documentation
+#  --------------------------------------------------------------------------
 
-#  This InitErgmTerm function is for the mindegree term described
-#  in Hunter, Goodreau, and Handcock (2011), "ergm.userterms:  A
-#  Template Package for Extending statnet"
+### Define the name of the term in R; this will be used by
+### ergmTerm-general Roxygen2 template to construct the Rd file name
+### and other information:
+###
+#' @templateVar name mindegree
+#'
+### Provide a title and brief description:
+###
+#' @title Minimum Degree
+#'
+#' @description This term adds one network statistic to the model
+#'   being the number of nodes in the network of at least degree
+#'   `mindeg`. That is, the statistic equals the number of nodes
+#'   in the network with `mindeg` or more edges.  This term can
+#'   only be used with undirected networks.
+#'
+### Note the:
+###
+### * "#" in front of the name; this is to keep R CMD check from
+###    parsing the term.
+###
+### * "binary:" tag specifying that this is a binary version as
+###   opposed to a "valued:' one.
+###
+#' @usage
+#' # binary: mindegree(mindeg, by=NULL)
+#'
+### Parameters, using the same syntax as function documentation.
+###
+#' @param mindeg an integer giving the 
+#'
+#' @param by an optional argument specifying a vertex attribute (see
+#'   Specifying Vertex attributes and Levels (`?nodal_attributes`) for
+#'   details). If this is specified, then degrees are calculated using
+#'   the subnetwork consisting of only edges whose endpoints have the
+#'   same value of the `by` attribute.
+#'
+### Import the standard ergmTerm documentation template so that it
+### gets indexed in ?ergmTerm.
+###
+#' @template ergmTerm-general
+#'
+### Other items, e.g., more details, examples, see also, references.
+###
+#' @details This `InitErgmTerm` function is for the mindegree term
+#'   described by
+#'
+#'   Hunter DR, Goodreau SM, Handcock MS (2013).  `ergm.userterms`: A
+#'   Template Package for Extending `statnet`, *Journal of Statistical
+#'   Software* 52(2), 1-25, \doi{10.18637/jss.v052.i02}.
+#'
+#'   It has been further updated to use the latest \CRANpkg{ergm} APIs
+#'   and conventions.
+###
+### Specify term keywords; see ?ergmKeyword
+###
+#' @concept undirected
+#' @concept categorical nodal attribute
+#' @concept frequently-used
+###
+### No @export!
 InitErgmTerm.mindegree <- function(nw, arglist, ...) {
   a <- check.ErgmTerm(nw, arglist, directed=FALSE, bipartite=FALSE,
       varnames = c("mindeg", "by"),
@@ -169,8 +108,9 @@ InitErgmTerm.mindegree <- function(nw, arglist, ...) {
   }
   list(name = "mindegree",
       coef.names = coef.names,
-      pkgname = "ergm.userterms",
-      inputs = c(attrflag, a$mindeg, nodecov),
+      pkgname = "ergm.userterms", # Optional: usually autodetected.
+      iinputs = c(attrflag, a$mindeg, nodecov), # Integer inputs
+      # inputs =  Numeric (double) inputs (unused)
       dependence = TRUE,
       emptynwstats = (a$mindeg == 0) * network.size(nw)
   )

man-roxygen/ergmTerm-general.R

@@ -0,0 +1,15 @@
+#  File man-roxygen/ergmTerm-general.R in package ergm, part of the
+#  Statnet suite of packages for network analysis, https://statnet.org .
+#
+#  This software is distributed under the GPL-3 license.  It is free,
+#  open source, and has the attribution requirements (GPL Section 7) at
+#  https://statnet.org/attribution .
+#
+#  Copyright 2003-2025 Statnet Commons
+################################################################################
+#' <% name <- if(startsWith(name, "'")) substr(name, 2, 1000) else name %>
+#' @name <%= name %>-ergmTerm
+#' @rdname <%= ergm:::.term.rdname("ergmTerm", name) %>
+#' @seealso [`ergmTerm`] for index of model terms currently visible to the package.
+#'
+#' \Sexpr[results=rd,stage=render]{ergm:::.formatTermKeywords("ergmTerm", "<%= name %>", "subsection")}