Various tweaks needed to get the package to CRAN, but not substantively

important.

DESCRIPTION

@@ -1,9 +1,10 @@
 Package: ergmgp
 Version: 0.1
-Date: 2023-02-27
+Date: 2023-06-09
 Title:  Tools for Modeling ERGM Generating Processes
 Authors@R: c(
-   	   person("Carter T.", "Butts", role=c("aut","cre"), email="[email protected]")
+   	   person("Carter T.", "Butts", role=c("aut","cre"), email="[email protected]"),
+   	   person(family="Statnet Commons", role=c("ctb"))
            )
 Depends:
     network (>= 1.15),
@@ -14,7 +15,7 @@ Imports:
     statnet.common (>= 4.2.0)
 LinkingTo:
     ergm
-Description:  Tools for continuous time processes with well-defined ERGM equilibria.
+Description:  Provides tools for simulating draws from continuous time processes with well-defined exponential family random graph (ERGM) equilibria, i.e. ERGM generating processes (EGPs).  A number of EGPs are supported, including the families identified in Butts (2023) <doi:10.1080/0022250X.2023.2180001>, as are functions for hazard calculation and timing calibration.
 License: GPL-3 + file LICENSE
 URL: https://statnet.org
 BugReports: https://github.com/statnet/ergmgp/issues

README.md

@@ -4,7 +4,17 @@
 
 An overview of supported EGPs and pointers to other help pages can be obtained after loading the package with `help(ergmgp)`.  Additional information on EGPs can also be found at the reference below.
 
-## Installing from Within R
+## Installing from CRAN
+
+The easiest way to install the package is to use CRAN.  From within `R`, simply use
+
+```
+install.packages("ergmgp")
+```
+
+which will install `ergmgp` and its dependencies.  Calling `library(ergmgp)` will subsequently load the package, and away you go.
+
+## Installing Directly from GitHub
 
 To install from GitHub, first ensure that you have the `devtools` package installed and loaded. Then, type the following: 
 

index.md

@@ -4,7 +4,17 @@
 
 An overview of supported EGPs and pointers to other help pages can be obtained after loading the package with `help(ergmgp)`.  Additional information on EGPs can also be found at the reference below.
 
-## Installing from Within R
+## Installing from CRAN
+
+The easiest way to install the package is to use CRAN.  From within `R`, simply use
+
+```
+install.packages("ergmgp")
+```
+
+which will install `ergmgp` and its dependencies.  Calling `library(ergmgp)` will subsequently load the package, and away you go.
+
+## Installing Directly from GitHub
 
 To install from GitHub, first ensure that you have the `devtools` package installed and loaded. Then, type the following: 
 

man/EGPHazard.Rd

@@ -1,17 +1,19 @@
 \name{EGPHazard}
 \alias{EGPHazard}
-%- Also NEED an '\alias' for EACH other topic documented here.
+
 \title{
 Calculate Transition Hazards for an ERGM Generating Process
 }
+
 \description{
 Given an EGP and an initial state, calculate the transition rates to one or more neighboring states.
 }
+
 \usage{
 EGPHazard(form, coef, toggles = NULL, rate.factor = 1, process = c("LERGM",
     "CRSAOM", "CI", "DS", "CDCSTERGM", "CFCSTERGM", "CSTERGM", "CTERGM"))
 }
-%- maybe also 'usage' for other objects documented here.
+
 \arguments{
   \item{form}{
 an ERGM formula for the EGP (or a list with \code{formation} and \code{dissolution} formulas, for \code{CSTERGM} processes).  The left-hand side is used as the current state when computing transition rates.
@@ -29,31 +31,31 @@ rate or pacing factor (sets the time scale).
 the ERGM generating process to use.
 }
 }
+
 \details{
 An ERGM generating process (EGP) is a continuous time graph process with an equilibrium distribution having a known ERGM form.  See \code{\link{ergmgp}} for an overview of EGPs, including the specifications supported here.
 
 \code{EGPHazard} calculates the log transition rates (i.e., hazards) from an initial or current state (specified by the left-hand side of the input formula) to one or more target states.  These states are specified by the edge variables whose states would change (often called \dQuote{toggles} in ERGM nomenclature).  By default, all possible transitions are evaluated; this can also be obtained by setting \code{toggles=="all"}.  Dissolution rates for all current edges can be obtained by setting \code{toggles=="edges"}, and formation rates for all current nulls can be obtained by setting \code{toggles=="nulls"}.  Otherwise, the \code{toggles} argument expects a two-column matrix of tail and head vertex IDs indicating the edge variables to be evaluated.  Note that only instantaneous rates from the origin state are computed; toggles are not cumulative.
 
 EGP specifications are as per \code{\link{simEGP}}.  Transition rates for all currently implemented EGPs follow the specifications of Butts (2023), with the trivial addition of a pacing constant for all families (which simply sets the timescale).
 }
