# Functions to activate and query dynamic attributes on vertices, edges, and networks These functions set, query and modify attributes of networkDynamic objects used to represent values which change over time. These dynamic or "temporally extended attributes" are stored as standard attributes with a specially defined structure. ```r activate.vertex.attribute(x, prefix, value, onset = NULL, terminus = NULL, length = NULL, at = NULL, v = seq_len(network.size(x)), dynamic.only = FALSE) activate.edge.attribute(x, prefix, value, onset = NULL, terminus = NULL, length = NULL, at = NULL, e = seq_along(x$mel), dynamic.only = FALSE) activate.edge.value(x, prefix, value, onset = NULL, terminus = NULL, length = NULL, at = NULL, e = seq_along(x$mel), dynamic.only = FALSE) activate.network.attribute(x, prefix, value, onset = NULL, terminus = NULL, length = NULL, at = NULL, dynamic.only = FALSE) ## S3 method for class 'active' get.vertex.attribute(x, prefix, onset = NULL, terminus = NULL, length = NULL, at = NULL, rule = c("any", "all","earliest","latest"), na.omit = FALSE, null.na = TRUE, active.default = TRUE, dynamic.only = FALSE, require.active = FALSE, return.tea = FALSE, unlist = TRUE, ...) ## S3 method for class 'active' get.edge.attribute(x, prefix, onset = NULL, terminus = NULL, length = NULL, at = NULL, rule = c("any", "all","earliest","latest"), active.default = TRUE, dynamic.only = FALSE, require.active = FALSE, return.tea = FALSE, unlist = TRUE, ..., el) ## S3 method for class 'active' get.edge.value(x, prefix, onset = NULL, terminus = NULL, length = NULL, at = NULL, rule = c("any", "all","earliest","latest"), active.default = TRUE, dynamic.only = FALSE, require.active = FALSE, return.tea = FALSE, unlist = TRUE, ...) ## S3 method for class 'active' get.network.attribute(x, prefix, onset = NULL, terminus = NULL,length = NULL, at = NULL, rule = c("any", "all","earliest","latest"), dynamic.only = FALSE, return.tea=FALSE, unlist=TRUE, ...) deactivate.vertex.attribute (x, prefix, onset=NULL, terminus=NULL, length = NULL, at = NULL, v = seq_len(network.size(x)), dynamic.only = FALSE) deactivate.edge.attribute (x, prefix, onset = NULL, terminus = NULL, length = NULL, at = NULL, e = seq_along(x$mel), dynamic.only = FALSE) deactivate.network.attribute(x, prefix, onset = NULL, terminus = NULL, length = NULL, at = NULL, dynamic.only = FALSE) ## S3 method for class 'active' list.vertex.attributes(x, onset = NULL, terminus = NULL,length = NULL, at = NULL, na.omit = FALSE, rule = c("any", "all"), v = seq_len(network.size(x)), require.active = FALSE, active.default = TRUE, dynamic.only = FALSE, ...) ## S3 method for class 'active' list.edge.attributes(x, onset = NULL, terminus = NULL,length = NULL, at = NULL, na.omit = FALSE, rule = c("any", "all"), e = seq_along(x$mel), require.active = FALSE, active.default = TRUE, dynamic.only = FALSE, ...) ## S3 method for class 'active' list.network.attributes(x, onset = NULL, terminus = NULL,length = NULL, at = NULL, na.omit = FALSE, rule = c("any", "all"), dynamic.only = FALSE, ...) ``` ## Arguments - `x`: a `networkDynamic` object - `prefix`: character string for the name of the attribute to be stored (will be stored as prefix.active) - `value`: an object that is the value of the attribute to be stored. If `value` is a `list`, it is assumed that each element corresponds to an index in `v`. - `onset`: an optional vector of time-points that specifies the starts of the interval(s) at which the `value` argument should be considered active for each vertex/edge. - `terminus`: an optional vector of time-points that specifies the ends of the interval(s) at which the `value` argument should be considered active for each vertex/edge. - `length`: an optional vector of interval lengths for the interval(s) which should be activated for each vertex/edge. This must be accompanied by one of `onset` or `terminus`. - `at`: optional, one or more time points (corresponding to vertices/edges) at which values should be activated for each vertex/edge - `v`: optional, one or more IDs indicating which vertices should have the TEA attribute added (default is all vertices) - `e`: optional, one or more edge IDs indicating which edge should have the TEA attribute added. Default is all edges. Note: Currently values of `e` correspond to elements of `x$mel`, including null elements from deleted edges. So if some edges have been deleted from the network, `e` may need to be padded out appropriately and can be longer than `network.edgecount(x)`. - `dynamic.only`: If dynamic.only==TRUE, only TEAs are considered; otherwise, non-TEA attributes are also employed (with activity as defined by active.default). - `require.active`: logical. If TRUE, NA will be returned instead of an attribute value if the associated vertex or edge is inactive for the query period. When vertex or edge activity has not be explicitly set, the state is controlled by `active.default`. - `active.default`: logical; should underlying vertices or edges without an activity attribute be regarded as active by default? - `na.omit`: logical; should values from missing vertices/edges be removed? (implemented for vertices, but removal means that the index may not correspond to vertex.id for returned values) - `null.na`: logical; should `NULL` values be replaced with NAs? - `rule`: a character string indicating how the attribute activity spells should be matched against the query spell for this query: * `any` (default) match attribute values if they overlap with any part of the query interval. * `all` match an attribute value only if it overlaps with the entire query interval, * `earliest` match a single value corresponding to the earliest attribute overlaping any part of the query spell, * `latest` match a single value corresponding to the earliest attribute overlaping any part of the query spell. - `return.tea`: logical; if `return.tea=TRUE`, will return an (appropriately truncated) activity attribute- a list with the first element a list of values and the second element the spell matrix of corresponding spell(s) matching according to `rule`. Also sets `unlist=FALSE` and `dynamic.only=TRUE`. - `unlist`: logical; should retrieved attributes be unlisted prior to being returned? Setting to FALSE is necessary to correctly fetch list objects stored as attributes. - ``...``: possible additional arguments - `el`: unused argument that exists solely for consistency with `network`; do not use this argument! ## Details These functions provide easy ways to work with temporally extended attributes, making it possible to store attributes on a dynamic network that should be represented as changing values and different points in time. Because the serve as wrappers for get.*.attribute and set.*.attribute, many of the arguments are directly passed through. The activate.*.attribute methods act as a cross between activate.* set.*.attribute methods. They are used to activate an attribute for a given spell, and in so doing set a value for that spell. The corresponding deactivate methods are more straightforward, deactivating the attribute over a set interval (and removing any spells/values as needed). A dynamic or Temporally Extended Attribute (TEA) is an edge, vertex, or network attribute satisfying the following properties: 1. Its name consists of an arbitrary prefix, together with the suffix ".active". 2. Its value consists of a two-element list, whose respective contents must be maintained in order as follows: * a. A list of value entries, such that the ith list element is the value of the attribute for the ith spell in the associated activity matrix. An attribute not active at any given point in time is defined as having a value of NA (but the reverse is not true -- an active attribute can also take a value of NA). * b. A two-column numeric matrix, conforming to the specifications for activity attributes in the networkDynamic package. Every active spell indicated in the activity matrix must correspond to exactly one entry of the associated value list, and these must be maintained in order (i.e., the value of the attribute for the ith active spell is the ith element in the value list). 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 ``` If the `set` and `deactivate` functions are 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)`. For more details, see `activate` The `get` query functions will give an error if no timing information is provided. When the activity arguments have a length greater than 1, the elements are assumed to correspond to the vertex or edge ids that should have that activity specified, not to the elements of `value`. In other words, it is possible to use one function call to activate multiple values on multiple vertices with a different activity time on each vertex, but it is not possible to activate multiple values at multiple times on a single vertex with one call. `activate.edge.value` is a wrapper for `activate.edge.attribute`. When the attribute query has a non-zero duration (i.e. `length` > 0, or `onset!=terminus`) it is possible that the query spell will match against multiple attribute values for each network element. If multiple values match and `return.tea=FALSE`, a warning will be generated and only the earliest value will be returned. To avoid the warning, this behavior (or its opposite) can be specified by setting `rule='earliest'` or `rule='latest'`. ## Returns The set methods modify their network argument internally and also invisibly return a reference to the modified network. The get methods return the attribute object appropriate for the time range specified query spell parameters. If query results in multiple values and `return.tea=FALSE` only the first (earliest) is returned along with a warning. Note that `get.edge.value.active` returns `NULL` if no attributes names match, where `get.vertex.attribute.active` returns `NA`s. Also of `null.na=FALSE` and `unlist=TRUE`, the index position for returned values may not correspond to the vertex.id because NULL values will be omited. ## Author(s) skyebend, ayn, carter, pavel, martina, steve ## Note Attribute activity is only checked against vertex and edge activity during fetching if `require.active=TRUE`. Otherwise the attributes for a vertex can take values (be active) when the vertex itself is inactive. Likewise for edges. The because they must check all attributes on all network elements, the `list.*.active` functions are generally more computationally expensive that a `get` call for checking if a specific attribute exists. Note that `get.edge.attribute.active` currently calls `get.edge.attribute.active` and does not support a list of edges as input. ## See Also See Also as `set.vertex.attribute`, `get.vertex.attribute`,`list.vertex.attributes`,`activate.vertices`, `activity.attribute`, `activate` ## Examples ```r #initialize network test<-network.initialize(5) #activate vertex attribute test<-activate.vertex.attribute(test,"letter","a",onset=0,terminus=1) test<-activate.vertex.attribute(test,"number","4",onset=1,terminus=2) test<-activate.vertex.attribute(test,"number","5",onset=2,terminus=3) #list active/all vertex attributes list.vertex.attributes.active(test, onset=0,terminus=3,dynamic.only=TRUE) list.vertex.attributes.active(test, onset=1,terminus=3,dynamic.only=FALSE) #get values for specific vertex attribute get.vertex.attribute.active(test,"letter",onset=2,terminus=3) #deactive vertex attribute test <- deactivate.vertex.attribute(test, "letter", onset=0, terminus=3) list.vertex.attributes.active(test, onset=0,terminus=3,dynamic.only=TRUE) #initialize edges test[1,2]<-1 test[2,3]<-1 #activate edge attribute test<-activate.edge.attribute(test,"number",1,onset=0,terminus=2) test<-activate.edge.attribute(test,"number",5,onset=2,terminus=5) test<-activate.edge.attribute(test,"letter","a",onset=1,terminus=4) #list edge attributes list.edge.attributes.active(test, onset=0,terminus=4,dynamic.only=TRUE) list.edge.attributes.active(test, onset=0,terminus=4,dynamic.only=FALSE) #get values for specific edge attribute get.edge.value.active(test,"number",onset=3,terminus=4) #deactive edge attribute test <- deactivate.edge.attribute(test, "letter", onset=0, terminus=3) list.edge.attributes.active(test, onset=0,terminus=3,dynamic.only=TRUE) #activate network attribute test <- activate.network.attribute(test,"alist",list("a","b"),onset=1,terminus=2) test <- activate.network.attribute(test,"alist",list("c","d"),onset=2,terminus=3) test <- activate.network.attribute(test,"aspace",list("1","2"),onset=1,terminus=2) test <- activate.network.attribute(test,"aspace",list("3","4"),onset=2,terminus=3) #list network attributes list.network.attributes.active(test, onset=0,terminus=3,dynamic.only=TRUE) list.network.attributes.active(test, onset=0,terminus=3,dynamic.only=FALSE) #get values for specific network attribute get.network.attribute.active(test,"alist",at=2.5,unlist=FALSE) #deactive network attribute test <- deactivate.network.attribute(test, "alist", onset=0, terminus=3) list.network.attributes.active(test, onset=0,terminus=3,dynamic.only=TRUE) # activate multiple values on multiple vertices at multiple times test<-network.initialize(3) activate.vertex.attribute(test,"letters",c("a","b","c"),onset=c(0,1,2),terminus=c(1,2,3)) # peek at TEA structure using non-TEA attribute query get.vertex.attribute(test,"letters.active",unlist=FALSE) # compare different 'rules' test<-network.initialize(1) activate.vertex.attribute(test,'color','red',onset=0,terminus=1) activate.vertex.attribute(test,'color','green',onset=1,terminus=2) activate.vertex.attribute(test,'color','blue',onset=2,terminus=3) get.vertex.attribute.active(test,'color',onset=0,terminus=3) get.vertex.attribute.active(test,'color',onset=0,terminus=3,return.tea=TRUE) get.vertex.attribute.active(test,'color',onset=0,terminus=3,rule='earliest') get.vertex.attribute.active(test,'color',onset=0,terminus=3,rule='latest') ```

tea_functions function