DirectedNet class

Description

An S4 (old-style) class representing a directed network.

CPP model objects

Description

CPP backend for model objects used internally in ernm functions

Metropolis samplers

Description

Metropolis hastings CPP samplers, used in the fitting procedure for ernm models.

creates an ERNM likelihood model

Description

creates an ERNM likelihood model

Usage

FullErnmModel(sampler, logLik, ...)

Arguments

Value

a FullyObservedModel object

Creates an ERNM likelihood model with missing data

Description

Creates an ERNM likelihood model with missing data

Usage

MissingErnmModel(observedSampler, unobservedSampler, ...)

Arguments

Value

a MarModel object

UndirectedNet class

Description

An S4 (old-style) class representing an undirected network.

Convert an Rcpp_UndirectedNet to a network object

Description

Converts a native ernm network into a network object from the network package.

Converts a native ernm network into a network object from the network package.

‘BinaryNet' covers ERNM’s native network objects exposed via Rcpp modules: 'Rcpp_DirectedNet' and 'Rcpp_UndirectedNet'. This page documents the classes and common coercion/plot/subsetting methods.

Usage

## S3 method for class 'Rcpp_UndirectedNet'
as.network(x, ...)

## S3 method for class 'Rcpp_DirectedNet'
as.network(x, ...)

## S3 method for class 'Rcpp_DirectedNet'
plot(x, ...)

## S3 method for class 'Rcpp_UndirectedNet'
plot(x, ...)

as.BinaryNet(x, ...)

Arguments

Value

an undirected network object

a directed network object

No return value, invisibly NULL

No return value, invisibly NULL

either an Rcpp_UndirectedNet or Rcpp_DirectedNet object

Classes

* 'Rcpp_DirectedNet' – directed binary network * 'Rcpp_UndirectedNet' – undirected binary network

Coercion

* 'as.network()' – convert to a 'network' object (package **network**) * 'as.BinaryNet()' – convert from a 'network' (or return-as-is)

Methods

* 'plot()' – plot via 'plot.network'

See Also

[network::network], [network::plot.network]

Examples

edge_list <- matrix(c(1,3),ncol=2)
# create a network with an edge from 1 -> 3
ernm_net <- new(UndirectedNet,edge_list,5)

# convert to a network object from the network package
network_net <- as.network(ernm_net)
network_net
edge_list <- matrix(c(1,3),ncol=2)
# create a network with an edge from 1 -> 3
ernm_net <- new(DirectedNet,edge_list,5)

# convert to a network object from the network package
network_net <- as.network(ernm_net)
network_net

# create ring network with 5 vertices
edge_list <- matrix(c(1,2,2,3,3,4,4,5,5,1),ncol=2, byrow=TRUE)
ernm_net <- new(DirectedNet,edge_list,5)

# basic plot
plot(ernm_net)

# change vertex point size (see plot.network)
plot(ernm_net, vertex.cex=.5)

# create ring network with 5 vertices
edge_list <- matrix(c(1,2,2,3,3,4,4,5,5,1),ncol=2, byrow=TRUE)
ernm_net <- new(UndirectedNet,edge_list,5)

# basic plot
plot(ernm_net)

# change vertex point size (see plot.network)
plot(ernm_net, vertex.cex=.5)

data(samplike)

# convert Sampson's monks into a native ernm network
net <- as.BinaryNet(samplike)
net[["group"]]
net[1:5,1:5]

Calculate network statistics

Description

Calculates all network statistics

Usage

calculateStatistics(formula)

Arguments

Value

a named vector of statistics

Examples

## Not run: 
data(samplike)
calculateStatistics(samplike ~ edges() +
 nodeCount("group") +
 nodeMatch("group") +
 homophily("group") +
 triangles())

## End(Not run)

Internal symbols

Description

Internal symbols used to access compiles code.

Access ERNM parameters

Description

Access ERNM parameters

Usage

## S3 method for class 'ernm'
coef(object, ...)

Arguments

Value

parameter vector

Creates a C++ representation of an ERNM model

Description

Creates a C++ representation of an ERNM model

Usage

createCppModel(
  formula,
  ignoreMnar = TRUE,
  cloneNet = TRUE,
  theta = NULL,
  modelArgs = list(modelClass = "Model")
)

