wiki:NetworkDynamicConverterFunctions

Version 4 (modified by skyebend, 7 years ago) (diff)

--

Draft Specification for networkDynamic converter functions: Take 3

Skye is collecting info from several previous discussions on the developer list in hopes of finally generating a spec for the converter methods.

A list of source / target schemas for dynamics

start network + edge toggles

what about vertex dynamics?

arrays of spells

possibly two arrays, one for edges and one for vertices

list of networks

each network is one wave in discrete time possible subtypes, list of matrices, or sna style graph stack

file formats with dynamics

.net, .son, some xml formats

Current or existing partial implementations

list of nets to nD : as.networkDynamic.network.list()

edge spells to nD : as.networkDynamic.network(spells=x)

vertex spells to nD : ?

edge (and vertex) spells to nD : as.networkDynamic.data.frame(x,nodeInfo=)

edge toggles to nD : as.networkDynamic.network(toggles=x)

nD to edge spells : as.data.frame.networkDynamic() uses duration.matrix internally

nD to edge spells : duration.matrix()

nD to vertex spells : get.vertex.activity() - sortof, returns list not matrix

nD to toggles : ?

Problem

"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.

Proposed methods and behaviors

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.

networkDynamicFromToggles(startNet=NULL,edge.toggles=NULL,vertex.toggles=NULL)
fill in edges and/or vertex spells in starting network using toggles. Toggles arguments can be anything convertible into a matrix. For edges will assume first columns are [tail,head,time]. What times assumed for ties in initial network?
networkDynamicFromSpells(startNet=NULL, edge.spells=NULL,vertex.spells=NULL, ...<rest of network properties>)
create/populate a nD using edge and/or vertex spells? Spells are any object convertible into a matrix. Edges assume format as [tail,head,onset,terminus], vertices [vertex.id,onset,terminus]
networkDynamicFromNetworks(network.list,onsets=seq(from=0,length=length(network.list)),termini=seq(from=1,length=length(network.list),vertex.pid=NULL)
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.
get.vertex.activity(nD, v=1:network.size(x),as.spellList=FALSE)
currently this returns a list of spell matrices. Add argument to return same info as a single spell matrix [vertex.id,onset.terminus].
get.edge.activity(networkDynamic,as.spellList=FALSE)
currently this returns a list of spell matrices. Add argument to return same info as a single spell matrix [vertex.id,onset.terminus]
get.vertex.toggles(networkDynamic,base.net=FALSE)
Return an array of toggles [vertex.id,onset,terminus]. Optionally return a list, the first element of which is $base.net and has a network object with the first state of the network, second element ($toggles) is the toggle array.
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 ?

Questions:

Should we use "fake" S3 method names to be consistent? (i.e. networkDynamic.spell.list)

Is it better to pass in a network object, or specify full list of network options (directed,bipartite,etc)? For matrix input formats, better to assume column order, or allow specifying column indicies/names?

Preferred format for returned data objects? (array, matrix, data.frame)?