R: Convert various forms of network timing information into...

networkDynamic {networkDynamic} | R Documentation

## Convert various forms of network timing information into networkDynamic objects.

### Description

Converts various forms of temporal data (spell matrices, togles, lists of networks ) describing dynamics of vertices and edges into networkDynamic objects.

### Usage

    networkDynamic(base.net = NULL, edge.toggles = NULL, vertex.toggles =NULL,
                     edge.spells = NULL, vertex.spells = NULL,
                     edge.changes = NULL, vertex.changes = NULL,
                     network.list = NULL, onsets = NULL, termini = NULL,
                     vertex.pid = NULL, start = NULL, end = NULL,
                     net.obs.period=NULL,verbose=TRUE,create.TEAs = FALSE,
                     edge.TEA.names=NULL,vertex.TEA.names=NULL,...)

### Arguments

`base.net` | A network (or network-coearceable) object which will be used to define network-level properties (directedness,etc) of the output network. When constructing from toggles, the edges in base.net give the initially active set of edges and vertices that the activity states will be toggled from. Network and vertex attributes of `base.net` will be copied to output (unless they are overwritten by dynamic attributes with the same names)
`edge.spells` | A matrix or data.frame of spells specifying edge timing. Assumed to be [onset,terminus,tail vertex.id, head vertex.id]. Any additional columns can loaded as dynamic attributes (see `edge.TEA.names`)
`vertex.spells` | A matrix or data.frame of spells specifying vertex timing. Assumed to be [onset,terminus,vertex.id]
`edge.toggles` | A matrix or data.frame of toggles giving a sequence of activation and deactivation times for toggles. Columns are assumed to be [toggle time, tail vertex id of the edge, head vertex id of the edge].
`vertex.toggles` | A matrix or data.frame of toggles giving a sequence of activation and deactivation times for vertices. Column order assumed to be [time,vertex.id]
`edge.changes` | A matrix or data.frame of edge changes with at least 4 columns, assumed to be [time, tail, head, direction]
`vertex.changes` | A matrix or data.frame of vertex changes with at least 3 columns, assumed to be [time, vertex.id,direction]
`network.list` | a list of network objects assumed to describe sequential panels of network observations. Network sizes may vary if some vertices are only active in certain panels. See onsets, termini, vertex.pid. If base.net not specified, first element of list will be used as base.net. Network, vertex, and edge attributes will be converted to TEAs if `create.TEAs=TRUE`.
`onsets` | an optional array of onset times to be assigned to the network panels of network.list. defaults to seq(from=0,length=length(network.list)-1)
`termini` | an optional array of terminus times to be assigned to the network panels of network.list defaults to seq(from=1,length=length(network.list)
`vertex.pid` | an optional name of a vertex attribute to be used as a unique vertex identifier when constructing from a network list with different sized networks.
`start` | Optional argument to indicate the earliest time at which any changes in the network could have been observed or simulated; any spells before this time point are considered onset-censored.
`end` | Optional argument to indicate the latest time at which any changes in the network could have been observed or simulated; any spells after this time point are considered terminus-censored.
`net.obs.period` | Optional argument. A structured list for providing additional information about when and how the network was observed.
`verbose` | Logical, If TRUE (default), status message will be printed about the assumptions made in the conversion process.
`create.TEAs` | If TRUE, Dynamic TEA attributes will be created corresponding to the static attributes appear on the network elements of `network.list`
`edge.TEA.names` | an optional vector of names for the dynamic (TEA) edge attributes to be imported from the extra columns of `edge.spells` (if `create.TEAs=TRUE`)
`vertex.TEA.names` | an optional vector of names for the dynamic (TEA) vertex attributes to be imported from the extra columns of `vertex.spells` (if `create.TEAs=TRUE`)
`...` | Additional arguments controlling the creating of the network or processing of attached data objects.

### Details

This function provides ways to convert multiple forms of timing information for vertices and edges into network dynamic objects.

#### Converting from lists of networks

If the timing information is provided in the form of a lists of networks (specified by the `network.list` argument ) the assumption is that each network is a discrete ‘panel’ observation indicating the active set vertices and edges. By default, each observation is assumed to span a unit interval, (so the 1st goes from 0 to 1, 2nd from 1-2, etc). However, the onset and termini of each observation panel can be explicitly specified via the `onsets` and `termini` arguments. If the networks in `network.list` vary in size, the name of a vertex attribute to be used as a persistent id must be specified using the `vertex.pid` attribute so that the vertices in each network can be matched up correctly. If `create.TEAs=TRUE`, dynamic attributes will be created for any (non-default) attributes appearing in the list of networks. Otherwise, network and vertex attributes will be copied from the network specified via `base.net`. If `base.net` is not specified, the first element of `network.list` will be used. A `net.obs.period` will be constructed to describe the range of observations used to construct the network, or one can be specified directly using the `net.obs.period` argument.

#### Converting from matrices of spells, changes or toggles

Alternatively, timing information for edges and vertices can be provided separately as matrices or data.frames in the forms of tables of spells, changes, or toggles. For vertices, the arguments are `vertex.spells`, `vertex.changes` or `vertex.toggles`. The columns for each argument have a specific order and function, indicated in the argument definitions above. Edge arguments are named similarly `edge.spells`, `edge.changes` or `edge.toggles`. The vertex ids and ‘head’ and ‘tail’ ids must be integer index ids. Network properties (number of vertices, bipartite, directedness, etc) can currently be specified by including a `base.net` argument to be used as a template, network and vertex attributes will be copied from `base.net` as well. If only edge information is provided, the network size will be imputed from the set of edge endpoints.

In the `edge.toggles` case, the edges present in `base.net` provide the initial state to be toggled from. If a `net.obs.period` is not specified directly using the `net.obs.period` argument one will be constructed. Since the correct observation information is not known it may not describe the data accurately. Spells data will be assumed to be 'continuous' and where toggles and changes will be assumed to be 'discrete' and the `net.obs.period$observations` may include infinate values indicating unknown bounds.

When constructing a network with separate sources of data for vertex and edge timing, edge and vertex activity will not be made consistent if input data is inconsistent – edges may be active when their incident vertices are inactive, etc. These situations can be detected using the `network.dynamic.check` function and possible resolved using one of the `reconcile.activity` functions.

Curently, dynamic attributes (TEAs, see `attribute.activity.functions`) for edges or vertices (with onset and termination times matching those of the edge or vertex spell) can be loaded in by by setting `create.TEAs=TRUE` and including additional columns in the `edge.spells` or `vertex.spells` argument and specifying a vector of names for the attributes with `edge.TEA.names` or `vertex.TEA.names`. Note that when using a `data.frame` to pass in non-numeric attributes, the default behavior of converting strings to factors should be avoided.

Specification is located at https://statnet.csde.washington.edu/trac/wiki/NetworkDynamicConverterFunctions

### Value

A networkDynamic object with vertex and edge timing specified by the input data. It will also print out information about the assumptions it makes while constructing the network.

### Note

This function provides the features that were formerly (in versions < 0.4) called using as.networkDynamic.* syntax.

### Author(s)

Li Wang lxwang@uw.edu, skyebend, statnet team

### See Also

See Also as `get.edge.activity`,`get.vertex.activity`, `network.dynamic.check`

### Examples

    # construct network out of a list of panels of varying sizes
    # omiting missing day 25
    data(windsurferPanels)
    dynBeach<-networkDynamic(network.list=beach[-25], vertex.pid="vertex.names",
                            onsets=c(1:24,26:31),termini=c(2:25,27:32))

    # read in tsv files for vertex and edge spells and
    # construct network of McFarland classroom interaction data
    # see ?cls33_10_16_96 for more info about this data set

    # read vertex data
    rawVerts<-read.table(paste(path.package('networkDynamic'),
       "/extdata/cls33_10_16_96_vertices.tsv",sep=''),header=TRUE)

    # peek at column headings to find ids and times
    names(rawVerts)

    # read in interation (edge) data
    rawEdges<-read.table(paste(path.package('networkDynamic'),
      "/extdata/cls33_10_16_96_edges.tsv",sep=''),header=TRUE)

    # peek at column headings to find ids and times
    names(rawEdges)

    # construct network using vertex and edge timing information
    cls33 <-networkDynamic(vertex.spells=rawVerts[,c(3,4,1)],
                           edge.spells=rawEdges[,c(3,4,1,2)])

    # add in the unchanging vertex attribute data
    set.vertex.attribute(cls33,"sex",as.vector(rawVerts$sex))
    set.vertex.attribute(cls33,"role",as.vector(rawVerts$role))

     ## Not run:   # takes 5 seconds, too slow for CRAN checks
    # loop over edge data to add the dynamic attributes on the edge
    for(r in 1:nrow(rawEdges)){
      # get the id of the edge from its tail and head
      eid <- get.edgeIDs(cls33,v=rawEdges$from_vertex_id[r],
                         alter=rawEdges$to_vertex_id[r])
      activate.edge.attribute(cls33,'interaction_type',rawEdges$interaction_type[r],
              onset=rawEdges$start_minute[r],terminus=rawEdges$end_minute[r],e=eid)
      activate.edge.attribute(cls33,'weight',rawEdges$weight[r],
              onset=rawEdges$start_minute[r],terminus=rawEdges$end_minute[r],e=eid)
    }

    # convert the set of newcomb panels with rank weights
    data(newcomb)
    newRankDyn <-networkDynamic(network.list=newcomb.rank)
    get.network.attribute.active(newRankDyn,'title',at=3)
    as.matrix(network.collapse(newRankDyn,at=5),attrname='rank')

    ## End(Not run)

[Package networkDynamic version 0.9.0 Index]