Arguments

Value

a Model object

Examples

## Not run: 
edge_list <- matrix(numeric(),ncol=2)
net <- new(UndirectedNet,edge_list,5)

rcpp_model <- createCppModel(net ~ edges(), theta = 0)

rcpp_sampler <- new(UndirectedMetropolisHastings, rcpp_model)

# Run MCMC to generate 30 networks with burnin=10 and an interval of 20 steps between each network
networks <- rcpp_sampler$generateSample(10,20,30)

sapply(networks, function(net) net$nEdges()) # number of edges in each network

## End(Not run)

Create a C++ MCMC sampler

Description

Create a C++ MCMC sampler

Usage

createCppSampler(
  formula,
  modelArgs = list(modelClass = "Model"),
  dyadToggle = NULL,
  dyadArgs = list(),
  vertexToggle = NULL,
  vertexArgs = list(),
  nodeSamplingPercentage = 0.2,
  ignoreMnar = TRUE,
  theta = NULL,
  ...
)

Arguments

Details

Available dyad toggles are:

'RandomDyad' : chooses a dyad randomly to toggle

'TieDyad' : chooses a dyad randomly with probability .5 and a random edge with probability .5

'NodeTieDyad' : chooses a random vertex and then chooses an out dyad from that vertex with probability .5 and an out edge with probability .5

'Neighborhood' : The neighborhood proposal starts by choosing a random vertex (a) and then selecting two random neighbors (b and c) Then a random non-a neighbor of b is also selected (d). The neighborhood toggle selects the dyad b- for toggling with probability 50% and the dyad d-c otherwise.

'Compound_NodeTieDyad_Neighborhood' : chooses 'NodeTieDyad' with probability .5 and 'Neighborhood' otherwise. This is the default proposal.

'Tetrad' : A toggle that preserves network degrees. This is useful when degrees are considered fixed.

'RandomMissingDyad' : RandomDyad, but restricted to missing dyads.

'NodeTieDyadMissing' : NodeTieDyad, but restricted to missing dyads.

'NeighborhoodMissing' : Neighborhood, but restricted to missing dyads.

'Compound_NodeTieDyadMissing_NeighborhoodMissing' : Compound_NodeTieDyad_Neighborhood, but restricted to missing dyads.

Available vertex toggles are:

'DefaultVertex' : The default toggle.

'DefaultVertexMissing' : DefaultVertex, but restricted to missing values.

Value

a MetropolisHastings object

Examples

## Not run: 

edge_list <- matrix(numeric(),ncol=2)
net <- new(UndirectedNet,edge_list,5)
net[["group"]] <- c("a","b","a","b","a")

# create a simple ernm model sampler
sampler <- createCppSampler(net ~ edges() + nodeCount("group") | group, theta = c(0,0))

# generate network statistics for 10 networks with a burn in of 100 steps and 200 steps between them
sampler$generateSampleStatistics(100,200,10)

# generate a network a further 100 steps later
sampler$generateSample(0,100,1)[[1]]

# make a sampler using Tie-Dyad proposals for the graph
td_sampler <- createCppSampler(net ~ edges() + nodeCount("group") | group,
  theta = c(0,0),
  dyadToggle = "TieDyad")
td_sampler$generateSampleStatistics(100,200,10)

## End(Not run)

Dutch School Data

Description

This dataset contains network and actor attributes collected in early adolescence. It is provided by Andrea Knecht and stored in the package.

Usage

data(dutch_school)

data("dutch_school")

Format

An object of class list of length 4.

Data taken from https

//www.stats.ox.ac.uk/~snijders/siena/tutorial2010_data.htm. Processed as undirected networks.

Source

Knecht, A. (2004). *Network and actor attributes in early adolescence*. DANS Data Station Social Sciences and Humanities. DOI: doi:10.17026/dans-z9b-h2bp.

References

Snijders, T.A.B., Steglich, C.E.G., and van de Bunt, G.G. (2010), Introduction to actor-based models for network dynamics, Social Networks 32, 44-60, http://dx.doi.org/10.1016/j.socnet.2009.02.004.

Fits an ERNM model

Description

