R: Use Simulated Annealing to attempt to match a network to a...

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)

- `formula`: Sufficient statistics are specified by a `formula`.

- `ergm_model`: A lower-level function that expects a pre-initialized `ergm_model`.

- `ergm`: Sufficient statistics and other settings are inherited from the `ergm` fit unless overridden.

### 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]