network.extract: 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

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.

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)

Author

Carter T. Butts buttsc@uci.edu, skyebend

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.

Examples

Run this code


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)

Run the code above in your browser using DataLab