is.active: Determine Activation State of Edges and Vertices

Description

Query the activity state of one or more network elements (edges or vertices) for either a single time point or an extended interval.

Usage

is.active(x, onset = NULL, terminus = NULL, length = NULL, at = NULL, e = NULL, v = NULL, 
    rule = c("any", "all","earliest","latest"), active.default = TRUE)

Value

A logical vector indicating the activity states of vertices or edges. In the case of vertices, the elements of the vector correspond to the vertex ids provided via the v paramter. In the edges case, if the network has deleted edges, they will be omited from the result so the elements of the vector may not correspond to the eids provided via the e parameter.

Arguments

x: an object of class network.
onset: an optional vector of timepoints that specifies the start of the queried interval(s). This must be accompanied by one of terminus or length.
terminus: an optional vector of timepoints that specifies the end of the queried interval(s). This must be accompanied by one of onset or length.
length: an optional vector of interval lengths for the queried interval(s). This must be accompanied by one of onset or terminus.
at: an optional vector of single time point(s) to query.
e: a vector of edge IDs to evaluate.
v: a vector of vertex IDs to evaluate.
rule: a character string indicating the definition of "active" for this query: any (default) to define active as any active spell during the interval, or all to define active as being active over the entire interval. Because we are only testing for activity, the values of earliest and latest are equivilent to any and are only included for compatibility with calling functions.
active.default: logical; should elements without an activity attribute be regarded as active by default?

Author

Ayn Leslie-Cook aynlc3@uw.edu, Carter T. Butts buttsc@uci.edu

Details

This function can be used to query the activity status of an element at single time point, or over an interval. The specification of timepoints and intervals is the same as for the activate function. The general rules are discussed in activity.attribute.

To query status at a single time point, use one of the following:

the at argument, or
set onset=terminus.

To query status over a particular interval, one of the following valid combinations of onset, terminus and length is required:

onset and terminus.
onset and length.
terminus and length.
or, you can specify no information.

If the query is specified with no timing information the spell is defined as (-Inf,Inf). The query 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.
Queries for intervals specified by c(Inf, Inf) or c(-Inf, -Inf) are ignored.

If the e argument includes edge ids corresponding to deleted edges, a warning will be generated because the length of the output vector will not match the vector of edge ids. In this case it is a good idea to use valid.eids to determine the edge ids.

Examples

Run this code

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))

# are the edges active at a particular time?
is.active(triangle, at=1, e=1:3)
is.active(triangle, at=4, e=seq_along(triangle$mel))

# delete an edge
delete.edges(triangle,e=2)
is.active(triangle, at=4, e=seq_along(triangle$mel))
# gives warning, and only two values returned, which edges are they?
# much safer to use
is.active(triangle, at=4, e=valid.eids(triangle))

Run the code above in your browser using DataLab