activate: Dynamic Activation and Inactivation of Edges and Vertices

In statnet/networkDynamic: Dynamic Extensions for Network Objects

Dynamic Activation and Inactivation of Edges and Vertices

Description

activate and deactivate set spells of activity and inactivity respectively for elements (edges and vertices) in a dynamic network.

Usage

activate.edges(x, onset = NULL, terminus = NULL, length = NULL, at = NULL,
    e = seq_along(x$mel))
activate.vertices(x, onset = NULL, terminus = NULL, length = NULL, at = NULL, 
    v = seq_len(network.size(x)))

deactivate.edges(x, onset = NULL, terminus = NULL, length = NULL, at = NULL,
    e = seq_along(x$mel))
deactivate.vertices(x, onset = NULL, terminus = NULL, length = NULL, at = NULL,
    v = seq_len(network.size(x)), deactivate.edges = FALSE)

Arguments

x	an object of class network.
onset	an optional vector of timepoints that specifies the starts of the interval(s). This must be accompanied by one of terminus or length.
terminus	an optional vector of timepoints that specifies the ends of the interval(s). This must be accompanied by one of onset or length.
length	an optional vector of interval lengths for the interval(s). This must be accompanied by one of onset or terminus.
at	optional, one or more time points to be activated.
e	optional, one or more IDs indicating edges to be modified. Ids can be repeated to indicate multiple time values per element.
v	optional, one or more IDs indicating vertices to be modified. Ids can be repeated to indicate multiple time values per element.
deactivate.edges	optional, TRUE setting will automatically deactivate all the edges associated with the vertex being deactivated

Details

An element in a dynamically extended network class is considered to be either “active” or “inactive” at any point in time, with the substantive meaning of “activity” determined by the specific application context. The activate and deactivate functions provide an interface for controlling the state of the elements in a dynamic network.

activate.edges and activate.vertices have identical behavior, except for the elements they modify (the same is true for the deactivate.* functions).

There are several ways to specify the activity spell, and the general syntax rules are described at activity.attribute. Activity can be set for a single time point, using either at, or by setting onset=terminus. Activity can be set for an interval [onset,terminus), using a valid combination of the onset, terminus and length attributes.

This allows for a wide range of options when specifying spells, but a correct specification must use only one of these forms:

  at
  onset and terminus 
  onset and length
  terminus and length
  or, you can provide no timing information 

If provided with no timing information, the element is activated/deactivated from -Inf to Inf. The specified interval spans the period from the onset (inclusive) to the terminus (exclusive), so [onset,terminus).

There are some special behaviors associated with the arguments Inf and -Inf.

• The open-ended interval c(-Inf,x) includes -Inf. For consistency, we also allow the open-ended interval c(x, Inf) to include Inf. Thus [onset, terminus) will be interpreted as [onset, terminus] when terminus = Inf.

• The arguments Inf or -Inf are only valid when used to specify an interval, they can not be used to specify status at a time point using at. In addition, they cannot be paired with themselves in a call. That is, both (Inf,Inf) and (-Inf,-Inf) are not valid specifications for any spell.

• Both deactivate.*(x) and deactivate.*(x, -Inf, Inf) create the null spell – specifying inactivity over the entire time span. Note that by convention the null spell is stored as (Inf,Inf).

Calling the activation/deactivation functions with a vector of spell modifiers and a vector of elements to be modified (for example, at=c(1,3,5 7), v=c(1:4)) allows multiple elements in the network to be activated/deactivated simultaneously (note, not multiple spells for a single element). The spell modifiers are applied sequentially to the selected elements. If the length of the spell vector is less than the number of elements, the spell modifiers are recycled as needed. When multiple network elements are activated in a single call, the spell modifiers must all be of one type, either at, or a valid mix of onset, terminus and length.

The activate.* and deactivate.* functions in general modify spells in similar, if opposite, ways. However, there are some behaviors that are specific to each function.

• Effects on an element that has no existing activity attributes.

  • For activate: the element is marked as being inactive before the onset time, then active for the specified spell, then inactive from the terminus on.

  • For deactivate: the element is marked as being active before the onset time, then inactive for the specified spell, then active from the terminus on (i.e., the opposite of activate.*.

• Effects of the at specification.

  • For activate: the element is activated at that time point.

  • For deactivate: the element is deactivated at the time point, but only if the time point is currently activated as a 0-length spell.

Currently, there is no support for activating multiple spells for a single element in a single call. To activate 2 spells for a node, for example, one must call activate.vertices twice. It is advisable to remove duplicate edges or vertices from the e or v input vectors.

Edge/vertex activity is tracked through an attribute called (eponymously) “active”, and which is explained in more detail under activity.attribute. This may be modified or otherwise accessed using standard class methods (e.g., get.edge.attribute), as well as the specialized methods described here.

Value

None. (But all four commands modify their arguments as a side-effect.)

Note

This function may not be entirely stable in the long run, since it makes explicit reference to internal elements of the network object; some syntactic changes could occur in the future.

Author(s)

Ayn Leslie-Cook [e-mail], Carter T. Butts [e-mail]

References

~put references to the literature/web site here ~

See Also

is.active

Examples

triangle <- network.initialize(3)  # create a toy network
add.edge(triangle,1,2)    # add an edge between vertices 1 and 2
add.edge(triangle,2,3)    # add more edges
add.edge(triangle,3,1)

# turn on all edges at time 1 only (0 length spell)
activate.edges(triangle,at=1) 

# activate edge (1,2) from t=2 to t=3
activate.edges(triangle,onset=2, terminus=3,
               e=get.edgeIDs(triangle,v=1,alter=2))
               
# activate edge (2,3) from t=4 for 2 time lengths
activate.edges(triangle,onset=4, length=2, 
               e=get.edgeIDs(triangle,v=2,alter=3))
               
deactivate.edges(triangle, at=2, e=1) # does not work since the spell is not 0-length
is.active(triangle, at=2, e=1:3)

deactivate.edges(triangle, e=1, onset=2, length=0.1)  # this deactivates the vertex
is.active(triangle, at=2, e=1:3)  

# this activates edges 2 and 3 at time 5
activate.edges(triangle, e=2:3, at=5)

# this activates edge 1 at multiple times;
deactivate.edges(triangle)
activate.edges(triangle, e=c(1,1,1), at=6:8)
is.active(triangle, at=6, e=1:3)
is.active(triangle, at=7, e=1:3)
is.active(triangle, at=8, e=1:3)

# this activates vertex 1 for two spells, (0,1) and (3,4)
test <- network.initialize(3)
activate.vertices(test,onset=0:3,terminus=1:4,v=c(1,2,3,1))
get.vertex.activity(test, as.spellList=TRUE)

statnet/networkDynamic documentation built on Jan. 4, 2024, 6:16 a.m.