From 9ddcc22591bedd2fe40d88609a0ee3f86e851e68 Mon Sep 17 00:00:00 2001 From: "Pavel N. Krivitsky" Date: Mon, 10 Feb 2025 20:13:23 +1100 Subject: [PATCH] Roxygenized the documentation and updated. references statnet/ergm.userterms#3 --- DESCRIPTION | 2 +- NAMESPACE | 10 +- R/ergm.userterms-package.R | 147 ++++++++++++++++++++++++++ R/zzz.R | 2 + inst/CITATION | 50 ++++----- man/ergm.userterms-package.Rd | 194 +++++++++++++++------------------- man/eut-upgrade.Rd | 113 ++++++++++---------- 7 files changed, 318 insertions(+), 200 deletions(-) create mode 100644 R/ergm.userterms-package.R diff --git a/DESCRIPTION b/DESCRIPTION index 4b4cab5..b5c7bdf 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -16,7 +16,7 @@ Imports: 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 non-CRAN 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 diff --git a/NAMESPACE b/NAMESPACE index c9b1f50..c64dbac 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,8 +1,6 @@ +# Generated by roxygen2: do not edit by hand +import(ergm) +import(network) +import(statnet.common) useDynLib(ergm.userterms) - -import(network,ergm) -importFrom(statnet.common, statnetStartupMessage) - -# Export all names -exportPattern(".") diff --git a/R/ergm.userterms-package.R b/R/ergm.userterms-package.R new file mode 100644 index 0000000..fdc84e5 --- /dev/null +++ b/R/ergm.userterms-package.R @@ -0,0 +1,147 @@ +#' User-defined terms used in Exponential Family Random Graph Models +#' +#' This non-CRAN package contains template code for user defined (change) statistics +#' that can be used with the \CRANpkg{statnet} suite of packages (and \CRANpkg{ergm} in +#' particular). To use this package the \CRANpkg{statnet} packages \CRANpkg{ergm} and +#' \CRANpkg{network} are required. +#' +#' As background, \CRANpkg{statnet} is a suite of software packages for statistical +#' network analysis. The packages implement recent advances in network modeling +#' based on exponential-family random graph models (ERGM). The components of +#' the package provide a comprehensive framework for ERGM-based network +#' modeling: tools for model estimation, for model evaluation, for model-based +#' network simulation, and for network visualization. This broad functionality +#' is powered by a central Markov chain Monte Carlo (MCMC) algorithm. The +#' coding is optimized for speed and robustness. For detailed information on +#' how to download and install the software, go to the \code{\link[ergm]{ergm}} +#' website: \url{statnet.org}. A tutorial, support newsgroup, references and +#' links to further resources are provided there. +#' +#' We have invested a lot of time and effort in creating the \code{statnet} +#' suite of packages for use by other researchers. Please cite it in all papers +#' where it is used. +#' +#' For complete citation information, use\cr +#' \code{citation(package="ergm")}. +#' +#' +#' @section Creating User-defined terms using this package: The \CRANpkg{statnet} +#' suite of packages allows the user to explore a large number of potential +#' models for their network data. These can be seen by typing +#' \code{?ergmTerm} (once the package \CRANpkg{ergm} has +#' been installed). For more information on the models and terms see Morris, +#' Handcock, and Hunter (2008). +#' +#' The purpose of the package is to allow additional terms can be coded up by +#' users (you!) and be used at native speeds with \CRANpkg{statnet}. So the suite +#' of packages can be extended with minimal work by the user. In addition the +#' core packages are not altered and so the new packages benefit from +#' improvements to the core suite. +#' +#' The process of creating new terms is explained in depth by the +#' document entitled by Hunter, Goodreau, and Handcock (2013) that is +#' found in the \file{inst/doc} directory of this package. While that +#' article is still valid, API changes in \CRANpkg{ergm} 4.0 have +#' simplified the term implementations and added new capabilities; see +#' the *Terms API* vignette in \CRANpkg{ergm}. +#' +#' In brief, to add a new term you need to (all file references are relative to +#' the package directory): +#' +#' 1. Download the source version of this package, currently hosted +#' at \url{https://github.com/statnet/ergm.userterms}, e.g., +#' \url{https://github.com/statnet/ergm.userterms/archive/refs/heads/master.zip}. +#' +#' 2. Unpack the source into a directory. +#' +#' 3. Optionally, rename the package name from \code{ergm.userterms} to some +#' something more evocative of its use (e.g., \code{myergm}). This can be done +#' using a global change to the files in the directory. Optionally, edit the +#' \file{DESCRIPTION} file to reflect the use of the package. +#' +#' 4. Edit \file{R/InitErgmTerm.users.R} to add \R \code{InitErgmTerm} +#' functions for the new terms. +#' +#' 5. Edit \file{src/changestats.users.c} to add \code{C} functions (like the +#' example already in that file) to compute the new change statistics. +#' +#' 6. Compile the package using the usual \R tools (e.g., \code{R CMD build +#' myergm} and \code{R CMD INSTALL myergm}). +#' +#' 7. Run it! It depends on \CRANpkg{ergm} and \CRANpkg{network}, of course. See the +#' example below. +#' @seealso [ergm-package], [network-package], [`ergmTerm`] +#' @references +#' 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}. +#' @keywords package models +"_PACKAGE" + + + + + +#' Updating \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} +#' prior to 3.1 +#' +#' Explanation and instructions for updating custom ERGM terms developed prior +#' to the release of \code{\link[=ergm-package]{ergm}} version 3.1 (including +#' 3.0--999 preview release) to be used with versions 3.1 or later. +#' +#' +#' @section Explanation: +#' +#' \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} --- +#' Statnet's mechanism enabling users to write their own ERGM terms --- comes +#' in a form of an R package containing files for the user to put their own +#' statistics into (i.e., \file{changestats.user.h}, \file{changestats.user.c}, +#' and \file{InitErgmTerm.user.R}), as well as some boilerplate to support them +#' (e.g., \file{ergm_edgetree.h}, \file{edgetree.c}, \file{ergm_changestat.h}, +#' \file{changestat.c}, etc.). +#' +#' Although the +#' \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} API is +#' stable, recent developments in ergm have necessitated the boilerplate files +#' in \pkg{ergm.userterms} to be updated. To reiterate, the user-written statistic +#' source code (\file{changestats.user.h}, \file{changestats.user.c}, and +#' \file{InitErgmTerm.user.R}) can be used without modification, but other +#' files that came with the package need to be changed. +#' +#' To make things easier in the future, we have implemented a mechanism (using +#' R's LinkingTo API, in case you are wondering) that will keep things in sync +#' in releases after the upcoming one. However, for the upcoming release, we +#' need to transition to this new mechanism. +#' @section Instructions: +#' +#' The transition entails the following steps. They only need to be done once +#' for a package. Future releases will keep up to date automatically. +#' +#' \enumerate{ +#' +#' \item Download the up-to-date +#' \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} +#' source \url{https://github.com/statnet/ergm.userterms}, e.g., +#' \url{https://github.com/statnet/ergm.userterms/archive/refs/heads/master.zip} +#' and unpack it. +#' +#' \item Copy the R and C files defining the user-written terms (usually +#' \file{changestats.user.h}, \file{changestats.user.c}, and +#' \file{InitErgmTerm.user.R}) and \emph{only} those files from the old +#' \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} source +#' code to the new. Do \emph{not} copy the boilerplate files that you did not +#' modify. +#' +#' \item If you have customized the package \file{DESCRIPTION} file (e.g., to +#' change the package name) or \file{zzz.R} (e.g., to change the startup +#' message), modify them as needed in the updated +#' \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}}, but do +#' \emph{not} simply overwrite them with their old versions. +#' +#' \item Make sure that your \code{\link[=ergm-package]{ergm}} installation is +#' up to date, and rebuild +#' \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}}. +#' +#' } +#' @name eut-upgrade +NULL diff --git a/R/zzz.R b/R/zzz.R index ea62bae..70897bb 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -7,6 +7,8 @@ # # Copyright 2012-2019 Statnet Commons ####################################################################### +#' @useDynLib ergm.userterms +#' @import ergm statnet.common network .onAttach <- function(lib, pkg){ sm <- statnetStartupMessage("ergm.userterms", c("statnet"), FALSE) if(!is.null(sm)){ diff --git a/inst/CITATION b/inst/CITATION index 799f8e4..dfa3c93 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -8,23 +8,23 @@ citHeader(paste0(sQuote("ergm.userterms"), " is part of the Statnet suite of pac # ---- END AUTOGENERATED STATNET CITATION ---- #' statnet: statnet.cite.pkg("ergm") # ---- BEGIN AUTOGENERATED STATNET CITATION ---- -bibentry("Manual", author = structure(list(list(given = "Mark S.", - family = "Handcock", role = "aut", email = "handcock@stat.ucla.edu", - comment = NULL), list(given = "David R.", family = "Hunter", +bibentry("Manual", author = structure(list(list(given = c("Mark", +"S."), family = "Handcock", role = "aut", email = "handcock@stat.ucla.edu", + comment = NULL), list(given = c("David", "R."), family = "Hunter", role = "aut", email = "dhunter@stat.psu.edu", comment = NULL), - list(given = "Carter T.", family = "Butts", role = "aut", - email = "buttsc@uci.edu", comment = NULL), list(given = "Steven M.", - family = "Goodreau", role = "aut", email = "goodreau@u.washington.edu", - comment = NULL), list(given = "Pavel N.", family = "Krivitsky", - role = c("aut", "cre"), email = "pavel@uow.edu.au", comment = c(ORCID = "0000-0002-9101-3362")), - list(given = "Martina", family = "Morris", role = "aut", - email = "morrism@u.washington.edu", comment = NULL)), class = "person"), - title = paste("ergm", ": ", "Fit, Simulate and Diagnose Exponential-Family Models for\nNetworks", - sep = ""), organization = paste("The Statnet Project (\\url{", - "http://www.statnet.org", "})", sep = ""), year = substr("2018-08-15", - 1, 4), note = paste("R package version ", "3.9.4", sep = ""), - url = paste("https://CRAN.R-project.org/package=", "ergm", - sep = "")) + list(given = c("Carter", "T."), family = "Butts", role = "aut", + email = "buttsc@uci.edu", comment = NULL), list(given = c("Steven", + "M."), family = "Goodreau", role = "aut", email = "goodreau@u.washington.edu", + comment = NULL), list(given = c("Pavel", "N."), family = "Krivitsky", + role = c("aut", "cre"), email = "pavel@statnet.org", + comment = c(ORCID = "0000-0002-9101-3362")), list(given = "Martina", + family = "Morris", role = "aut", email = "morrism@u.washington.edu", + comment = NULL)), class = "person"), title = paste("ergm", + ": ", gsub("\n", " ", "Fit, Simulate and Diagnose Exponential-Family Models for Networks", + fixed = TRUE), sep = ""), organization = paste0("The Statnet Project (\\url{", + "https://statnet.org", "})"), year = substr("2025-01-30", + 1, 4), note = paste("R package version ", "4.8.1-7571", sep = ""), + url = paste0("https://CRAN.R-project.org/package=", "ergm")) # ---- END AUTOGENERATED STATNET CITATION ---- #' statnet: statnet.cite.pkg("ergm.userterms") # ---- BEGIN AUTOGENERATED STATNET CITATION ---- @@ -36,15 +36,15 @@ bibentry("Manual", author = structure(list(list(given = "Mark S.", email = "buttsc@uci.edu", comment = NULL), list(given = "Steven M.", family = "Goodreau", role = "aut", email = "goodreau@u.washington.edu", comment = NULL), list(given = "Pavel N.", family = "Krivitsky", - role = c("aut", "cre"), email = "pavel@uow.edu.au", comment = NULL), - list(given = "Martina", family = "Morris", role = "aut", - email = "morrism@u.washington.edu", comment = NULL)), class = "person"), - title = paste("ergm.userterms", ": ", "User-specified terms for the statnet suite of packages", - sep = ""), organization = paste("The Statnet Project (\\url{", - "http://www.statnet.org", "})", sep = ""), year = substr("2013-04-26", - 1, 4), note = paste("R package version ", "3.1.1", sep = ""), - url = paste("https://CRAN.R-project.org/package=", "ergm.userterms", - sep = "")) + role = c("aut", "cre"), email = "pavel@statnet.org", + comment = c(ORCID = "0000-0002-9101-3362")), list(given = "Martina", + family = "Morris", role = "aut", email = "morrism@u.washington.edu", + comment = NULL)), class = "person"), title = paste("ergm.userterms", + ": ", gsub("\n", " ", "User-specified Terms for the statnet Suite of Packages", + fixed = TRUE), sep = ""), organization = paste0("The Statnet Project (\\url{", + "https://statnet.org", "})"), year = substr("2019-05-15", + 1, 4), note = paste("R package version ", "4.0.0", sep = ""), + url = paste0("https://CRAN.R-project.org/package=", "ergm.userterms")) # ---- END AUTOGENERATED STATNET CITATION ---- bibentry("Article", title = "ergm.userterms: A Template Package for Extending statnet", diff --git a/man/ergm.userterms-package.Rd b/man/ergm.userterms-package.Rd index b9f3dd5..bfacc94 100644 --- a/man/ergm.userterms-package.Rd +++ b/man/ergm.userterms-package.Rd @@ -1,125 +1,99 @@ -% File man/ergm.userterms-package.Rd in package ergm.userterms, 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 2012-2019 Statnet Commons -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ergm.userterms-package.R +\docType{package} \name{ergm.userterms-package} -\alias{ergm.userterms-package} \alias{ergm.userterms} -\docType{package} -\title{ -User-defined terms used in Exponential Family Random Graph Models -} +\alias{ergm.userterms-package} +\title{User-defined terms used in Exponential Family Random Graph Models} \description{ -This package contains template code for -user defined (change) statistics that can be used with the -\pkg{statnet} suite of packages (and \pkg{ergm} in particular). -To use this package the \pkg{statnet} -packages \pkg{ergm} and \pkg{network} are required. - -As background, -\pkg{statnet} is a suite of software packages for statistical network analysis. -The packages implement recent advances in network modeling based on -exponential-family random graph models (ERGM). The components of the package -provide a comprehensive framework for ERGM-based network modeling: tools for -model estimation, for model evaluation, for model-based network simulation, and -for network visualization. This broad functionality is powered by a central -Markov chain Monte Carlo (MCMC) algorithm. The coding is optimized for speed -and robustness. -For detailed information on how to download and install the software, -go to the \code{\link[ergm]{ergm}} website: -\url{statnet.org}. -A tutorial, support newsgroup, references and links to further -resources are provided there. - -When publishing results obtained using this package the original authors -are to be cited as: - -Mark S. Handcock, David R. Hunter, Carter T. Butts, Steven M. Goodreau, -and Martina Morris. 2003 -\emph{statnet: Software tools for the Statistical Modeling of Network Data} -\cr -\url{statnet.org}. +This non-CRAN package contains template code for user defined (change) statistics +that can be used with the \CRANpkg{statnet} suite of packages (and \CRANpkg{ergm} in +particular). To use this package the \CRANpkg{statnet} packages \CRANpkg{ergm} and +\CRANpkg{network} are required. +} +\details{ +As background, \CRANpkg{statnet} is a suite of software packages for statistical +network analysis. The packages implement recent advances in network modeling +based on exponential-family random graph models (ERGM). The components of +the package provide a comprehensive framework for ERGM-based network +modeling: tools for model estimation, for model evaluation, for model-based +network simulation, and for network visualization. This broad functionality +is powered by a central Markov chain Monte Carlo (MCMC) algorithm. The +coding is optimized for speed and robustness. For detailed information on +how to download and install the software, go to the \code{\link[ergm]{ergm}} +website: \url{statnet.org}. A tutorial, support newsgroup, references and +links to further resources are provided there. -We have invested a lot of time and effort in creating the -\code{statnet} suite of packages for use by other researchers. -Please cite it in all papers where it is used. +We have invested a lot of time and effort in creating the \code{statnet} +suite of packages for use by other researchers. Please cite it in all papers +where it is used. For complete citation information, use\cr -\code{citation(package="statnet")}. +\code{citation(package="ergm")}. } \section{Creating User-defined terms using this package}{ - The \pkg{statnet} suite of packages allows the - user to explore a large number of potential models - for their network data. These can be seen by typing - \code{help("ergm-terms",package="ergm")} (once the package - \pkg{ergm} has been installed). For more information on - the models and terms see Morris, Handcock, and Hunter (2008). - - The purpose of the package is to allow additional terms can - be coded up by users (you!) and be used at native speeds with - \pkg{statnet}. So the suite of packages can be extended with - minimal work by the user. In addition the core packages are - not altered and so the new packages benefit from improvements - to the core suite. - - The process of creating new terms is explained in depth by the - document entitled - by Hunter, Goodreau, and Handcock (2010) that is - found in the inst/doc directory of this package. - - In brief, to add a new term you need to (all file references are relative to the - package directory).: + The \CRANpkg{statnet} +suite of packages allows the user to explore a large number of potential +models for their network data. These can be seen by typing +\code{?ergmTerm} (once the package \CRANpkg{ergm} has +been installed). For more information on the models and terms see Morris, +Handcock, and Hunter (2008). - 1. Download the source version of this package. For example, in R use - - \code{download.packages("ergm.userterms", destdir=".", type="source")} - - where \code{destdir} is the directory to save the source - (e.g., \code{ergm.userterms_3.0.tar.gz}) in. +The purpose of the package is to allow additional terms can be coded up by +users (you!) and be used at native speeds with \CRANpkg{statnet}. So the suite +of packages can be extended with minimal work by the user. In addition the +core packages are not altered and so the new packages benefit from +improvements to the core suite. - 2. Unpack the source into a directory - (e.g., on Linux or the Mac - \code{tar -vzxf ergm.userterms_3.0.tar.gz}). +The process of creating new terms is explained in depth by the +document entitled by Hunter, Goodreau, and Handcock (2013) that is +found in the \file{inst/doc} directory of this package. While that +article is still valid, API changes in \CRANpkg{ergm} 4.0 have +simplified the term implementations and added new capabilities; see +the \emph{Terms API} vignette in \CRANpkg{ergm}. - 3. Optionally, rename the package name from - \code{ergm.userterms} to some something - more evocative of its use (e.g., \code{myergm}). - This can be done using a global change to the files in the - directory. Optionally, edit the \code{DESCRIPTION} file to reflect the - use of the package. - - 4. Edit \code{R/InitErgmTerm.users.R} to add - \R \code{InitErgmTerm} functions for the new terms. - - 5. Edit \code{src/changestats.users.c} to add \code{C} - functions (like the example already in that file) to compute the - new change statistics. - - 6. Compile the package using the usual \R - tools (e.g., \code{R CMD build myergm} and - \code{R CMD INSTALL myergm}). - - 7. Run it! It depends on \pkg{ergm} and \pkg{network}, of course. - See the example below. +In brief, to add a new term you need to (all file references are relative to +the package directory): +\enumerate{ +\item Download the source version of this package, currently hosted +at \url{https://github.com/statnet/ergm.userterms}, e.g., +\url{https://github.com/statnet/ergm.userterms/archive/refs/heads/master.zip}. +\item Unpack the source into a directory. +\item Optionally, rename the package name from \code{ergm.userterms} to some +something more evocative of its use (e.g., \code{myergm}). This can be done +using a global change to the files in the directory. Optionally, edit the +\file{DESCRIPTION} file to reflect the use of the package. +\item Edit \file{R/InitErgmTerm.users.R} to add \R \code{InitErgmTerm} +functions for the new terms. +\item Edit \file{src/changestats.users.c} to add \code{C} functions (like the +example already in that file) to compute the new change statistics. +\item Compile the package using the usual \R tools (e.g., \code{R CMD build +myergm} and \code{R CMD INSTALL myergm}). +\item Run it! It depends on \CRANpkg{ergm} and \CRANpkg{network}, of course. See the +example below. +} } + \references{ -Hunter DR, Goodreau SM, Handcock MS (2013). -{\pkg{ergm.userterms}: {A} Template Package for -Extending \pkg{statnet}}, Journal of Statistical -Software 52(2), 1-25, -URL http://www.jstatsoft.org/v52/i02/. +Hunter DR, Goodreau SM, Handcock MS (2013). \code{ergm.userterms}: A +Template Package for Extending \code{statnet}, \emph{Journal of Statistical +Software} 52(2), 1-25, \doi{10.18637/jss.v052.i02}. +} +\seealso{ +\link[ergm:ergm-package]{ergm-package}, \link[network:network-package]{network-package}, \code{\link[ergm:ergmTerm]{ergmTerm}} } -\seealso{statnet, network, ergm, ergm-terms} -\examples{ -data(faux.mesa.high) -summary(faux.mesa.high~mindegree(2)) -fit <- ergm(faux.mesa.high~mindegree(2), estimate="MPLE") -summary(fit) +\author{ +\strong{Maintainer}: Pavel N. Krivitsky \email{pavel@statnet.org} (\href{https://orcid.org/0000-0002-9101-3362}{ORCID}) + +Authors: +\itemize{ + \item Mark S. Handcock \email{handcock@stat.ucla.edu} + \item David R. Hunter \email{dhunter@stat.psu.edu} + \item Carter T. Butts \email{buttsc@uci.edu} + \item Steven M. Goodreau \email{goodreau@u.washington.edu} + \item Martina Morris \email{morrism@u.washington.edu} +} + } -\keyword{ package } -\keyword{ models } +\keyword{models} +\keyword{package} diff --git a/man/eut-upgrade.Rd b/man/eut-upgrade.Rd index f274e6f..3fdb89a 100644 --- a/man/eut-upgrade.Rd +++ b/man/eut-upgrade.Rd @@ -1,73 +1,70 @@ -% File man/eut-upgrade.Rd in package ergm.userterms, 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 2012-2019 Statnet Commons -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/ergm.userterms-package.R \name{eut-upgrade} \alias{eut-upgrade} - -\title{Updating \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} prior to 3.1} - -\description{Explanation and instructions for updating custom ERGM terms - developed prior to the release of \code{\link[=ergm-package]{ergm}} - version 3.1 (including 3.0--999 preview release) to be used with versions 3.1 or later.} - +\title{Updating \pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} +prior to 3.1} +\description{ +Explanation and instructions for updating custom ERGM terms developed prior +to the release of \code{\link[=ergm-package]{ergm}} version 3.1 (including +3.0--999 preview release) to be used with versions 3.1 or later. +} \section{Explanation}{ - \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} --- Statnet's - mechanism enabling users to write their own ERGM terms --- comes in a - form of an R package containing files for the user to put their own - statistics into (i.e., \code{changestats.user.h}, - \code{changestats.user.c}, and \code{InitErgmTerm.user.R}), as well as - some boilerplate to support them (e.g., \code{edgetree.h}, - \code{edgetree.c}, \code{changestat.h}, \code{changestat.c}, etc.). - Although the \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} API - is stable, recent developments in ergm have necessitated the - boilerplate files in ergm.userterms to be updated. To reiterate, the - user-written statistic source code (\code{changestats.user.h}, - \code{changestats.user.c}, and \code{InitErgmTerm.user.R}) can be used - without modification, but other files that came with the package need - to be changed. +\pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} --- +Statnet's mechanism enabling users to write their own ERGM terms --- comes +in a form of an R package containing files for the user to put their own +statistics into (i.e., \file{changestats.user.h}, \file{changestats.user.c}, +and \file{InitErgmTerm.user.R}), as well as some boilerplate to support them +(e.g., \file{ergm_edgetree.h}, \file{edgetree.c}, \file{ergm_changestat.h}, +\file{changestat.c}, etc.). - To make things easier in the future, we have implemented a mechanism - (using R's LinkingTo API, in case you are wondering) that will keep - things in sync in releases after the upcoming one. However, for the - upcoming release, we need to transition to this new mechanism. +Although the +\pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} API is +stable, recent developments in ergm have necessitated the boilerplate files +in \pkg{ergm.userterms} to be updated. To reiterate, the user-written statistic +source code (\file{changestats.user.h}, \file{changestats.user.c}, and +\file{InitErgmTerm.user.R}) can be used without modification, but other +files that came with the package need to be changed. +To make things easier in the future, we have implemented a mechanism (using +R's LinkingTo API, in case you are wondering) that will keep things in sync +in releases after the upcoming one. However, for the upcoming release, we +need to transition to this new mechanism. } \section{Instructions}{ - The transition entails the following steps. They only need to be done - once for a package. Future releases will keep up to date - automatically. - \enumerate{ - - \item Download the up-to-date \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} source from CRAN - using, e.g., \code{\link{download.packages}} and unpack it. +The transition entails the following steps. They only need to be done once +for a package. Future releases will keep up to date automatically. + +\enumerate{ - \item Copy the R and C files defining the user-written terms - (usually \code{changestats.user.h}, \code{changestats.user.c}, and - \code{InitErgmTerm.user.R}) and \emph{only} those files from the old - \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} source code to - the new. Do \emph{not} copy the boilerplate files that you did not - modify. - - \item If you have customized the package \code{DESCRIPTION} file - (e.g., to change the package name) or \code{zzz.R} (e.g., to change - the startup message), modify them as needed in the updated - \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}}, but do - \emph{not} simply overwrite them with their old versions. +\item Download the up-to-date +\pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} +source \url{https://github.com/statnet/ergm.userterms}, e.g., +\url{https://github.com/statnet/ergm.userterms/archive/refs/heads/master.zip} +and unpack it. + +\item Copy the R and C files defining the user-written terms (usually +\file{changestats.user.h}, \file{changestats.user.c}, and +\file{InitErgmTerm.user.R}) and \emph{only} those files from the old +\pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}} source +code to the new. Do \emph{not} copy the boilerplate files that you did not +modify. + +\item If you have customized the package \file{DESCRIPTION} file (e.g., to +change the package name) or \file{zzz.R} (e.g., to change the startup +message), modify them as needed in the updated +\pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}}, but do +\emph{not} simply overwrite them with their old versions. + +\item Make sure that your \code{\link[=ergm-package]{ergm}} installation is +up to date, and rebuild +\pkg{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}}. - \item Make sure that your \code{\link[=ergm-package]{ergm}} - installation is up to date, and rebuild - \code{\link[ergm.userterms:ergm.userterms-package]{ergm.userterms}}. - - } } +} +