Changes between Version 7 and Version 8 of NetworkDynamicConverterFunctions


Ignore:
Timestamp:
10/17/12 18:32:32 (7 years ago)
Author:
skyebend
Comment:

drafting spec of how networkDynamic() should work

Legend:

Unmodified
Added
Removed
Modified
  • NetworkDynamicConverterFunctions

    v7 v8  
    55== A list of source / target schemas for dynamics == 
    66 
    7 === start network + edge toggles === 
     7=== toggles: start network + edge toggles === 
     8{{{[ onset, terminus, tail, head, onset.censored, terminus.censored, duration, edge.id}}} 
    89what about vertex dynamics? 
    910 
    10 === arrays of spells === 
     11=== changes: edge toggles with times and direction === 
     12likes toggles, but also includes a column indicating if edge was formed or dissolved 
     13 
     14=== spell matrix: arrays of spells === 
    1115possibly two arrays, one for edges and one for vertices 
    1216 
     
    3842== Problem == 
    3943 
    40 "as.*" syntax doesn't seem appropriate for these converter functions, since often need multiple data objects as input.  And for output usually need to specify which facet of network information should be returned (vertex vs. edges).  Also, the S3 method dispatching (as.nD.data.frame) is tricky since the data frame may be either toggles or spells.  Also, not much advantage to having a single "convert" function if you have to have to set lots of arguments, hard to have defaults sensible for each type.  
     44"as.*" syntax doesn't seem appropriate for these converter functions, since often need multiple data objects as input.  And for output usually need to specify which facet of network information should be returned (vertex vs. edges).  Also, the S3 method dispatching (as.nD.data.frame) is tricky since the data frame may be either toggles or spells.  Not much advantage to having a single "convert" function if you have to have to set lots of arguments, hard to have defaults sensible for each type.  
    4145 
    4246== Proposed methods and behaviors == 
    4347 
     48=== Importing to nD ===  
     49 Single function {{{networkDynamic()}}} that has arguments for specifying inputs of the various schemas. Arguments are not speced by object types o toggles and spells are both represented with data frames (or matrices.   
     50 
     51 
     52==== function ==== 
     53{{{ 
     54networkDynamic(base.net=NULL,edge.toggles=NULL,vertex.toggles=NULL, 
     55   edge.spells=NULL,vertex.spells=NULL,edge.changes=NULL,vertex.changes=NULL, 
     56   network.list=NULL,onsets=NULL,termini=NULL,vertex.pid=NULL,start,end...) 
     57}}} 
     58 
     59fill in edges and/or vertex spells in starting network using toggles.  Toggles arguments can be anything convertible into a matrix.  
    4460  
    45 Separate functions for each type of conversion. Name functions by schemas they are converting, not by object types of arguments because toggles and spells are both represented with data frames.  (maybe only keep an "as.data.frame" function aliased to most common use case? ).  I think so far only duration.matrix() is a published method, so that may be the only one we have to keep around.  
     61==== Arguments ==== 
     62 base.net:: a network object providing an initial network state for the toggles and changes versions. For spell versions it is copied to provide the basic network attributes (n,directed, etc) 
    4663 
    47  networkDynamic(base.net=NULL,network.list=NULL,edge.toggles=NULL,vertex.toggles=NULL,edge.spells=NULL,vertex.spells=NULL):: fill in edges and/or vertex spells in starting network using toggles.  Toggles arguments can be anything convertible into a matrix.  
     64 network.list:: a list of network objects assumed to describe sequential panels of network observations. Network sizes may vary. see onsets, termini, vertex.pid. 
    4865 
    49  For edge.toggles, assume first columns are [tail,head,time]. What times assumed for ties in initial network? 
     66 edge.toggles:: assume first columns are [tail,head,time]. What times assumed for ties in initial network? 
    5067 
    51  edge.spells format as [tail,head,onset,terminus] 
     68 edge.spells:: an object coercible to a matrix with first four columns assumed to be [tail,head,onset,terminus].  Each row defines an activity spell for an edge. tail and head are vertex.ids for the edge, there may be multiple rows for each edge. 
    5269 
    53  vertex.spells [vertex.id,onset,terminus]  
     70 vertex.spells:: an object coercible to a matrix with first three columns assumed to be [vertex.id,onset,terminus]. Each row defines an activity spell for the appropriate vertex, there may be multiple rows per vertex.  
    5471 
    55  onsets=seq(from=0,length=length(network.list)) 
     72 onsets:: an optional array of onset times to be assigned to the network panels of network.list. defaults to seq(from=0,length=length(network.list)) 
    5673  
    57  termini=seq(from=1,length=length(network.list) 
     74 termini:: an optional array of terminus times to be assigned to the network panels of network.list defaults to seq(from=1,length=length(network.list) 
    5875  
    59  vertex.pid=NULL 
     76 vertex.pid:: an optional name of a vertex attribute to be used as a unique vertex identifier when constructing nD from a network list with different sized networks. (Also allow for spell lists?) 
     77 
     78 start:: The beginning of the observation period describing the network (used to define censoring) 
     79 
     80 end:: The end of the observation period describing the network (used to define censoring) 
     81 
     82 ...::  additional arguments needed in the future, possible network attributes? 
     83 
     84 
     85 
     86==== behavior sketch ==== 
     87 
     88 network.list:: create a nD object using a list of networks (or objects like matrices convertible to networks). Timing of each panel of vertex and edges . spells taken from onsets and termini arguments (defaults to [0,1].[1,2] etc..). If vertex.pid is set to the name of a network attribute, use that attribute as the vertex. id when constructing a network (for when inputs are not the same sizes. Censoring of starting / ending networks? 
     89 
     90=== Exporting from nD === 
    6091  
    61  network.list:: create a nD object using a list of networks (or objects like matrices convertible to networks). Timing of each panel of vertex and edges . spells taken from onsets and termini arguments (defaults to [0,1].[1,2] etc..). If vertex.pid is set to the name of a network attribute, use that attribute as the vertex. id when constructing a network (for when inputs are not the same sizes. Censoring of starting / ending networks? 
     92(maybe only keep an "as.data.frame" function aliased to most common use case? ).  
     93 
     94 
    6295 
    6396 get.vertex.activity(nD, v=1:network.size(x),as.spellList=FALSE):: currently this returns a list of spell matrices, one for each v specified.  Add argument to return same info as a single spell matrix [onset.terminus,vertex.id].  Sort order by onset,terminus,vertex.id? Include attributes? 
     
    67100 get.slice.networks(networkDynamic, start=min(get.change.times(networkDynamic),end=max(get.change.times(networkDynamic),time.step=1,duration=1, rule="any"):: return a list with a series of networks produced by network.extract.  Allow specifying a series of onsets, termini  instead of / in addition to  start,step,duration,end ? 
    68101 
     102don't include export toggle methods unless we have a use case.  
     103 
    69104 
    70105== Questions: ==  
    71106 
    72 Should we use "fake" S3 method names to be consistent?  (i.e. networkDynamic.spell.list) 
     107Should we use "fake" S3 method names to be consistent?  (i.e. networkDynamic.spell.list): NO 
    73108 
    74109Is it better to pass in a network object to be populated YES, or specify full list of network options (directed,bipartite,etc)?  
     
    90125Support for non-numeric,non integer input ids. '''pid=attrName''' Sort into alphabetic order, assign to ids 1:n 
    91126 
    92 Remove: to-toggle methods.  
    93127 
    94128Add "include.censoring=T" attribute