wiki:NetworkDynamicConverterFunctions

Version 7 (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

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.

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.

For edge.toggles, assume first columns are [tail,head,time]. What times assumed for ties in initial network?

edge.spells format as [tail,head,onset,terminus]

vertex.spells [vertex.id,onset,terminus]

onsets=seq(from=0,length=length(network.list))

termini=seq(from=1,length=length(network.list)

vertex.pid=NULL

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?

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?
get.edge.activity(networkDynamic,as.spellList=FALSE)
currently this returns a list of spell matrices. Add "start" and "end" arguments for specifying censoring. Add argument to return same info as a single spell matrix [onset,terminus,tail,head,left.censored, right.censored, duration, edge.id]. Sort order by onset,terminus,tail,head,eid?.
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 to be populated YES, 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)?

Censoring behavior (Inf should not automatically be censored, right) change to start.censored, end.censored.

Implement for multiple head/tail set, or just return error?

Support multiplex edges.

Include missing edges / vertices in output? include.missing=FALSE If true, include extra column for missingness?

Argument to include additional columns for attributes? Or user should lookup using eids? (simple attributes would be fine, but lists of objects might not work in data.frame output.) include.attrs=c("attrName1","attrName2")

Support for non-numeric,non integer input ids. pid=attrName Sort into alphabetic order, assign to ids 1:n

Remove: to-toggle methods.

Add "include.censoring=T" attribute