+
 \value{
 a matrix containing the toggles, indicators for whether each event would have been a formation event, and the log event hazards (one row per toggle).
 }
+
 \references{
 Butts, Carter T.  (2023).  \dQuote{Continuous Time Graph Processes with Known ERGM Equilibria: Contextual Review, Extensions, and Synthesis.} \emph{Journal of Mathematical Sociology}.  \doi{10.1080/0022250X.2023.2180001}
 }
+
 \author{
 Carter T. Butts \email{buttsc@uci.edu}
 }
-%\note{
-%%  ~~further notes~~
-%}
-
-%% ~Make other sections like Warning with \section{Warning }{....} ~
 
 \seealso{
 \code{\link{ergmgp}} for information on EGPs, \code{\link[ergm]{ergm}} for information on ERGM specifications, \code{\link{simEGP}}
 }
+
 \examples{
 #Simulate a small network with triadic dependence
 n <- 25
@@ -78,12 +80,7 @@ a <- function(z){(z-min(z))/diff(range(z))}
 plot(net, edge.col = hsv(a(ldissr[,4])*0.6))  #Blue=fast, red=slow
 
 }
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory (show via RShowDoc("KEYWORDS")):
+
  \keyword{ graphs }
  \keyword{ models }
-% Use only one keyword per line.
-% For non-standard keywords, use \concept instead of \keyword:
-% \concept{ ~cpt1 }
-% \concept{ ~cpt2 }
-% Use only one concept per line.
+

man/EGPRateEst.Rd

@@ -1,19 +1,21 @@
 \name{EGPRateEst}
 \alias{EGPRateEst}
-%- Also NEED an '\alias' for EACH other topic documented here.
+
 \title{
 Estimate Event Rates for an ERGM Generating Process
 }
+
 \description{
 Given an EGP, estimate either the expected time required for a specified number of transitions to occur, or the expected number of transitions within a specified time period.
 }
+
 \usage{
 EGPRateEst(formula, coef, process = c("LERGM", "CRSAOM", "CI", "DS",
     "CDCSTERGM", "CFCSTERGM", "CSTERGM", "CTERGM"), time.target = NULL,
     event.target = NULL, reps = 25, cores = 1, rate.factor = 1, 
     verbose = FALSE, ...)
 }
-%- maybe also 'usage' for other objects documented here.
+
 \arguments{
   \item{formula}{
 an ERGM formula for the EGP (or a list with \code{formation} and \code{dissolution} formulas, for \code{CSTERGM} processes).  The left-hand side is used as the initial state.
@@ -47,31 +49,31 @@ logical; show progress information?
 additional arguments to \code{\link{simEGP}}.
 }
 }
+
 \details{
 This function can be used to estimate the expected amount of time needed for a specific number of transitions to be realized (in which case \code{event.target} should be supplied) or the expected number of transition events occurring within a specified time period (in which case \code{time.target} should be supplied).  Either way, one of \code{time.target} and \code{event.target} must be given.  The function works by simulating \code{reps} trajectories (using \code{simEGP}) for the specified time/number of events, and returning the mean outcome (along with some other associated statistics).
 
 A typical use case for this function is to calibrate the simulation time needed to obtain a reasonable number of transitions from some starting point (e.g., to ensure burn-in).  Simply simulating a fixed number of transition events will result in a biased system state; however, one can avoid this problem by using this function to determine the average duration needed for the desired number of events to be realized, and then using this duration as a stopping rule for subsequent simulations.  Alternately, another use is to estimate the rate at which events accrue, e.g. to estimate compute time or memory requirements for a longer simulation study.  Some processes are particularly prone to entering regimes in which they produce very large numbers of events per unit phenomenological time, and it can be useful to identify this issue before committing resources to simulating a long trajectory.
 
 Note that, at present, all trajectories have the same starting point (the network on the left-hand side of the input formula).  They are hence coupled by the initial condition (despite being otherwise independent).  When equilibrium estimates from short sequences are desired, it may be wise to call this function more than once with different starting networks and integrate the results.
 }
+
 \value{
 A vector containing the mean outcome (time or event count), its standard error, the standard deviation of the outcome, and the number of replicates used.
 }
+
 \references{
 Butts, Carter T.  (2023).  \dQuote{Continuous Time Graph Processes with Known ERGM Equilibria: Contextual Review, Extensions, and Synthesis.} \emph{Journal of Mathematical Sociology}.  \doi{10.1080/0022250X.2023.2180001}
 }
+
 \author{
 Carter T. Butts \email{buttsc@uci.edu}
 }
-%\note{
-%%  ~~further notes~~
-%}
-
-%% ~Make other sections like Warning with \section{Warning }{....} ~
 
 \seealso{
 \code{\link{ergmgp}} for information on EGPs, \code{\link[ergm]{ergm}} for information on ERGM specifications, \code{\link{simEGP}}
 }