ernm() fits exponential family random network models, which is an extension of exponential family random graph models, where nodal covariates may be considered stochastic. Additionally, the function may be used to fit models where the nodal covariates are random, but the graph is fixed (i.e. ALAAMs )

Usage

ernm(
  formula,
  tapered = TRUE,
  tapering_r = 3,
  modelArgs = list(),
  nodeSamplingPercentage = 0.2,
  modelType = NULL,
  likelihoodArgs = list(),
  fullToggles = c("Compound_NodeTieDyad_Neighborhood", "DefaultVertex"),
  missingToggles = c("Compound_NodeTieDyadMissing_NeighborhoodMissing", "VertexMissing"),
  ...
)

Arguments

Value

a fitted model

References

Fellows, Ian Edward. Exponential family random network models. University of California, Los Angeles, 2012.

Examples

## Not run: 

data(samplike)

# fit a tapered model to the samplike dataset where group is considered random
fit <- ernm(samplike ~ edges() + nodeCount("group") + nodeMatch("group") | group)
summary(fit)

# fit an untapered model. The homophily term is a degeneracy robust version
# of nodeMatch, which should be used instead of nodeMatch when tapering is not
# present. See Fellows (2012)
fit2 <- ernm(samplike ~ edges() + nodeCount("group") + homophily("group") | group, tapered=FALSE)
summary(fit2)

## End(Not run)

## Not run: 
# standard ergms may be fit within ernm
library(network)
data(flo)
flomarriage <- network(flo,directed=FALSE)
fit_flo <- ernm(flomarriage ~ edges() + star(2) + triangles(), tapered=FALSE)
summary(fit_flo)

# ALAAMs can be fit by specifying that edges are considered fixed using noDyad
fit3 <- ernm(samplike ~ nodeCount("group") + nodeMatch("group") | group + noDyad)
summary(fit3)

## End(Not run)

ERNM formula

Description

ERNM formula

Formula

ERNM models are specified using a formula interface. The formula expresses what statistics are in the model, along with any parameters that the statistics take. It also defines what nodal covariates are considered random and if the edges are considered random. Finally, it specifies the network that the model is defined on.

The format of the formula follows the pattern

..network.. ~ ..statistics.. | ..random..

The ..network.. place should be a single object that can be coerced into a native ernm network using as.BinaryNet.

The ..statistics.. place may contain any statistic supported by the package (see ernm-terms). Multiple statistics may be added by separating them with "+".

The ..random.. place defines what is considered random within the network. By default the dyads are considered random, however, this may be changed by including noDyad in the random place. Additionally, the names of vertex attributes can be added to make them stochastic.

For example, a simple erdos-renyi random graph model can be specified on the samplike dataset (see data(samplike)) by

samplike ~ edges()

A simple multinomial ALAAM model for the group variable can be specified by setting the dyads to be fixed and group to be random.

samplike ~ nodeCount("group") | noDyad + group

A full ernm model with terms for edges, triangles, and homopily looks like

samplike ~ edges() + triangles() + nodeCount("group") + homophily("group")

ERNM model terms

Description

ERNM model terms

Statistic Descriptions

edges (directed) (undirected)

Edges: This term adds one network statistic equal to the number of edges (i.e. nonzero values) in the network.

reciprocity() (directed)

A count of the number of pairs of actors i and j for which (i{\rightarrow}j) and (j{\rightarrow}i) both exist.

star(k, direction="in") (directed) (undirected)

The k argument is a vector of distinct integers. This term adds one network statistic to the model for each element in k. The ith such statistic counts the number of distinct k[i]-stars in the network, where a k-star is defined to be a node N and a set of k different nodes \{O_1, \dots, O_k\} such that the ties \{N, O_i\} exist for i=1, \dots, k. For directed networks, direction indicates whether the count is of in-stars (direction="in") or out-stars (direction="out")

triangles() (directed) (undirected)

This term adds one statistic to the model equal to the number of triangles in the network. For an undirected network, a triangle is defined to be any set \{(i,j), (j,k), (k,i)\} of three edges. For a directed network, a triangle is defined as any set of three edges (i{\rightarrow}j) and (j{\rightarrow}k) and either (k{\rightarrow}i) or (k{\leftarrow}i).

transitivity() (undirected)

