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 statnet suite of packages (and ergm in particular). To use this package the statnet packages ergm and network are required.

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.

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 statnet: Software tools for the Statistical Modeling of Network Data
statnet.org.

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="statnet").

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 help("ergm-terms",package="ergm") (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 (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).:

1. Download the source version of this package. For example, in R use

download.packages("ergm.userterms", destdir=".", type="source")

where destdir is the directory to save the source (e.g., ergm.userterms_3.0.tar.gz) in.

2. Unpack the source into a directory (e.g., on Linux or the Mac tar -vzxf ergm.userterms_3.0.tar.gz).

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.

References

Hunter DR, Goodreau SM, Handcock MS (2013). ergm.userterms: A Template Package for Extending statnet, Journal of Statistical Software 52(2), 1-25, URL http://www.jstatsoft.org/v52/i02/.

See Also

statnet, network, ergm, ergm-terms

Examples

1
2
3
4
data(faux.mesa.high)
summary(faux.mesa.high~mindegree(2))
fit <- ergm(faux.mesa.high~mindegree(2), estimate="MPLE")
summary(fit)