R: Convert a time range of a networkDynamic object into a static...

network.collapse {networkDynamic} | R Documentation

## Convert a time range of a networkDynamic object into a static network object.

### Description

This function provides an easy way to sensibly collapse the time-related information in a `networkDynamic` object and return a plain `network` object with a set of vertices, edges, and attributes that appropriately correspond to those appearing in the original `networkDynamic` object during the query interval.

### Usage

    network.collapse(dnet, onset = NULL, terminus = NULL, at = NULL, length = NULL,
                     rule = c("any", "all","earliest","latest"), active.default = TRUE,
                     retain.all.vertices=FALSE, rm.time.info=TRUE, ...)
    dnet%k%at

### Arguments

`dnet` | A `networkDynamic` object with possible vertex, edge, network, and attribute spell information.
`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. The value `earliest` behaves like `any` but specifies that when multiple attribute values are encountered, only the earliest will be returned. The value `latest` behaves like `any` but specifies that when multiple attribute values are encountered, only the latest will be returned.
`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 dnet?
`rm.time.info` | logical; if `TRUE`, the `net.obs.period` attribute will be removed (if it exists), and the activity summary attributes `activity.count` and `activity.duration` will not be attached to edges and vertices
`...` | Possible additional arguments (not yet invented) to handle aggregation of attributes.

### Details

First performs a `network.extract` on the passed networkDynamic object with the specified time range to get the appropriate set of active edges. Extracts appropriate values from any dynamic attributes and stores them as static attributes and optionally (if `rm.time.info=FALSE`) computes some crude summary attributes for edge and vertex spells (`activity.count`, `activity.duration`),. Then removes all `activity.attribute` and `dynamic.attributes` information and returns a plain network without the `networkDynamic` class.

The `%k%` operator (‘K’ for kollapse) is a shortcut for the 'at' version of `network.collapse`.

If no temporal arguments are specified, defaults to collapsing entire time range of the input network (`onset=-Inf,terminus=Inf`). Original network is not modified.

Arbitrary attribute values may be returned when query spells with a duration are used for continuous time networks (i.e. anything other than 'at') or query spells that don't line up with the discrete units for discrete time networks are used. If a query spell intersects with multiple attribute values, a warning will be produced and only the earliest value will be used (see `get.vertex.attribute.active`). To avoid ambiguity (and the warning), appropriate handling can be specified by setting `rule='earliest'` or `rule='latest'` to indicate which of the multiple values should be returned.

The duration values returned for edges do not account for any potential ‘censoring’ of observations in the original network.

### Value

A new 'static' `network` object corresponding to the specified time range of the `networkDynamic` argument. If the original network contained dynamic TEA attributes (i.e. 'weight.active'), the appropriate (if possible) value is queried and stored as a non-TEA attribute ('weight').

### Note

This function may be quite computationally expensive if the network contains lots of attributes. For many tasks it is possible to avoid collapsing the network by using `is.active`, the dynamic `network.extensions`, and the `attribute.activity.functions`.

### Author(s)

Skye Bender-deMoll

### See Also

See also `network.extract` for extracting sub-ranges of a networkDynamic, `get.vertex.attribute.active` for more on TEA attributes, and `as.network.networkDynamic` for stripping the the networkDynamic class from an object without the expense of modifying or removing the activity attributes.

### Examples

    # create a network with some basic activity
    test<-network.initialize(5)
    add.edges.active(test, tail=c(1,2,3), head=c(2,3,4),onset=0,terminus=1)
    activate.edges(test,onset=3,terminus=5)
    activate.edges(test,onset=-2,terminus=-1)

    # collapse the whole thing
    net <-network.collapse(test)
    is.networkDynamic(net)
    get.vertex.attribute(net,'activity.duration')
    get.edge.value(net,'activity.count')
    get.edge.value(net,'activity.duration')

    # add a dynamic edge attribute
    activate.edge.attribute(test,'weight',5,onset=3,terminus=4)
    activate.edge.attribute(test,'weight',3,onset=4,terminus=5)

    # collapse with an interval query
    net3<-network.collapse(test,onset=3,terminus=4)
    get.edge.value(net3,'weight')

    # note that if we use a query that intersects mutiple
    # attribute values it will generate a warning.
    # try commented line below:

    # net3<-network.collapse(test,onset=3,terminus=5)

    # but should be safe from attribute issues when
    # collapsing with a point query
    net3<-network.collapse(test,at=3)
    get.edge.value(net3,'weight')

    # can use operator version for point query instead
    net3<-test%k%4.5
    get.edge.value(net3,'weight')

[Package networkDynamic version 0.9.0 Index]