network.extract: Temporal Extracts/Cross-sections of Dynamically Extended...
In networkDynamic: Dynamic Extensions for Network Objects

network.extract

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

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)

networkDynamic documentation built on Feb. 16, 2023, 10:08 p.m.