R: A single block-diagonal network created by combining multiple...

combine_networks {tergm} | R Documentation

## A single block-diagonal network created by combining multiple networks

### Description

Given a list of compatible networks, the `combine_networks()` returns a single block-diagonal network, preserving attributes that can be preserved.

### Usage

    combine_networks(
      nwl,
      ignore.nattr = c("mnext"),
      ignore.vattr = c(),
      ignore.eattr = c(),
      blockID.vattr = ".NetworkID",
      blockName.vattr = NULL,
      detect.edgecov = FALSE,
      keep.unshared.attr = FALSE,
      subnet.cache = FALSE
    )

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

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

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

### Arguments

`nwl` | a list of `network::network`s to be combined; they must have similar fundamental properties: directedness and bipartedness, though their sizes (and the size of each bipartite group) can vary.
`ignore.nattr, ignore.vattr, ignore.eattr` | network, vertex, and edge attributes not to be processed as described below.
`blockID.vattr` | name of the vertex attribute into which to store the index of the network to which that vertex originally belonged.
`blockName.vattr` | if not `NULL`, the name of the vertex attribute into which to store the name of the network to which that vertex originally belonged.
`detect.edgecov` | if `TRUE`, combine network attributes that look like dyadic covariate (`ergm::edgecov`) matrices into a block-diagonal matrix.
`keep.unshared.attr` | whether to keep those network, vertex, and edge attributes not shared by all networks in the list; if `TRUE`, positions corresponding to networks lacking the attribute are replaced with `NA`, `NULL`, or some other placeholder; incompatible with `detect.edgecov==TRUE`.
`subnet.cache` | whether to save the input network list as an attribute of the combined network, so that if the network is resplit using on the same attribute (e.g. using `uncombine_network()`), an expensive call to `split.network()` can be avoided, at the cost of storage.
`x, object` | a combined network.
`...` | additional arguments to methods.

### Value

an object of class `combined_networks` inheriting from `network::network` with a block-diagonal structure (or its bipartite equivalent) comprising the networks passed in `nwl`. In particular,

- the returned network's size is the sum of the input networks';

- its basic properties (directedness and bipartednes) are the same;

- the input networks' sociomatrices (both edge presence and edge attributes) are the blocks in the sociomatrix of the returned network;

- vertex attributes are concatenated;

- edge attributes are assigned to their respective edges in the returned network;

- network attributes are stored in a list; but if `detect.edgecov==TRUE`, those network attributes that have the same dimension as the sociomatrices of the constituent networks, they are combined into a single block-diagonal matrix that is then stored as that attribute.

In addition, a two new vertex attibutes, specified by `blockID.vattr` and (optionally) `blockName.vattr` contain, respectively, the index in `nwl` of the network from which that vertex came and its name, determined as follows:

1. If `nwl` is a named list, names from the list are used.

2. If not 1, but the network has an attribute `title`, it is used.

3. Otherwise, a numerical index is used.

If `blockID.vattr` already exists on the constituent networks, the index is prepended to the attribute.

### Methods (by generic)

- `print`: A wrapper around `network::print.network()` to print constituent network information and omit some internal variables.

- `summary`: A wrapper around `network::summary.network()` to print constituent network information and omit some internal variables.

- `print`: A wrapper around `network::print.summary.network()` to print constituent network information and omit some internal variables.

### Examples

    data(samplk)

    o1 <- combine_networks(list(samplk1, samplk2, samplk3))
    image(as.matrix(o1))
    head(get.vertex.attribute(o1, ".NetworkID"))
    o2 <- combine_networks(list(o1, o1))
    image(as.matrix(o2))
    head(get.vertex.attribute(o2, ".NetworkID", unlist=FALSE))

    data(florentine)
    f1 <- combine_networks(list(business=flobusiness, marriage=flomarriage),
                           blockName.vattr=".NetworkName")
    image(as.matrix(f1))
    head(get.vertex.attribute(f1, ".NetworkID"))
    head(get.vertex.attribute(f1, ".NetworkName"))

[Package tergm version 4.0.2 Index]