Skip to content
This repository has been archived by the owner on Jul 18, 2022. It is now read-only.

Graph Query API

Jump to bottom
Benjamin Bach edited this page Aug 2, 2021 · 1 revision

In a Nutshell

This page provides the complete API reference for querying data from networkcube as well as a small tutorial on what to do with queries.

Query API

Networkcube distinguishes between

  • individual objects (nodes, links, timesteps, locations, etc.. ), and
  • arrays of objects, called query arrays.

Both, objects and query arrays result from queries on the dynamic network.

  • Simple queries are individual function calls, e.g. someNode.attr('label').
  • Queries can be chained as in d3 or jQuery.

This sheet explains the API for querying dynamic graphs in networkcube.

Queries directly DynamicGraph

var g:networkcube.DynamicGraph = networkcube.getGraph().

Get all elements

  • g.nodes():NodeQuery
  • g.links():LinkQuery
  • g.times():TimeQuery
  • g.nodePairs():NodePairQuery
  • g.locations():LocationQuery

Get element by id (.X())

  • g.node(id:number) returns Node with id id;
  • g.link(id:number) returns Link with id id;
  • g.time(id:number) returns Time with id id;
  • g.location(id:number) returns Location with id id;
  • g.nodePair(id:number) returns NodePair with id id;
  • g.selections():Selection[]
  • future: (g.graph({nodes:Node[], links:Link[], times:Time[]}) returns a static WindowGraph.)

Data Objects

Data Objects are all memory objects that are stored with a DynamicGraph. e.g:

  • var n:Node = g.node(0);
  • var l:Link = g.link(0);
  • var p:NodePair = g.nodePair(0);
  • var t:Time = g.time(0);
  • var loc:Location = g.location(0);

Data Objects (DataObject)

DataObject is the generic high level object for all data objets in the graph.

For var d:DataObject = g.<someTypeHere>(), we can query:

  • d.attr(attributeName:string):any returns the value for that attribute. Temporal attributes (e.g. neighbors of nodes, return this TimeSeries object)
  • .presentIn(t1:Time, t2?:Time):boolean returns if the data object is defined in this time.
  • .isHighlighted():boolean returns if the object is highlighted.
  • .isVisible():boolean returns if the object is visible.
  • .selections():Selection[] returns the selections this object is .
  • .isSelected():boolean returns if the object is selected. Shorthand for d.selections().length > 0.

Nodes (Node extends DataObject)

Queries

  • .neighbors():NodeQuery

  • .neighbors(t:Time):NodeQuery returns neighbors for time t

  • .neighbors(t1:Time, t2:Time):NodeQuery returns neighbors between time t1 and t2

  • .outNeighbors():NodeQuery

  • .outNeighbors(t:Time):NodeQuery

  • .outNeighbors(t1:Time, t2:Time):NodeQuery

  • .inNeighbors():NodeQuery

  • .inNeighbors(t:Time):NodeQuery

  • .inNeighbors(t1:Time, t2:Time):NodeQuery

  • .links():LinkQuery

  • .links(t:Time):LinkQuery

  • .links(t1:Time, t2:Time):LinkQuery

  • .outLinks():LinkQuery

  • .outLinks(t:Time):LinkQuery

  • .outLinks(t1:Time, t2:Time):LinkQuery

  • .inLinks():LinkQuery

  • .inLinks(t:Time):LinkQuery

  • .inLinks(t1:Time, t2:Time):LinkQuery

  • .createAttribute(attributeName:string, f:Function):NodeQuery // creates an attribute for every object in the query. The attribute value is returned by the passed function.

  • .removeAttribute(attributeName:string):NodeQuery

  • .. one for every field, listed below.

Fields in DynamicGraph for node information

The following lists the index lists in DynamicGraph that containing only indices to other lists, but no objects.

  • label:string[] = [];
  • nodeType:string[] = [];
  • outLinks: ArrayTimeSeries<number>[] = []; // contains link ids only, since every GRAPH has its own EDGE object instance
  • inLinks: ArrayTimeSeries<number>[] = []; // contains link ids only, since every GRAPH has its own EDGE object instance
  • links: ArrayTimeSeries<number>[] = [];
  • outNeighbors: ArrayTimeSeries[] = [];` // contains node ids only, since every GRAPH has its own NODE object instance
  • inNeighbors: ArrayTimeSeries<number>[] = []; // contains node ids only, since every GRAPH has its own NODE object instance
  • neighbors: ArrayTimeSeries<number>[] = [];
  • selections: Selection[][] = [];
  • locations: ScalarTimeSeries<number>[] = [];

Link

Fields:

  • source:number[] = [];
  • target:number[] = [];
  • linkType:string[] = [];
  • directed:boolean[] = [];
  • nodePair:number[] = []; // array of all time ids (temporally ordered) when this link is present
  • presence:number[][] = []; // array of values per time this link is present. This is a generic field // that can be used for weights, e.g.
  • values:ScalarTimeSeries<any>[] = [];
  • selections: Selection[][] = [];
  • times: TimeQuery; all times this link's weight is not undefined

NodePair

  • source:Node;
  • target:Node;
  • links:Link[] = []

Time

  • time:any[] = [];
    // moment object
  • unixTime:number[] = [];
    // js date object
  • selections: Selection[][] = [];
  • links:LinkQuery All links that's weight is not undefined in this time

Location

  • label:string[] = [];
  • longitude:number[] = [];
  • latitude: number[] = [];

Selection

var s:Selection = g.getSelection(id);

  • `s.elements():ObjectQuery
  • s.color():string
  • s.name:string; elements:Object[]; acceptedType:string; color:string; id:number; showColor:boolean = true; filter:boolean = false; priority:number = 0;

