Package 'ergm.userterms'

User-defined terms used in Exponential Family Random Graph Models

Description

This non-CRAN package contains template code for user defined (change) statistics that can be used with the statnet suite of packages (and ergm in particular). To use this package the statnet packages ergm and network are required.

Details

As background, 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 ergm website: 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 statnet suite of packages for use by other researchers. Please cite it in all papers where it is used.

For complete citation information, use
citation(package="ergm").

Creating User-defined terms using this package

The 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 ?ergmTerm (once the package 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 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 ‘inst/doc’ directory of this package. While that article is still valid, API changes in ergm 4.0 have simplified the term implementations and added new capabilities; see the Terms API vignette in 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 https://github.com/statnet/ergm.userterms, e.g., 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 ergm.userterms to some something more evocative of its use (e.g., myergm). This can be done using a global change to the files in the directory. Optionally, edit the ‘DESCRIPTION’ file to reflect the use of the package.

4. Edit ‘R/InitErgmTerm.users.R’ to add R InitErgmTerm functions for the new terms.

5. Edit ‘src/changestats.users.c’ to add 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., R CMD build myergm and R CMD INSTALL myergm).

7. Run it! It depends on ergm and network, of course. See the example below.

Author(s)

Maintainer: Pavel N. Krivitsky [email protected] (ORCID)

Authors:

• Mark S. Handcock [email protected]

• David R. Hunter [email protected]

• Carter T. Butts [email protected]

• Steven M. Goodreau [email protected]

• Martina Morris [email protected]

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.

See Also

ergm-package, network-package, ergmTerm

---

Updating ergm.userterms prior to 3.1

Description

Explanation and instructions for updating custom ERGM terms developed prior to the release of ergm version 3.1 (including 3.0–999 preview release) to be used with versions 3.1 or later.

Explanation

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., ‘changestats.user.h’, ‘changestats.user.c’, and ‘InitErgmTerm.user.R’), as well as some boilerplate to support them (e.g., ‘ergm_edgetree.h’, ‘edgetree.c’, ‘ergm_changestat.h’, ‘changestat.c’, etc.).

Although the 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 (‘changestats.user.h’, ‘changestats.user.c’, and ‘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.

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.

1. Download the up-to-date ergm.userterms source https://github.com/statnet/ergm.userterms, e.g., https://github.com/statnet/ergm.userterms/archive/refs/heads/master.zip and unpack it.

2. Copy the R and C files defining the user-written terms (usually ‘changestats.user.h’, ‘changestats.user.c’, and ‘InitErgmTerm.user.R’) and only those files from the old ergm.userterms source code to the new. Do not copy the boilerplate files that you did not modify.

3. If you have customized the package ‘DESCRIPTION’ file (e.g., to change the package name) or ‘zzz.R’ (e.g., to change the startup message), modify them as needed in the updated ergm.userterms, but do not simply overwrite them with their old versions.

4. Make sure that your ergm installation is up to date, and rebuild ergm.userterms.

---

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.

Usage

# binary: mindegree(mindeg, by=NULL)

Arguments

mindeg	an integer giving the
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.

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 ergm APIs and conventions.

See Also

ergmTerm for index of model terms currently visible to the package.

Keywords

None

---

Square root of the number of triangles

Description

These terms add one network statistic to the model, the square root of the number of triangles. They demonstrate the private and auxiliary storage mechanisms. The change statistic for the square root of the number of triangles depends on the initial number of triangles, so it is costly to compute – unless one can keep track of the number of triangles. These terms can only be used with undirected networks.

Usage

# binary: sqrt.triangle

# binary: sqrt.triangle.aux

See Also

ergmTerm for index of model terms currently visible to the package.

Keywords

None

Examples

data(florentine)

sqrt(summary(flomarriage~triangle))
summary(flomarriage~sqrt.triangle)

stopifnot(sqrt(summary(flomarriage~triangle)) == summary(flomarriage~sqrt.triangle))

summary(flomarriage~sqrt.triangle.aux)

stopifnot(sqrt(summary(flomarriage~triangle)) == summary(flomarriage~sqrt.triangle.aux))

---