+
 \examples{
 #Simulate a small network with triadic dependence
 n <- 25
@@ -91,12 +93,8 @@ eevents <- EGPRateEst(net ~ edges + esp(0), coef = co, process = "LERGM",
 eevents   #Expectation should be close to 500
 
 }
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory (show via RShowDoc("KEYWORDS")):
+
  \keyword{ graphs }
  \keyword{ models }
-% Use only one keyword per line.
-% For non-standard keywords, use \concept instead of \keyword:
-% \concept{ ~cpt1 }
-% \concept{ ~cpt2 }
-% Use only one concept per line.
+
+

man/durations.Rd

@@ -1,16 +1,19 @@
 \name{durations}
 \alias{durations}
-%- Also NEED an '\alias' for EACH other topic documented here.
+
 \title{
 Obtain Edge Spell Durations from an ERGM Generating Process Trajectory
 }
+
 \description{
 Given an input trajectory (in networkDynamic form, or network form with additional attributes), return the set of all edge durations (along with censoring information, if desired).
 }
+
 \usage{
 durations(net, censor = c("obs", "omit"), return.censoring = TRUE)
 }
-%- maybe also 'usage' for other objects documented here.
+
+
 \arguments{
   \item{net}{
 a \code{network} or \code{networkDynamic} object containing the trajectory information.
@@ -22,6 +25,7 @@ how should censoring be handled?  (Currently, only returning observed spell leng
 logical; return censoring information?
 }
 }
+
 \details{
 This function extracts information on edge spells (periods of time in which edges are present) from the input network, and returns the spell durations (optionally, together with censoring information).  The durations should not be assumed to be in any particular order; this function is generally invoked to examine duration distributions.
 
@@ -31,31 +35,21 @@ Spells may be left-censored, right-censored, or both.  \code{censor=="obs"} resu
 
 When using \code{durations} to estimate equilibrium duration distributions, it is important to bear in mind that EGP trajectories stopped by event count are not terminated at a random time, and hence will provide biased estimates.  Consider using \code{\link{EGPRateEst}} to calibrate a reasonable simulation time, and sampling with a temporal stopping rule.
 }
+
 \value{
 A vector of spell durations (order not guaranteed), or a matrix containing said durations and censoring indicators (0=uncensored, 1=right-censored, 2=left-censored, and 3=interval censored).
-%%  ~Describe the value returned
-%%  If it is a LIST, use
-%%  \item{comp1 }{Description of 'comp1'}
-%%  \item{comp2 }{Description of 'comp2'}
-%% ...
 }
-%\references{
-%% ~put references to the literature/web site here ~
-%}
+
 \author{
 Carter T. Butts \email{buttsc@uci.edu}
 }
-%\note{
-%%  ~~further notes~~
-%}
-
-%% ~Make other sections like Warning with \section{Warning }{....} ~
 
 \seealso{
 \code{\link{simEGP}}
 }
+
 \examples{
-\dontrun{  #Examples are a bit slow, so not automatically run
+\donttest{  #Examples are a bit slow, so not automatically run
 
 #Generate a simple CD-CSTERGM trajectory; equilibrium mean outdegree
 #is 2, dissolution rate is 1/3
@@ -76,7 +70,7 @@ net <- simulate(network.initialize(n)~edges, coef=log(2/(n-3)))
 traj <- simEGP(net~edges, coef=list(formation=log(2/(n-3)*1/3),
     dissolution=log(1/3)), time=500, process="CDCSTERGM", 
     return.networkDynamic=TRUE, verbose=FALSE)
-slice <- traj %t% 499                     #Take a slice near the end
+slice <- traj \%t\% 499                     #Take a slice near the end
 network.edgecount(slice)/(n-1)            #Mean degree apx 2
 dur <- durations(traj)                    #Get durations
 head(dur)                                 #More of a mix
@@ -85,13 +79,8 @@ hist(dur[,1], xlab="Time", main="Duration Distribution")  #Visualize
 
 }
 }
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory (show via RShowDoc("KEYWORDS")):
+
  \keyword{ manip }
  \keyword{ graphs }
  \keyword{ survival }
-% Use only one keyword per line.
-% For non-standard keywords, use \concept instead of \keyword:
-% \concept{ ~cpt1 }
-% \concept{ ~cpt2 }
-% Use only one concept per line.
+

man/ergmgp-package.Rd

@@ -3,10 +3,13 @@
 \alias{ergmgp-package}
 \alias{ergmgp}
 \alias{EGP_init}
+
 \title{Tools for Modeling ERGM Generating Processes}
+
 \description{
 Tools for simulation and analysis of continuous time graph processes with equilibria that can be described in exponential family random graph (ERGM) form.
 }
+
 \details{
 A random graph \eqn{G} on support \eqn{\mathcal{G}}{Supp(G)} is said to be expressed in exponential family random graph (ERGM) form when its probability mass function (pmf) is written as