The Soffer-Vazquez transitivity. This is clustering metric that adjusts for large degree differences and is described by C in Equation 6 of #' https://pubmed.ncbi.nlm.nih.gov/16089694/. Note The approximation of the number of possible shared neighbors between node i and j of min(d_i,d_j) - 1 in this implementation.

nodeMatch(name) (directed) (undirected)

For categorical network nodal variable 'name,' the number of edges between nodes with the same variable value.

nodeMix(name) (directed) (undirected)

For categorical network nodal variable 'name,' adds one statistic for each combination of levels of the variable equal to the count of edges between those levels.

homophily(name) (directed) (undirected)

A degeneracy robust homophily term for use in untapered models. See Fellows (2012).

degree(d, direction="undirected", lessThanOrEqual=FALSE) (directed) (undirected)

The d argument is a vector of distinct integers. This term adds one network statistic to the model for each element in d; the ith such statistic equals the number of nodes in the network of degree d[i], i.e. with exactly d[i] edges. For directed networks if direction="undirected" degree is counted as the sum of the in and out degrees of a node. If direction="in" then in-degrees are used and direction="out" indicates out-degrees.

If lessThanOrEqual=TRUE, then the count is the number of nodes with degree less than or equal to d.

nodeCov(name, direction="undirected") (directed) (undirected)

The name argument is a character string giving the name of a numeric attribute in the network's vertex attribute list. This term adds a single network statistic to the model equaling the sum of name(i) and name(j) for all edges (i,j) in the network. For categorical variables, levels are coded as 1,..,nlevels'. If direction="in", only in-edges are counted. If direction="out" only out-edges are counted.

gwesp(alpha) (directed) (undirected)

This term is just like gwdsp except it adds a statistic equal to the geometrically weighted edgewise (not dyadwise) shared partner distribution with decay parameter alpha parameter, which should be non-negative.

gwdegree(alpha, direction="undirected") (directed) (undirected)

This term adds one network statistic to the model equal to the weighted degree distribution with decay controlled by the decay parameter. The alpha parameter is the same as theta_s in equation (14) in Hunter (2007).

For directed networks if direction="undirected" degree is counted as the sum of the in and out degrees of a node. If direction="in" then in-degrees are used ans direction="out" indicates out-degrees.

gwdsp(alpha) (directed) (undirected)

This term adds one network statistic to the model equal to the geometrically weighted dyadwise shared partner distribution with decay parameter decay parameter, which should be non-negative.

esp(d, type=2) (directed) (undirected)

This term adds one network statistic to the model for each element in d where the ith such statistic equals the number of edges (rather than dyads) in the network with exactly d[i] shared partners. This term can be used with directed and undirected networks. For directed networks the count depends on type:

type = 1 : from -> to -> nbr -> from

type = 2 : from -> to <- nbr <- from (homogeneous)

type = 3 : either type 1 or 2

type = 4 : all combinations of from -> to <-> nbr <-> from

geoDist(long, lat, distCuts=Inf) (undirected)

given nodal variables for longitude and latitude, calculates the sum of the great circle distance between connected nodes. distCuts splits this into separate statistics that count the sum of the minimum of the cut point and the distance.

References

Fellows, Ian Edward. Exponential family random network models. University of California, Los Angeles, 2012.

Fit an ernm

Description

This is a lower level MCMC-MLE fitting function for ERNM. Users should generally use the ernm() function instead.

Usage

ernmFit(
  sampler,
  theta0,
  mcmcBurnIn = 10000,
  mcmcInterval = 100,
  mcmcSampleSize = 10000,
  minIter = 3,
  maxIter = 40,
  objectiveTolerance = 0.5,
  gradTolerance = 0.25,
  meanStats,
  verbose = 1,
  method = c("bounded", "newton")
)

Arguments

Value

an ernm object

References

Fellows, Ian Edward. Exponential family random network models. University of California, Los Angeles, 2012.

Create an ERNM package skeleton

Description

Creates a skeleton for a package extending the ernm package by copying an example package.

Usage

ernmPackageSkeleton(path = ".")

Arguments

Value

A logical value indicating whether the copy was successful.

Goodness of fit for ERNM model

Description

Goodness of fit plot for ERNM models, particularly suited for comparing models

Usage