Query objects

Query

A query is a set of data objects and provides specialized functions on those objects, described below. There are four ways you obtain queries:

  • using one of the functions on the dynamic network, described above,
  • call some function on an existing query,
  • call some function on a data object,
  • create a new query from an array of data objects: e.g. var nodeQuery = new NodeQuery(someNodes, dynamicGraph);

The following functions are common to all queries in networkcube.

  • .elements() returns a simple array or all elements in the query.
  • .first() returns first element
  • .last() returns first element
  • .contains(object:any)
  • .add(object:any)
  • .addAll(addAll)
  • .length

ObjectQuery extends Query

  • .attr(attributeName:string) returns different things..
  • .series(attributeName:string) returns TimeSeries.
  • .where(attributeName:string, any?) returns ObjectQuery.
  • .time(modifier:string, t1:Time, t2?:Time) returns ObjectQuery.
    • .time('in', t1:Time)
    • .time('in', t1:Time, t2:Time)
    • .time('before', t1:Time)
    • .time('after', t1:Time)
  • .highlighted():ObjectQuery
  • .selected():ObjectQuery
  • .visible():ObjectQuery
  • .sort(attributeName:string)
  • .forEach(d:Object, i:number)

NodeQuery

LinkQuery

  • sources: LinkQuery all source nodes of this set of links
  • target: LinkQuery all target nodes of this set of links

StringQuery extends Query

NumberQuery extends Query

  • min()
  • max()
  • mean()
  • stdev()
  • ... more stats here

TimeSeriesQuery extends Query

Tutorial

Queries are run agains a DynamicNetwork and return an array of JS objects. Queries in networkcube are similar to queries in d3 and jQuery, in that they use syntax chaining.

The principles for designing this query language should be simple and extensible.

The examples in this section are performed on the dynamic graph g:

 var g:networkcube.DynamicGraph = networkcube.getDynamicGraph();

For the query API, see [here](Query API)

Example Queries

Some examples of what queries in networkcube can do: *

Tutorial and Syntax

A detailed tutorial to queries.

A query returns one of four objects or data structures:

  • A single object. Objects in networkcube are: Node, Edge, Time, Location, NodePair, LinkType, or a scalar such as String, Number, or Boolean.
  • An array of objects. All objects have the same time.
  • A Time Series: In a time series, an index id refers to a time step and points to an individual element or an array.
  • A graph for a given time step or time interval. You can define the nodes and edge being present in this graph.

There are three types of queries in networkcube:

  • Object queries returns a set of object: etc.:NodeQuery, LinkQuery, TimeQuery
  • Attribute queries returning attribute values on objects
  • Time queries returning a time series
  • Aggregation queries returning an aggregated value on arrays or time series or numbers
  • Filter queries returning only element satisfying a condition, and
  • Operation queries performing an operation on a result, such as grouping or ordering by some value.

We walk through those queries individually in the following.

Object Queries

Return a ObjectQuery (NodeQuery, EdgeQuery, TimeQuery)

  • all nodes: g.get('nodes') returns a list of NodeQuery.
  • all links: g.get('links') returns a list of LinkQuery.
  • all links: g.get('times') returns a list of LinkQuery.
  • all links: g.get('locations') returns a list of Links.
  • node with type t: g.get('nodes').where('type', t) returns a NodeQuery.
  • link with type t: g.get('link').where('type', t) returns a LinkQuery.
  • node with id: g.node(id) short for g.get('nodes').where('id', id).get(0). returns Node.
  • time with id: g.time(id) returns a Time.

Attribute Queries

Objects returned by ObjectQuery can be stored as variables and can be the base for further queries.

 var n = g.node(id);
 var l = g.link(id);
 var nodes = g.get('nodes');

An objects attributes can be queried by the attr function (inspired by d3).

  • a node's neighbors: n.attr('neighbors') --> return an array NodeQuery.
  • a node's outgoing links: n.attr('outLinks') --> return an array LinkQuery.
  • a link's NodePair': l.attr('nodePair')--> return aNodePair`.
  • a link's LinkType: l.attr('linkType') --> return a LinkType.
  • all node's labels: nodes.attr('labels') returns a StringQuery
  • all links of a set of nodes nodes.attr('links') returns a LinkQuery.
  • all a node's locations: n.attr('location') returns a LocationQuery.

Temporal Queries

.time(modifier, t1, t2?)
  • links present in t: g.get('links').time('in', t) returns LinkQuery.
  • links present between t1 and t2: g.get('links').time('in',t1, t2), returns LinkQuery. //
  • a node's neighbors in time t: n.attr('neighbors').presentIn(t) //?time('in',t1)
  • a node's neighbors between time t1 and t2: n.attr('neighbors').time('in', t1, t2)
  • labels of all nodes present before t1: g.get('nodes').time('before', t1).
  • types of all nodes present before t1: g.get('nodes').time('before', t1).attr('type').

Time Series

Sometimes it can be necessary to keep the result of a temporal query organized by time stamp.

Instead of querying by attr or , query by series. Time series return a TimeSeries object that groups a type of query by time stamp

  • a time series of node locations: n.series('location') returns a TimeSeries query containing a `LocationQuery' for each time step.

Aggregation

TODO

Operations

  • order results: n.attr('neighbors').order('label')
  • group results by result attributes: n.attr('neighbors').group('location')

Wish List

  • Create higher level abstractions for attribute access, e.g. n.neighbors(), l.nodePair().
Clone this wiki locally