Changes between Version 1 and Version 2 of TemporallyExtendedAttributes


Ignore:
Timestamp:
10/24/12 10:45:31 (7 years ago)
Author:
skyebend
Comment:

added wiki formating

Legend:

Unmodified
Added
Removed
Modified
  • TemporallyExtendedAttributes

    v1 v2  
    1 ==Draft Specification for Temporally Extended Attributes== 
     1== Draft Specification for Temporally Extended Attributes == 
    22 
    33Compiled by Carter Butts, w/extensive input from Skye Bender-deMoll, Martina Morris, Pavel Krivitsky, and others 
    44 
    5 v0.1, last modified 01/10/10 
     5v0.1.1 
    66 
    7 Definition: A "temporally extended attribute" (TEA) is a standard edge, vertex, or network attribute that (1) has a name ending in ".active" and (2) carries meta-data regarding its state over time. 
     7'''Definition:''' ''A "temporally extended attribute" (TEA) is a standard edge, vertex, or network attribute that (1) has a name ending in ".active" and (2) carries meta-data regarding its state over time.'' 
    88 
    99 
    10 ===General Requirements:=== 
     10=== General Requirements: === 
    1111 
    12   1. TEAs must be compatible with the existing network class specification. 
     12 1. TEAs must be compatible with the existing network class specification. 
    1313 
    14   2. All operations involving TEAs must be implementable within the existing network class API. 
     14 2. All operations involving TEAs must be implementable within the existing network class API. 
    1515 
    16   3. TEAs must allow for the same time/state semantics as other elements of the networkDynamic extended class. 
     16 3. TEAs must allow for the same time/state semantics as other elements of the networkDynamic extended class. 
    1717 
    18   4. TEA methods should allow the following operations: 
     18 4. TEA methods should allow the following operations: 
     19  a. Cross-section queries (selection of attributes at an instant in time). 
     20   i. Return types must include attribute values or activity tables. 
     21   ii. Inactive attributes should return NA. 
     22  b. Interval queries (all values taken by selected active attribute(s) over an arbitrary continuous interval). 
     23   i. As above, return values must include attribute values or activity table information. 
     24  c. Next event/previous event queries (find next or previous state change given query time). 
     25   i. Return NA if no event. 
     26   ii. Should be able to return transitional state, time, or both. 
     27  d. "apply" function semantics for interval or cross-sectional queries. 
     28  e. Activity table queries (i.e., return spell list), using (a) or (b) query semantics. 
     29  f. List TEA attributes. 
    1930 
    20     a. Cross-section queries (selection of attributes at an instant in time). 
     31 5. TEA methods should exhibit reasonable default behavior when called against non-TEA attributes: 
     32  a. During attribute seek ("get"), failure to find *.active should default to a seek for * (unless selected otherwise). 
     33  b. Non-TEA attributes found by failover seek should be treated as universally active/inactive in accord with is.active semantics (see man page for is.active). 
    2134 
    22       i. Return types must include attribute values or activity tables. 
    23  
    24       ii. Inactive attributes should return NA. 
    25  
    26     b. Interval queries (all values taken by selected active attribute(s) over an arbitrary continuous interval). 
    27  
    28       i. As above, return values must include attribute values or activity table information. 
    29      
    30     c. Next event/previous event queries (find next or previous state change given query time). 
    31  
    32       i. Return NA if no event. 
    33        
    34       ii. Should be able to return transitional state, time, or both. 
    35  
    36     d. "apply" function semantics for interval or cross-sectional queries. 
    37  
    38     e. Activity table queries (i.e., return spell list), using (a) or (b) query semantics. 
    39      
    40     f. List TEA attributes. 
    41  
    42   5. TEA methods should exhibit reasonable default behavior when called against non-TEA attributes: 
    43  
    44     a. During attribute seek ("get"), failure to find *.active should default to a seek for * (unless selected otherwise). 
    45  
    46     b. Non-TEA attributes found by failover seek should be treated as universally active/inactive in accord with is.active semantics (see man page for is.active). 
    47  
    48   6. TEA local activity is independent of the entity to which it is attached. 
    49    
    50     a. Where feasible, however, functions should allow optional "filtering" behavior by activity of the underlying entity. 
     35 6. TEA local activity is independent of the entity to which it is attached. 
     36  a. Where feasible, however, functions should allow optional "filtering" behavior by activity of the underlying entity. 
    5137   
    5238 
    53 ===Acceptable Limitations (?):=== 
     39=== Acceptable Limitations (?): === 
    5440 
    5541  1. The current networkDynamic implementation is subject to R vector allocation limits, and as such can record on the order of ten million spells per entity on a 64-bit machine.  It is assumed that this is acceptable (otherwise, implementation becomes substantially more difficult). 
     
    6450   
    6551 
    66 ===Attribute Standard=== 
     52=== Attribute Standard === 
    6753 
    68   A temporally extended attribute is an edge, vertex, or network attribute satisfying the following properties: 
    69    
    70   1. Its name consists of an arbitrary prefix, together with the suffix ".active". 
     54A temporally extended attribute is an edge, vertex, or network attribute satisfying the following properties: 
     55  
     56 1. Its name consists of an arbitrary prefix, together with the suffix ".active". 
    7157 
    72   2. Its value consists of a two-element list, whose respective contents must be maintained in order as follows: 
    73  
    74     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). 
    75  
    76     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). 
     58 2. Its value consists of a two-element list, whose respective contents must be maintained in order as follows: 
     59  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). 
     60  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). 
    7761 
    7862 
    79 ===Default Methods=== 
     63=== Default Methods === 
    8064 
    81   Since TEAs are standard network attributes, they can be manipulated directly via the existing network attribute methods (either via R or the C-level API).  Likewise, existing summary and other methods in the base class will simply interpret TEAs as they would any other list-valued attributes.  Thus, TEA-extended network objects are backward compatible (as required). 
     65Since TEAs are standard network attributes, they can be manipulated directly via the existing network attribute methods (either via R or the C-level API).  Likewise, existing summary and other methods in the base class will simply interpret TEAs as they would any other list-valued attributes.  Thus, TEA-extended network objects are backward compatible (as required). 
    8266   
    8367 
    84 ===Extended Attribute Methods=== 
     68=== Extended Attribute Methods === 
    8569 
    86   Several special-purpose methods may be created to facilitate interaction with TEAs.  The following are initial proposals of this type (briefly described): 
     70Several special-purpose methods may be created to facilitate interaction with TEAs.  The following are initial proposals of this type (briefly described): 
    8771 
    88   activate/deactivate.*.attribute 
     72==== activate/deactivate.*.attribute ==== 
    8973 
    90     The activate.*.attribute methods act as a cross between the new activate.* and the old 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). 
     74The activate.*.attribute methods act as a cross between the new activate.* and the old 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). 
     75  {{{ 
     76activate.edge.attribute(x, prefix, value, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
     77 
     78activate.edge.value(x, prefix, value, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
     79 
     80activate.network.attribute(x, prefix, value, onset=-Inf, terminus=NULL, dynamic.only=FALSE) 
     81 
     82activate.vertex.attribute(x, prefix, value, onset=-Inf, terminus=NULL, v=1:network.size(x), dynamic.only=FALSE) 
     83 
     84deactivate.edge.attribute(x, prefix, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
     85 
     86deactivate.edge.value(x, prefix, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
     87 
     88deactivate.network.attribute(x, prefix, onset=-Inf, terminus=NULL, dynamic.only=FALSE) 
     89 
     90deactivate.vertex.attribute(x, prefix, onset=-Inf, terminus=NULL, v=1:network.size(x), dynamic.only=FALSE) 
     91 }}} 
     92Behavior sketch: For the activate methods, query the selected entities for a TEA with the specified prefix.  If no such TEA exists and dynamic.only==FALSE, perform a secondary seek with an attribute such that attrname==prefix; if such an attribute is found, convert it to a TEA, and otherwise (or if no such TEA exists and dynamic.only==TRUE) create a TEA with the appropriate prefix.  Once the appropriate TEA is found/created, modify the TEA's spell table to make the attribute active for the specified period, and set the value of the corresponding spell to the contents of the value argument.  (This process is repeated for every element whose attribute is set in this fashion, with semantics corresponding to set.*.attribute.) 
     93 
     94For the deactivate methods, query the selected entities for a TEA with the specified prefix; if no such TEA exists and dynamic.only=FALSE, perform a secondary seek for an attribute with attrname==prefix.  If no acceptable attribute is found, exit.  Otherwise, modify the spell table of the attribute in question to force deactivation over the specified interval (converting the attribute to a TEA if necessary), adjusting the associated value list as necessary. 
     95 
     96==== get.*.attribute.active ==== 
     97 
     98The get.*.attribute.active methods function much like the corresponding conventional functions, but filter information in various ways based on the activity of the underlying attributes.  Usage is as follows: 
     99    {{{ 
     100get.edge.attribute.active(el, prefix, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
     101     
     102get.edge.value.active(x, prefix, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
     103     
     104get.network.attribute.active(x, prefix, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
     105     
     106get.vertex.attribute.active(x, prefix, onset, terminus=NULL, na.omit = FALSE, null.na = TRUE, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
     107    }}} 
     108Behavior sketch: For the entities in question, seek a TEA with the indicated name prefix (failing over to regular attributes with attrname==prefix if dynamic.only=FALSE).  Given such a TEA, return the dynamic value information corresponding to the query interval (with all query parameters interpreted as per is.active).  By default, the activity of the underlying entity is ignored; if require.active==TRUE, attributes are considered inactive when the entity to which they are attached is inactive (w/active.default being used where necessary to impute activity).  Return values are in TEA form, specifically a list containing a value list along with a spell list.   
     109 
     110==== list.*.attribute.active ==== 
    91111   
    92     activate.edge.attribute(x, prefix, value, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
    93     activate.edge.value(x, prefix, value, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
    94     activate.network.attribute(x, prefix, value, onset=-Inf, terminus=NULL, dynamic.only=FALSE) 
    95     activate.vertex.attribute(x, prefix, value, onset=-Inf, terminus=NULL, v=1:network.size(x), dynamic.only=FALSE) 
    96     deactivate.edge.attribute(x, prefix, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
    97     deactivate.edge.value(x, prefix, onset=-Inf, terminus=NULL, e=1:length(x$mel), dynamic.only=FALSE) 
    98     deactivate.network.attribute(x, prefix, onset=-Inf, terminus=NULL, dynamic.only=FALSE) 
    99     deactivate.vertex.attribute(x, prefix, onset=-Inf, terminus=NULL, v=1:network.size(x), dynamic.only=FALSE) 
    100   
    101     Behavior sketch: For the activate methods, query the selected entities for a TEA with the specified prefix.  If no such TEA exists and dynamic.only==FALSE, perform a secondary seek with an attribute such that attrname==prefix; if such an attribute is found, convert it to a TEA, and otherwise (or if no such TEA exists and dynamic.only==TRUE) create a TEA with the appropriate prefix.  Once the appropriate TEA is found/created, modify the TEA's spell table to make the attribute active for the specified period, and set the value of the corresponding spell to the contents of the value argument.  (This process is repeated for every element whose attribute is set in this fashion, with semantics corresponding to set.*.attribute.) 
    102     For the deactivate methods, query the selected entities for a TEA with the specified prefix; if no such TEA exists and dynamic.only=FALSE, perform a secondary seek for an attribute with attrname==prefix.  If no acceptable attribute is found, exit.  Otherwise, modify the spell table of the attribute in question to force deactivation over the specified interval (converting the attribute to a TEA if necessary), adjusting the associated value list as necessary. 
     112The list.*.attribute.active methods act like their normal counterparts, but implement basic temporal query logic on top of their standard functionality.  Usage is as follows: 
     113{{{ 
     114list.network.attributes.active(x, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    103115 
    104   get.*.attribute.active 
     116list.edge.attributes.active(x, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    105117 
    106     The get.*.attribute.active methods function much like the corresponding conventional functions, but filter information in various ways based on the activity of the underlying attributes.  Usage is as follows: 
    107      
    108     get.edge.attribute.active(el, prefix, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    109     get.edge.value.active(x, prefix, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    110     get.network.attribute.active(x, prefix, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    111     get.vertex.attribute.active(x, prefix, onset, terminus=NULL, na.omit = FALSE, null.na = TRUE, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    112      
    113     Behavior sketch: For the entities in question, seek a TEA with the indicated name prefix (failing over to regular attributes with attrname==prefix if dynamic.only=FALSE).  Given such a TEA, return the dynamic value information corresponding to the query interval (with all query parameters interpreted as per is.active).  By default, the activity of the underlying entity is ignored; if require.active==TRUE, attributes are considered inactive when the entity to which they are attached is inactive (w/active.default being used where necessary to impute activity).  Return values are in TEA form, specifically a list containing a value list along with a spell list.   
     118list.vertex.attributes.active(x, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
     119}}} 
    114120 
    115   list.*.attribute.active 
    116    
    117     The list.*.attribute.active methods act like their normal counterparts, but implement basic temporal query logic on top of their standard functionality.  Usage is as follows: 
    118  
    119     list.network.attributes.active(x, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    120     list.edge.attributes.active(x, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    121     list.vertex.attributes.active(x, onset, terminus=NULL, rule = c("any", "all"), active.default = TRUE, dynamic.only=FALSE, require.active=FALSE) 
    122    
    123     Behavior sketch:  For the entity type in question, search the (onset,terminus) interval using the specified query rule for all active attributes, returning their names.  Query arguments correspond to is.active.  If dynamic.only==TRUE, only TEAs are considered; otherwise, non-TEA attributes are also employed (with activity as defined by active.default).  By default, no check is made to ensure that the underlying entity is active during the query interval; if require.active==TRUE, then, attributes are regarded as inactive when the entities to which they are attached are inactive (using active.default to determine this as needed). 
     121Behavior sketch:  For the entity type in question, search the (onset,terminus) interval using the specified query rule for all active attributes, returning their names.  Query arguments correspond to is.active.  If dynamic.only==TRUE, only TEAs are considered; otherwise, non-TEA attributes are also employed (with activity as defined by active.default).  By default, no check is made to ensure that the underlying entity is active during the query interval; if require.active==TRUE, then, attributes are regarded as inactive when the entities to which they are attached are inactive (using active.default to determine this as needed). 
    124122       
    125123 
    126 ===New Methods=== 
     124=== New Methods === 
    127125 
    128   In addition to extensions of standard methods, it may be useful to create more complex custom query methods for dynamic attributes.  Among these, some generalization of the "apply" function seems most useful; however, I am not yet sure how best to do this without creating a long list of methods.  This is an area that might be deferred until more experience with the basic functionality has been obtained. 
     126In addition to extensions of standard methods, it may be useful to create more complex custom query methods for dynamic attributes.  Among these, some generalization of the "apply" function seems most useful; however, I am not yet sure how best to do this without creating a long list of methods.  This is an area that might be deferred until more experience with the basic functionality has been obtained. 
    129127   
    130128