R: Temporal Extracts/Cross-sections of Dynamically Extended...

network.extract {networkDynamic} | R Documentation

## Temporal Extracts/Cross-sections of Dynamically Extended Network Objects

### Description

Given a networkDynamic and a specified time point (or interval), return a reduced networkDynamic that only contains the vertices and edges active at the given point or over the given interval.

### Usage

    network.extract(x, onset = NULL, terminus = NULL, length = NULL, at = NULL,
        rule = c("any", "all"), active.default = TRUE, retain.all.vertices = FALSE,
        trim.spells=FALSE)

    x %t% at

### Arguments

`x` | an object of class `network`.
`onset` | optionally, the start of the specified interval. This must be accompanied by one of `terminus` or `length`.
`terminus` | optionally, the end of the specified interval. This must be accompanied by one of `onset` or `length`.
`length` | optionally, the length of the specified interval. This must be accompanied by one of `onset` or `terminus`.
`at` | optionally, a single time point.
`rule` | a text string for defining “active” for this call: `any` if elements active at any time during the interval are to be used, or `all` if elements must be active over the entire interval.
`active.default` | logical; should elements without an activity attribute be regarded as active by default?
`retain.all.vertices` | logical; should the extracted network retain all vertices, ignoring the vertex activity spells of x in order to ensure that the network returned has the same size as x?
`trim.spells` | logical; should the spells of vertices, edges and their attributes in the extracted network be trimmed to match the query range? (Sensible thing to do, but could be expensive)

### Details

For the purposes of extraction, edges are only considered active over some interval if: the edge itself is active over this time period, and both of the incident vertices are also active over the given time period.

When `retain.all.vertices=FALSE` (the default), the function has the following behavior:

- If `at` is used to specify the spell of interest, the returned network consists of all edges and vertices active at that time point.

- If an interval is supplied to specify the spell (via `onset` and one of `terminus` or `length`), edges and vertices active over the specified interval are used. If `rule="any"`, then edges and vertices active at any time during the interval are returned; otherwise, only those active during the entire period are returned.

Vertices in the extracted network will have the same order as the original network, with inactive vertices removed.

When `retain.all.vertices=TRUE`

- All vertices are preserved in the output net to preserved network size and ids.

- if `trim.spells=TRUE`, 'retained' vertices will be marked as inactive (they will have 'null' spell (Inf,Inf))

- Edges that are active (by the specified `rule`) during the specified spell are included in the returned network (same as above.)

- Edges with one or more inactive vertices still will be removed (even if the vertex is being 'retained' to preserve network size)

If a `net.obs.period` network attribute is present, its observation spells will be truncated by the onset and terminus of extraction. If the onset and terminus do not intersect with any observation spells, the '$observations' component will be set to the 'null' spell `c(Inf,Inf)`.

`%t%` (the temporal cross-section operator) is a simplified (and less flexible) wrapper for `network.extract` that returns the network of active vertices and edges at a given time point.

### Value

A `networkDynamic` object containing the active edges and vertices for the specified spell, when `retain.all.vertices=FALSE`, otherwise the network object containing all vertices, and only those edges active for the specified spell.

### Note

Note that only active vertices are included by default (`retain.all.vertices=FALSE`). As a result, the size of the extracted network may be smaller than the original. Vertex and edge ids will be translated, but may not correspond to their original values. If it is necessary to maintain the identities of vertices, see `persistent.ids`.

### Author(s)

Carter T. Butts buttsc@uci.edu, skyebend

### See Also

`is.active`, `activity.attribute`, `network.extensions`, and `get.inducedSubgraph` for a related non-temporal version, `network.collapse` to squish a `networkDynamic` object into a static `network`

### Examples

    triangle <- network.initialize(3)    # create a toy network

    # add edges with activity
    # first add an edge between vertices 1 and 2
    add.edges.active(triangle,onset=0,terminus=10,tail=1,head=2)
    # add a more edges
    add.edges.active(triangle,onset=0,length=4,tail=2,head=3)
    add.edges.active(triangle,at=4.5,tail=3,head=1)

    # specify some vertex activity
    activate.vertices(triangle,onset=0,terminus=10)
    deactivate.vertices(triangle,onset=1,terminus=2,v=3)

    degree<-function(x){as.vector(rowSums(as.matrix(x))
      + colSums(as.matrix(x)))} # handmade degree function

    degree(triangle) # degree of each vertex, ignoring time

    degree(network.extract(triangle,at=0))
    degree(network.extract(triangle,at=1)) # just look at t=1
    degree(network.extract(triangle,at=2))
    degree(network.extract(triangle,at=5))

    # watch out for empty networks! they are just an empty list
    t10 <- network.extract(triangle,at=10)
    t10

    # notice difference between 'at' syntax and 'onset,terminus'
    # when network is not in discrete time
    degree(network.extract(triangle,at=4))
    degree(network.extract(triangle,onset=4,terminus=5))

    # the %t% (time) operator is like an alias for the 'at' extraction syntax
    degree(triangle%t%4)

    par(mfrow=c(2,2))
    #show multiple plots
    plot(triangle,main='ignoring dynamics',displaylabels=TRUE)
    plot(network.extract(triangle,onset=1,terminus=2),main='at time 1',displaylabels=TRUE)
    plot(network.extract(triangle,onset=2,terminus=3),main='at time 2',displaylabels=TRUE)
    plot(network.extract(triangle,onset=5,terminus=6),main='at time 5',displaylabels=TRUE)

[Package networkDynamic version 0.9.0 Index]