Skip to content

Drawing graphs

Jump to bottom
Felix Kling edited this page Dec 12, 2013 · 4 revisions

Important: The API for the visualization is in a very early stage and it is likely to change in future versions.

One of the main features of JSNetworkX is to easily draw graphs on a web page. In order to draw a graph, you need to include the latest version of the D3.js library.

Graphs are drawn using the force layout. Other layouts to choose from might be added in the future.

Once you have included D3, you can draw a graph with

jsnx.draw(G, options, bind)

The three arguments are:

  • G: The graph to draw
  • options: An object with layout and style settings (see below)
  • bind: A boolean, indicating whether changes to G (like adding, removing nodes) should be directly reflected in the visualization.

Have a look at how the examples are drawn. The "Getting Started" page also has a section about drawing.

Drawing options

The second argument is an object containing various settings for the visualization. Some of the are required, but most of them have sensible default values.

  • element (a DOM element) (required):
    The container in which the graph should be drawn. An SVG element is append to this element.

  • d3 (D3 instance):
    Use this option to pass a reference to the D3 library if the global d3 global is not available or does not refer to D3. If this option is not present, it is assumed that window.d3 refers to D3.

  • width (number or string):
    The width of the resulting visualization. If not present, the width of the parent element (element) will be used.

  • height (number or string):
    The height of the resulting visualization. If not present, the width of the parent element (element) will be used.

  • layout_attr (object):
    Settings with which the force layout should be initialized. The possible options correspond to the respective method names, for example linkDistance, linkStrength, etc. For more information, please refer to the force layout documentation.
    Since force.links, force.nodes and force.size are internally provided with values, these cannot be set externally.

The default value is:

    'layout_attr': {
        'charge': -120,
        'linkDistance': 40
     }

  • node_shape (string, default: circle): The element name of the node shape.

  • node_attr (object): The attributes which should be added to each node element. Which attributes are supported and/or make sense depend on the element used for representing nodes (see node_shape). The D3 method .attr() is called to set the attributes, so every value accepted by this method can be used.

The default value is:

    'node_attr': {
        'r': 10 // default element is circle, so the element will have a radius of 10
    }
  • node_style (object):
    The CSS style settings for each node. The D3 method .style() is called to set the attributes, so every value accepted by this method can be used.

The default value is:

    'node_style': {
        'stroke': '#333',
        'fill': '#999',
        'cursor': 'pointer'
    }

  • edge_attr (object):
    The attributes which should be added to each edge element. Edges are represented by path elements. The d attribute is automatically computed and should not be overridden. The D3 method .attr() is called to set the attributes, so every value accepted by this method can be used.

  • edge_style (object):
    The CSS style settings for each edge. The D3 method .style() is called to set the attributes, so every value accepted by this method can be used.

The default value is: 'edge_style': { 'stroke': '#000', 'stroke-width': 2 }

  • label_attr and edge_label_attr (object):
    Attributes for the text elements used to draw the labels.

  • label_style and edge_label_style (object):
    The CSS style settings for each node and edge label. The default values are:

      'label_style': {
      'text-anchor': 'middle',
      'dominant-baseline': 'central',
      'cursor': 'pointer',
      '-webkit-user-select': 'none',
      'fill': '#000'
  }

  'edge_label_style': {
      'font-size': '0.8em',
      'dominant-baseline': 'central',
      'text-anchor': 'middle',
      '-webkit-user-select': 'none'
  }

  • with_labels (boolean, default: false):
    If true, node labels are drawn.

  • labels (string|function|object):
    If this option is not set and with_labels is true, the node itself is used as label.

If labels is a string, the label value is taken from each node data, with the key being the value of labels. I.e. G.node[n][labels].

If labels is a function, the label value is the return value of this function. The function is called for each node and is passed one argument. This argument is the same datum bound to each node element with D3.

If labels is an object, each node is looked up in the object and the value is taken as label, i.e. labels[node].

  • with_edge_labels (boolean, default: false):
    If true, edge labels are drawn.

  • edge_labels (string|function):
    If this option is not set and with_labels is true, the label simply consist of both node names.

If edge_labels is a string, the label value is taken from each edge data, with the key being the value of edge_labels. I.e. G.get_edge_data(u,v)[edge_labels].

If labels is a function, the label value is the return value of this function. The function is called for each edge and is passed one argument. This argument is the same datum bound to each edge element with D3.

  • weighted (boolean, default: false):
    If true, the weight of each edge is considered when drawing the edge. If options.edge_labels is not provided and options.with_edge_labels is true, the weights are used as edge labels.

  • weighted_stroke (boolean, default: true):
    If true, the stroke width of each edge is relative to the weight of the edge. The maximum stroke width is the one defined in options.edge_style['stroke-width']. In that case this option must not be empty and must contain a number.

  • weights (string|function, default: "weight"):
    If weights is a string, the weight is taken from each edge datum, with the key being the value of weights. I.e. G.get_edge_data(u,v)[weights].

If weights is a function, the weight is the return value of this function. The function is called for each edge and is passed one argument. This argument is the same datum bound to each edge element with D3.

  • edge_offset (number|array|function, default: 10):
    This value defines the offset of the edge from the center of each node. This options is necessary to draw directed graphs properly. Otherwise, since the edge is normally drawn from the center of each node, the arrow heads won't be visible.
    If the nodes are represented by circles, this value should be the same as the radius of the circles.

If edge_offset is a number, this number will be used for both, the x and y offset of the edge, from the center of the node.

If edge_offset is an array, it must be of the form [x,y], with x and y being numbers.

If edge_offset is a function, it must return an array of the form [x,y] (as above). The function is called for each edge and is passed one argument. This argument is the same datum bound to each edge element with D3.

  • pan_zoom (object, default: {enabled: true, scale: true}):
    The value is an object with two properties, enabled and scale. If enabled is true, the graph can be panned and zoomed in and out (through scrolling).
    If scale is true, nodes will keep there size but the distance between nodes will increase/decrease. This mode turned out to be very useful to inspect dense graphs. If the shift key is pressed when zooming, a "normal" zoom is performed. If scale is false, the action are reversed (i.e. pressing shift performs a scaled zoom).
Clone this wiki locally