ernm_gof(
  models,
  observed_network = NULL,
  stats_formula,
  style = "histogram",
  scales = "fixed",
  print = TRUE,
  n_sim = 10000,
  burnin = 10000,
  interval = 100
)

Arguments

Details

Goodness of fit in ERNM is done by comparing simulated networks from the ernm model to the observed network. If the observed network is typical of the simulated networks it is considered to be well fit.

Value

A list containing goodness-of-fit plots and simulated statistics

Examples

## Not run: 
data(samplike)
fit_basic <- ernm(samplike ~ edges() + nodeCount("group") + nodeMatch("group") | group)
fit_tri <- ernm(samplike ~ edges() + nodeCount("group") + nodeMatch("group") + triangles() | group)

# how well is the triangle term fit?
gof <- ernm_gof(
  list(
    basic = fit_basic,
    with_triangles = fit_tri
  ),
  observed_network = samplike,
  stats_formula = samplike ~ triangles(),
  n_sim = 100
)

# look at the fit over all edgewise shared partners
gof <- ernm_gof(
  list(
    basic = fit_basic,
    with_triangles = fit_tri
  ),
  style="boxplot",
  observed_network = samplike,
  stats_formula = samplike ~ esp(1:10),
  n_sim = 100
)

## End(Not run)

Subsetting and assignment for ernm network objects

Description

These methods allow standard subsetting ('[') and assignment ('[<-') for 'Rcpp_DirectedNet' and 'Rcpp_UndirectedNet' objects.

Usage

## S4 method for signature 'Rcpp_DirectedNet'
x[i, j, ..., maskMissing = TRUE, drop = TRUE]

## S4 method for signature 'Rcpp_UndirectedNet'
x[i, j, ..., maskMissing = TRUE, drop = TRUE]

## S4 replacement method for signature 'Rcpp_DirectedNet'
x[i, j, ...] <- value

## S4 replacement method for signature 'Rcpp_UndirectedNet'
x[i, j, ...] <- value

Arguments

Value

A modified object or extracted submatrix depending on the method.

Examples

# convert the Sampson's monks network into a native ernm network
data(samplike)
sampnet <- as.BinaryNet(samplike)
sampnet

# get the number of nodes and edges in the network
sampnet$size()
sampnet$nEdges()

# Extract and assign vertex attributes
sampnet[["group"]]
sampnet[["newvar"]] <- rnorm(18)
sampnet[["newvar"]]

# get the edge matrix between the first 5 vertices
sampnet[1:5,1:5]

# add an edge 2 --> 3
sampnet[2,3] <- TRUE

# Make the dyad 4 --> 1 missing
sampnet[4,1] <- NA
sampnet[1:5,1:5]

# get the in and out degrees for each vertex
sampnet$inDegree(1:18)
sampnet$outDegree(1:18)

Likelihood for a fully observed ernm

Description

This function approximates the likelihood around a sample generated at parameters theta0. The likelihood is only "trusted" within a vicinity of theta0. The size of this vicinity is controlled by requiring a minimum effective sample size (minESS) at theta + (theta - tehta0) * damping.

Usage

fullErnmLikelihood(
  theta,
  sample,
  theta0,
  stats,
  minEss = 5,
  damping = 0.05,
  method = c("cumulant", "sample"),
  order = 3
)

Arguments

Value

a list with value, gradient, and hessian

MCMC approximate log-likelihood

Description

MCMC approximate log-likelihood

Usage

## S3 method for class 'ernm'
logLik(object, ...)

Arguments

Examples

## Not run: 
fit <- ernm(samplike ~ edges() + nodeCount("group") + nodeMatch("group") | group)
logLik(fit)
AIC(fit)
BIC(fit)

## End(Not run)

Likelihood for an ernm with missing data

Description

This function approximates the likelihood around a sample generated at parameters theta0. The likelihood is only "trusted" within a vicinity of theta0. The size of this vicinity is controlled by requiring a minimum effective sample size (minESS) at theta + (theta - tehta0) * damping.

Usage

marErnmLikelihood(theta, sample, theta0, stats, minEss = 5, damping = 0.1)

Arguments

Value

a list with value, gradient, and hessian

MCMC effective sample size

Description

Computes the effective sample size from a statistic vector.

Usage

mcmcEss(x)

