Graph API

sigma.classes.graph

This class implements sigma's graph model. It is also usable as a standalone to deal with graph data in your applications. When the JavaScript file is loaded, if the sigma object is defined in the global scope, then the graph will be referenced at sigma.classes.graph. But if sigma is undefined, then the graph will simply be exported as graph.

Public methods

nodes() : array nodes( string ) : object nodes( array ) : array

• This methods is used to retrieve nodes from the graph. If no argument is given, then an array containing references to every nodes will be returned. The method can also be called with the ID of an node to only retrieve the related node, or an array of IDs to obtain an array of the specified nodes.

edges() : array edges( string ) : object edges( array ) : array

• This methods is used to retrieve edges from the graph. If no argument is given, then an array containing references to every edges will be returned. The method can also be called with the ID of an edge to only retrieve the related edge, or an array of IDs to obtain an array of the specified edges.

addNode( object ) : graph

• This method adds a node to the graph. The node must be an object, with a string under the key id. Except for this, it is possible to add any other attribute, that will be preserved all along the manipulations. Also, the node will be cloned when added to the graph, to prevent its id to be writable in the future.
• The method returns the graph instance.

addEdge( object ) : graph

• This method adds an edge to the graph. The edge must be an object, with a string under the key id, and strings under the keys source and target that are existing node IDs. Except for this, it is possible to add any other attribute, that will be preserved all along the manipulations. The edge will be cloned when added to the graph, to prevent its id, source and target to be writable in the future.
• The method returns the graph instance.

dropNode( string ) : graph

• This method takes an existing node id as argument and drops the related node from the graph. It also removes each edge that is bound to it, through the dropEdge method. An error is thrown if the node does not exist.
• The method returns the graph instance.

dropEdge( string ) : graph

• This method takes an existing edge id as argument and drops the related edge from the graph. An error is thrown if the edge does not exist.
• The method returns the graph instance.

degree( string, ?string ) : number degree( array, ?string ) : array

• This methods is used to retrieve the degree of one or several nodes. If the ID of a node is given, then its degree will be returned. If an array of existing node IDs is given, then the array of the corresponding degrees will be returned instead.
• It is also possible to specify as second argument the type of degree to retrieve:
  • By default the disconnected degree will be used (the number of edges that are connected to the node).
  • If "in" is given as second argument, then the incoming degrees will be returned (the number of edges that "come from" the node)
  • If "out" is given as second argument, then the outcoming degrees will be returned (the number of edges that "go to" the node)

read( object ) : graph

• This method reads an object and adds the nodes and edges, through the proper methods addNode and addEdge. It then returns the graph.
• Here is an example:

var myGraph = new graph();
myGraph.read({
  nodes: [
    { id: 'n0' },
    { id: 'n1' }
  ],
  edges: [
    {
      id: 'e0',
      source: 'n0',
      target: 'n1'
    }
  ]
});

console.log(
  myGraph.nodes().length,
  myGraph.edges().length
); // outputs 2 1

clear() : graph

• This method empties the nodes and edges arrays, as well as the different indexes, and then returns the graph. It is faster than removing by hand dropNode and dropEdge, since it basically just "reset" the graph.

kill( object ) : void

• This method kills the graph. It basically empties each index and methods attached to the graph, and destroys the references.

Static methods

For people who might want to implement graph algorithms (clustering, graph-specific metrics, etc...), sigma.classes.graph provides some static methods to help keeping custom indexes in the graph up to date through every method calls. Also, it is possible to add methods to help getting the indexes or just help manipulating the graphs.

addMethod(string, function)

• This static method adds a method that will be bound to the futurly created graph instances. Since these methods will be bound to their scope when the instances are created, it does not use the prototype. The reason is to make those methods catchable to keep eventual custom indexes up to date with custom bindings (see the attach and addIndex methods). And because of that, methods have to be added before instances are created to make them available.
• The first parameter is the name of the function, and the second parameter is the function. Here is an example:

sigma.classes.graph.addMethod('getNodesCount', function() {
  return this.nodesArray.length;
});

var myGraph = new sigma.classes.graph();
console.log(myGraph.getNodesCount()); // outputs 0

attach( methodName : string, key : string, function)

• This static method binds a function to a method. Anytime the specified method is called, the bound function is called right after, with the same arguments and in the same scope. To attach a function to the graph constructor, use "constructor" as the method name (first argument). To ensure a function is not bound several times to the same method, a unique key (second argument) must identify the function. And if the key is already present an error will be thrown.
• The main idea is to have a clean way to keep custom indexes up to date, for instance:

var timesAddNodeCalled = 0;
sigma.classes.graph.attach('addNode', 'timesAddNodeCalledInc', function() {
  timesAddNodeCalled++;
});

var myGraph = new sigma.classes.graph();
console.log(timesAddNodeCalled); // outputs 0

myGraph.addNode({ id: '1' }).addNode({ id: '2' });
console.log(timesAddNodeCalled); // outputs 2

addIndex(string, object)

• This static method will add a custom index. It takes as arguments the name of the index and an object containing all the different functions to bind to the methods, these methods name used as the keys in the object. It is of course possible to bind functions to any method, added with addMethod or by yourself.
• Here is a basic example, that creates an index to keep the number of nodes in the current graph. It also adds a method to provide a getter on that new index:

sigma.classes.graph.addIndex('nodesCount', {
  constructor: function() {
    this.nodesCount = 0;
  },
  addNode: function() {
    this.nodesCount++;
  },
  dropNode: function() {
    this.nodesCount--;
  }
});

sigma.classes.graph.addMethod('getNodesCount', function() {
  return this.nodesCount;
});

var myGraph = new sigma.classes.graph();
console.log(myGraph.getNodesCount()); // outputs 0

myGraph.addNode({ id: '1' }).addNode({ id: '2' });
console.log(myGraph.getNodesCount()); // outputs 2