san {ergm}R Documentation

Use Simulated Annealing to attempt to match a network to a vector of mean statistics

Description

This function attempts to find a network or networks whose statistics match those passed in via the target.stats vector.

Usage

san(object, ...)

## S3 method for class 'formula'
san(object, response = NULL, reference = ~Bernoulli,
  constraints = ~., target.stats = NULL, nsim = NULL, basis = NULL,
  output = c("network", "edgelist", "pending_update_network"),
  only.last = TRUE, control = control.san(), verbose = FALSE, ...)

## S3 method for class 'ergm_model'
san(object, response = NULL,
  reference = ~Bernoulli, constraints = ~., target.stats = NULL,
  nsim = NULL, basis = NULL, output = c("network", "edgelist",
  "pending_update_network"), only.last = TRUE, control = control.san(),
  verbose = FALSE, ...)

## S3 method for class 'ergm'
san(object, formula = object$formula,
  constraints = object$constraints, target.stats = object$target.stats,
  nsim = NULL, basis = NULL, output = c("network", "edgelist",
  "pending_update_network"), only.last = TRUE,
  control = object$control$SAN.control, verbose = FALSE, ...)

Arguments

object

Either a formula or an ergm object. The formula should be of the form y ~ <model terms>, where y is a network object or a matrix that can be coerced to a network object. For the details on the possible <model terms>, see ergm-terms. To create a network object in , use the network() function, then add nodal attributes to it using the %v% operator if necessary.

...

Further arguments passed to other functions.

response

Name of the edge attribute whose value is to be modeled. Defaults to NULL for simple presence or absence.

reference

One-sided formula whose RHS gives the reference measure to be used. (Defaults to ~Bernoulli.)

constraints

A one-sided formula specifying one or more constraints on the support of the distribution of the networks being simulated. See the documentation for a similar argument for ergm and see list of implemented constraints for more information. For simulate.formula, defaults to no constraints. For simulate.ergm, defaults to using the same constraints as those with which object was fitted.

target.stats

A vector of the same length as the number of terms implied by the formula, which is either object itself in the case of san.formula or object$formula in the case of san.ergm.

nsim

Number of networks to generate. Deprecated: just use replicate().

basis

If not NULL, a network object used to start the Markov chain. If NULL, this is taken to be the network named in the formula.

output

Character, one of "network" (default), "edgelist", or "pending_update_network": determines the output format. Partial matching is performed.

only.last

if TRUE, only return the last network generated; otherwise, return a network.list with nsim networks.

control

A list of control parameters for algorithm tuning; see control.san.

verbose

Logical or numeric giving the level of verbosity. Higher values produce more verbose output.

formula

(By default, the formula is taken from the ergm object. If a different formula object is wanted, specify it here.

Value

A network or list of networks that hopefully have network statistics close to the target.stats vector.

Methods (by class)

Examples


# initialize x to a random undirected network with 50 nodes and a density of 0.1
x <- network(50, density = 0.05, directed = FALSE)
 
# try to find a network on 50 nodes with 300 edges, 150 triangles,
# and 1250 4-cycles, starting from the network x
y <- san(x ~ edges + triangles + cycle(4), target.stats = c(300, 150, 1250))

# check results
summary(y ~ edges + triangles + cycle(4))

# initialize x to a random directed network with 50 nodes
x <- network(50)

# add vertex attributes
x %v% 'give' <- runif(50, 0, 1)
x %v% 'take' <- runif(50, 0, 1)

# try to find a set of 100 directed edges making the outward sum of
# 'give' and the inward sum of 'take' both equal to 62.5, so in
# edges (i,j) the node i tends to have above average 'give' and j
# tends to have above average 'take'
y <- san(x ~ edges + nodeocov('give') + nodeicov('take'), target.stats = c(100, 62.5, 62.5))

# check results
summary(y ~ edges + nodeocov('give') + nodeicov('take'))


# initialize x to a random undirected network with 50 nodes
x <- network(50, directed = FALSE)

# add a vertex attribute
x %v% 'popularity' <- runif(50, 0, 1)

# try to find a set of 100 edges making the total sum of
# popularity(i) and popularity(j) over all edges (i,j) equal to
# 125, so nodes with higher popularity are more likely to be
# connected to other nodes
y <- san(x ~ edges + nodecov('popularity'), target.stats = c(100, 125))
 
# check results
summary(y ~ edges + nodecov('popularity'))

# creates a network with denser "core" spreading out to sparser
# "periphery"
plot(y)
[Package ergm version 3.10.4 Index]