Arguments

Value

A numeric value representing the effective sample size.

References

Kass, R. E., Carlin, B. P., Gelman, A., & Neal, R. M. (1998). "Markov Chain Monte Carlo in Practice: A Roundtable Discussion." *The American Statistician*, 52(2), 93-100. DOI: doi:10.2307/2685466

MCMC standard error by batch

Description

Computes the MCMC standard error from a statistic vector using a batching method.

Usage

mcmcse(x, expon = 0.5)

Arguments

Value

A numeric value representing the estimated standard error.

Examples

x <-

Plot an ernm object

Description

Plot an ernm object

Usage

## S3 method for class 'ernm'
plot(x, ...)

Arguments

Value

No return value, plots the likelihood history

Print a ERNM summary object

Description

Print a ERNM summary object

Usage

## S3 method for class 'ErnmSummary'
print(x, ...)

Arguments

Value

x invisibly

Print ernm object

Description

Print ernm object

Usage

## S3 method for class 'ernm'
print(x, rowwise = TRUE, ...)

Arguments

Value

No return value, prints summary

Register statistics

Description

Register statistics

Usage

registerDirectedStatistic

Value

no return value

Register setter methods for Rcpp net objeccts

Description

Register setter methods for Rcpp net objeccts

Usage

register_rcpp_net_methods()

Value

no return value

runErnmCppTests

Description

Runs the internal C++ tests for the ernm package. Prints the results of any failed tests

Examples

runErnmCppTests()

Sampson's Monks Data

Description

This dataset represents the social network of relationships among monks in a monastery, as studied by Samuel F. Sampson. The data were collected during a period of instability and document both positive and negative interactions among the monks.

Usage

data(samplike)

data("samplike")

Format

An object of class network of length 5.

Details

The study recorded friendships, antagonisms, and other social relationships among the monks before and after a significant schism occurred in the monastery.

NOTE COPIED FROM ERGM PACKAGE

Mislabeling in Versions Prior to 3.6.1: In ergm version 3.6.0 and earlier, the adjacency matrices of the datasets reflected an older ordering of the names.

Source

Sampson, S. F. (1969). *Crisis in a cloister*. Unpublished Ph.D. dissertation, Cornell University.

References

White, H.C., Boorman, S.A. and Breiger, R.L. (1976). Social structure from multiple networks. I. Blockmodels of roles and positions. American Journal of Sociology, 81(4), 730-780.

See Also

florentine, network, plot.network, ergm

Simulate statistics

Description

Generates a MCMC chain for an ernm model and returns the sample statistics

Usage

simulateStatistics(
  formula,
  theta,
  nodeSamplingPercentage = 0.2,
  mcmcBurnIn = 10000,
  mcmcInterval = 100,
  mcmcSampleSize = 100,
  ignoreMnar = TRUE,
  modelArgs = list(modelClass = "Model"),
  ...
)

Arguments

Value

a matrix of statistics

Examples

## Not run: 
edge_list <- matrix(numeric(),ncol=2)
net <- new(UndirectedNet,edge_list,5)
net[["group"]] <- c("a","b","a","b","a")

# generate sample statistics from a simple ernm model with positive homophily
stats <- simulateStatistics(net ~ edges() + nodeCount("group") + homophily("group") | group,
  theta = c(0,0,2),
  mcmcBurnIn=10)
colMeans(stats)

## End(Not run)

Summary for ernm object

Description

Summary for ernm object

Usage

## S3 method for class 'ernm'
summary(object, ...)

Arguments

Value

an ErnmSummary object

Ernm likelihood for a TaperedModel

Description

This function approximates the likelihood around a sample generated at parameters theta0. The likelihood is only "trusted" within a vicinity of theta0. The size of this vicinity is controlled by requiring a minimum effective sample size (minESS) at theta + (theta - tehta0) * damping.

Usage

taperedErnmLikelihood(
  theta,
  centers,
  tau,
  sample,
  theta0,
  stats,
  minEss = 5,
  damping = 0.05
)

Arguments

Value

a list with value, gradient, and hessian

Parameter covariance matrix

Description

Parameter covariance matrix

Usage

## S3 method for class 'ernm'
vcov(object, ...)

Arguments

Value

covariance matrix