D3.js Tips and Tricks: d3.js force directed graph example (basic)

Thursday, 14 March 2013

d3.js force directed graph example (basic)

The following post is a portion of the D3 Tips and Tricks document which is free to download. To use this post in context, consider it with the others in the blog or just download the pdf and / or the examples from the downloads page:-)

-------------------------------------------------------

Basic force directed graph showing directionality

As explained in the previous post, the example graphs explained here are a combination of Mike Bostock's Mobile Patent Suits graph and Force-Directed Graph with Mouseover graph.

The data for this example graph has been altered from the data that was comprised of litigants in the mobile patent war to fictitious peoples names and associated values (to represent the strength of the links between the two). In the original examples the data was contained in the graph code. In the following example it is loaded from a csv file named force.csv. The values loaded are as follows;

source,target,value
Harry,Sally,1.2
Harry,Mario,1.3
Sarah,Alice,0.2
Eveie,Alice,0.5
Peter,Alice,1.6
Mario,Alice,0.4
James,Alice,0.6
Harry,Carol,0.7
Harry,Nicky,0.8
Bobby,Frank,0.8
Alice,Mario,0.7
Harry,Lynne,0.5
Sarah,James,1.9
Roger,James,1.1
Maddy,James,0.3
Sonny,Roger,0.5
James,Roger,1.5
Alice,Peter,1.1
Johan,Peter,1.6
Alice,Eveie,0.5
Harry,Eveie,0.1
Eveie,Harry,2.0
Henry,Mikey,0.4
Elric,Mikey,0.6
James,Sarah,1.5
Alice,Sarah,0.6
James,Maddy,0.5
Peter,Johan,0.7

The code is as follows;

<!DOCTYPE html>
<meta charset="utf-8">
<script type="text/javascript" src="d3/d3.v3.js"></script>
<style>

path.link {
  fill: none;
  stroke: #666;
  stroke-width: 1.5px;
}

circle {
  fill: #ccc;
  stroke: #fff;
  stroke-width: 1.5px;
}

text {
  fill: #000;
  font: 10px sans-serif;
  pointer-events: none;
}

</style>
<body>
<script>

// get the data
d3.csv("data/force.csv", function(error, links) {

var nodes = {};

// Compute the distinct nodes from the links.
links.forEach(function(link) {
    link.source = nodes[link.source] || 
        (nodes[link.source] = {name: link.source});
    link.target = nodes[link.target] || 
        (nodes[link.target] = {name: link.target});
    link.value = +link.value;
});

var width = 960,
    height = 500;

var force = d3.layout.force()
    .nodes(d3.values(nodes))
    .links(links)
    .size([width, height])
    .linkDistance(60)
    .charge(-300)
    .on("tick", tick)
    .start();

var svg = d3.select("body").append("svg")
    .attr("width", width)
    .attr("height", height);

// build the arrow.
svg.append("svg:defs").selectAll("marker")
    .data(["end"])
  .enter().append("svg:marker")
    .attr("id", String)
    .attr("viewBox", "0 -5 10 10")
    .attr("refX", 15)
    .attr("refY", -1.5)
    .attr("markerWidth", 6)
    .attr("markerHeight", 6)
    .attr("orient", "auto")
  .append("svg:path")
    .attr("d", "M0,-5L10,0L0,5");

// add the links and the arrows
var path = svg.append("svg:g").selectAll("path")
    .data(force.links())
  .enter().append("svg:path")
    .attr("class", "link")
    .attr("marker-end", "url(#end)");

// define the nodes
var node = svg.selectAll(".node")
    .data(force.nodes())
  .enter().append("g")
    .attr("class", "node")
    .call(force.drag);

// add the nodes
node.append("circle")
    .attr("r", 5);

// add the text 
node.append("text")
    .attr("x", 12)
    .attr("dy", ".35em")
    .text(function(d) { return d.name; });

// add the curvy lines
function tick() {
    path.attr("d", function(d) {
        var dx = d.target.x - d.source.x,
            dy = d.target.y - d.source.y,
            dr = Math.sqrt(dx * dx + dy * dy);
        return "M" + 
            d.source.x + "," + 
            d.source.y + "A" + 
            dr + "," + dr + " 0 0,1 " + 
            d.target.x + "," + 
            d.target.y;
    });

    node
        .attr("transform", function(d) { 
            return "translate(" + d.x + "," + d.y + ")"; });
}

});

</script>
</body>
</html>

In a similar process to the one we went through when highlighting the function of the Sankey diagram, where there are areas that we have covered before, I will gloss over some details on the understanding that you will have already seen them explained in an earlier section (most likely the basic line graph example).

The first block we come across is the initial html section;

<!DOCTYPE html>
<meta charset="utf-8">
<script type="text/javascript" src="d3/d3.v3.js"></script>
<style>

The only thing slightly different with this example is that we load the d3.v3.js script earlier. This has no effect on running the code.

The next section loads the Cascading Style Sheets;

path.link {
  fill: none;
  stroke: #666;
  stroke-width: 1.5px;
}

circle {
  fill: #ccc;
  stroke: #fff;
  stroke-width: 1.5px;
}

text {
  fill: #000;
  font: 10px sans-serif;
  pointer-events: none;
}

We set styles for three elements and all the settings laid out are familiar to us from previous work.

Then we move into the JavaScript. Our first line loads our csv data file (`force.csv`) from our `data` directory.

d3.csv("data/force.csv", function(error, links) {

Then we declare an empty object (I still tend to think of these as arrays even though they're strictly not).

var nodes = {};

This will contain our data for our nodes. We don't have any separate node information in our data file, it's just link information, so we will be populating this in the next section...

links.forEach(function(link) {
    link.source = nodes[link.source] || 
        (nodes[link.source] = {name: link.source});
    link.target = nodes[link.target] || 
        (nodes[link.target] = {name: link.target});
    link.value = +link.value;
});

This block of code looks through all of out data from our csv file and for each link adds it as a node if it hasn't seen it before. It's quite clever how it works as it employs a neat JavaScript shorthand method using the double pipe (`||`) identifier.

So the line (expanded)...

link.source=nodes[link.source] || (nodes[link.source]={name: link.source});

... can be thought of as saying “*If* `link.source` *does not equal any of the `nodes` values then create a new element in the `nodes` object with the name of the `link.source` value being considered.*”. It could conceivably be written as follows (this is untested);

if (link.source != nodes[link.source]) {
    nodes[link.source] = {name: link.source}
};

Then the block of code goes on to test the `link.target` value in the same way. Then the `value` variable is converted to a number from a string if necessary (`link.value = +link.value;`).

The next block sets the size of our svg area that we'll be using;

var width = 960,
    height = 500;

The next section introduces the `force` function.

var force = d3.layout.force()
    .nodes(d3.values(nodes))
    .links(links)
    .size([width, height])
    .linkDistance(60)
    .charge(-300)
    .on("tick", tick)
    .start();

Full details for this function are found on the D3 Wiki, but the following is a rough description of the individual settings.

`var force = d3.layout.force()` makes sure we're using the `force` function.

`.nodes(d3.values(nodes))` sets our layout to the array of `nodes` as returned by the function `d3.values` (https://github.com/mbostock/d3/wiki/Arrays#wiki-d3_values). Put simply, it sets the nodes to the `nodes` we have previously set in our object.

`.links(links)` does for links what `.nodes` did for nodes.

`.size([width, height])` sets the available layout size to our predefined values. If we were using `gravity` as a force in the graph this would also set the gravitational centre. It also sets the initial random position for the elements of our graph.

`.linkDistance(60)` sets the target distance between linked nodes. As the graph begins and moves towards a steady state, the distance between each pair of linked nodes is computed and compared to the target distance; the links are then moved towards or away from each other, so as to converge on the set distance.

Setting this value (and other force values) can be something of a balancing act. For instance, here is the result of setting the `.linkDistance` to 160.

Here the charged nodes are trying to arrange themselves at an appropriate distance, but the length of the links means that their arrangement is not very pretty. Likewise if we change the value to 30 we get the following;

Here the link distance allows for a symmetrical layout, but the distance is too short to be practical.

`.charge(-300)` sets the force between nodes. Negative values of `charge` results in node repulsion, while a positive value results in node attraction. In our example, if we vary the value to 150 we get this result;

It's not exactly easy to spot, but the graph feels a little 'lazy'. The nodes don't find their equilibrium easily or at all. Setting the value higher than 300 (for our example) keeps all the nodes nice and spread out, but where there are other separate discrete linked nodes (as there are in our example) they tend to get forced away from the center of the defined area.

`.on("tick", tick)` runs the animation of the force layout one 'step'. It's these progression of steps that give the force layout diagram it's fluid movement.

`.start();` Starts the simulation; this method must be called when the layout is first created.

The next block of our code is the standard section that sets up our svg container.

var svg = d3.select("body").append("svg")
    .attr("width", width)
    .attr("height", height);

The next block of our code is used to create our arrowhead marker. I will be the first to admit that it has entered a realm of svg expertise that I do not have and the amount of extra memory power I would need to accumulate to understand it sufficiently to explain won't be occurring in the near future. Please accept my apologies and as a small token of my regret, accept the following links as an invitation to learn more: http://www.w3.org/TR/SVG/coords.html#ViewBoxAttribute and http://www.w3schools.com/svg/svg_reference.asp?.
What is useful to note here is that we define the label for our marker as `end`. We will use this in the next section to reference the marker as an object. This particular section of the code caused me some small amount of angst. The problem being when I attempted to adjust the width of the link lines in conjunction with the `value` set in the data for the link, it would also adjust the stroke-width of the arrowhead marker. Then when I attempted to adjust for the positioning of the arrow on the path, I could never get the maths right. Eventually I decided to stop struggling against it and the encode the value as line in a couple of different ways. One as opacity using discrete boundaries and the other using variable line width, but with the arrowheads a common size. We will cover both those solutions in the coming sections.

svg.append("svg:defs").selectAll("marker")
    .data(["end"])
  .enter().append("svg:marker")    
    .attr("id", String)
    .attr("viewBox", "0 -5 10 10")
    .attr("refX", 15)
    .attr("refY", -1.5)
    .attr("markerWidth", 6)
    .attr("markerHeight", 6)
    .attr("orient", "auto")
  .append("svg:path")
    .attr("d", "M0,-5L10,0L0,5");

The `.data(["end"]) ` line sets our tag for a future part of the script to find this block and draw the marker.

`.attr("refX", 15)` sets the offset of the arrow from the centre of the circle. While it is designated as the `X` offset, because the object is rotating, it doesn't correspond to the x (left and right) axis of the screen. The same is true of the `.attr("refY", -1.5)` line.

The `.attr("markerWidth", 6)` and `.attr("markerHeight", 6)` lines set the bounding box for the marker. So varying these will vary the space available for the marker.

The next block of code adds in our links as paths and uses the `#end` marker to draw the arrowhead on the end of it.

var path = svg.append("svg:g").selectAll("path")
    .data(force.links())
  .enter().append("svg:path")
    .attr("class", "link")
    .attr("marker-end", "url(#end)");

Then we define what our nodes are going to be.

var node = svg.selectAll(".node")
    .data(force.nodes())
  .enter().append("g")
    .attr("class", "node")
    .call(force.drag);

This uses the `nodes` data and adds the `.call(force.drag);` function which allows the node to be dragged by the mouse.

The next block adds the nodes as an svg circle.

node.append("circle")
    .attr("r", 5);

And then we add the name of the node with a suitable offset.

node.append("text")
    .attr("x", 12)
    .attr("dy", ".35em")
    .text(function(d) { return d.name; });

The last block of JavaScript is the `ticks` function. This block is responsible for updating the graph and most interestingly drawing the curvy lines between nodes.

function tick() {
    path.attr("d", function(d) {
        var dx = d.target.x – d.source.x,
            dy = d.target.y – d.source.y,
            dr = Math.sqrt(dx * dx + dy * dy);
        return "M" + 
            d.source.x + "," + 
            d.source.y + "A" + 
            dr + "," + dr + " 0 0,1 " + 
            d.target.x + "," + 
            d.target.y;
    });

    node
        .attr("transform", function(d) { 
            return "translate(" + d.x + "," + d.y + ")"; });
}

This is another example where there are some easily recognizable parts of the code that set the x and y points for the ends of each link (`d.source.x`, `d.source.y` for the start of the curve and `d.target.x`, `d.target.y` for the end of the curve) and a transformation for the node points, but the cleverness is in the combination of the math for the radius of the curve (`dr = Math.sqrt(dx * dx + dy * dy);`) and the formatting of the svg associated with it. This is sadly beyond the scope of what I can comfortable explain, so we will have to be content with “the magic happens here”.

The end result should be a tidy graph that demonstrates nodes and directional links between them.

The code and data for this example can be found as Basic Directional Force Layout Diagram on bl.ocks.org.

The above description (and heaps of other stuff) is in the D3 Tips and Tricks book that can be accessed from the downloads page of d3noob.org (Hey! IYou can get it for free. Why not?)

57 comments:

Aralo14 March 2013 at 06:49
Thanks!
ReplyDelete
Replies
Anonymous27 June 2013 at 03:53
Thanks..
ReplyDelete
Replies
Unknown5 July 2013 at 06:53
Can you suggest me a graph suitable for representation of a path from A to B which can have many possible paths. what i am looking for is a static graph (not movable).
ReplyDelete
Replies
Anonymous2 August 2013 at 08:21
would it be possible to highlight(change color) of the neighboring nodes / links on mouse hover over node please?
I am really trying to understand this, but I have only been able to understand some code from your example. but not enough to modify it to find all links between selected nodes.
can you kindly help please?
ReplyDelete
Replies
saipuck13 August 2013 at 15:54
Noob here to all things web/JS/D3 so wanted to say THANK YOU for all your efforts in sharing your experiences. It's been very helpful.

I'm still crawling my way through this example and got stuck at the '||' part. It appears that that section of code will modify 'links' in addition to 'nodes'?

So, written differently (easier to me), I think it would be something like:
```
if( link.source != nodes[ link.source]) {
nodes[link.source] = {name: link.source };
link.source = nodes[ link.source ]; // new
}
```
and another one for target?
ReplyDelete
Replies
rajesh keshri28 August 2013 at 00:35
Hello. I have four attributes source, target, link and type in csv. All the data in text format. which graph can be suited for my requirement. i tried with Hierarchical Edge Bundling (http://bl.ocks.org/mbostock/1044242). Butit did not satisfy my requirement. i couldn't be able to link with all my attributes. Please suggest any d3 graph.
ReplyDelete
Replies
Ashish Yete6 December 2013 at 01:22
Hi All,
I want to display some information in between the source and the target nodes,(ideally in the center of the lines joining the source and the target) is there any way i can do that?
any help will be greatly appreciated.

Thanks,
Ashish
ReplyDelete
Replies
Gino14 December 2013 at 09:57
Excellent!
Is it possible load the nodes with different colors and diameters?
Thank you!
ReplyDelete
Replies
Gino18 December 2013 at 06:58
Hi D3noob,
this is the js pieces of code that I added:

// --- code I adde to capture the rad value of the csv file columns ----
link.rad = +link.rad;
//-------------------------------------------------------------
});

...
...

//--- add the nodes
node.append("circle")
.attr("r", 8);
/*----- this piece of code doesn't work ----------------
.attr("r", (function(d) {
return d.rad;
}
));
--------------------------------------------------------*/

...
...

The HTML page and all the other js code is quite the same as your example.
The force_5.js is a file just like your csv file, exept that there's one more column (the rad parameter) of integer values (range 6 - 20)

If you can help me would be great.
Thanks!

//gino
ReplyDelete
Replies
Gino1 March 2014 at 09:56
Hi D3noob,
the example in the link:

http://bl.ocks.org/d3noob/5141278

seems not work in IE8, the error message say "d3 is undefined".

Have you any idea?
ReplyDelete
Replies
Unknown27 March 2014 at 21:09
Nice tutorial. As I was playing around with this code I changed the style sheet to make it more colourful. This is when I noticed that the arrow at the end of the line does to exist centred over the line. If you zoom right in you can see where the line connects to the node as the arrow head is slightly offset. This is much more noticeable when there is a strong disparity in the colours. I was wondering how to shift the arrow such that the end of the arrow point coincides with the end of the line?

Thanks Sean
ReplyDelete
Replies
Raja Sekhar20 May 2014 at 11:14
Is it possible to remove the curve shape and just add an arrow to a straight line which makes a simple look
ReplyDelete
Replies
Koushik30 May 2014 at 03:59
Hi D3noob,
Thanks for sharing this article. It helped me a lot :) However I'm stuck with one thing. For each node, I want to show some extra information like type, contact, level etc in a tooltip apart from the node name as label. Here is how my model looks which fetches values from the database:

this.source = DBUtil.GetDBString(dr, "ParentCode");
this.target = DBUtil.GetDBString(dr, "ChildCode");
this.nodetype = DBUtil.GetDBString(dr,"NodeType");
this.nodecontact = DBUtil.GetDBString(dr,"NodeContact");
this.nodelevel = DBUtil.GetDBString(dr,"NodeLevel");

How do I define these parameters for each node in my JavaScript method.
I was trying:

links.forEach(function (link) {
link.source = nodes[link.source] || (nodes[link.source] = { name: link.source });
link.target = nodes[link.target] || (nodes[link.target] = { name: link.target });

link.target.nodetype = link.nodetype ;
link.target.nodecontact = link.nodecontact ;
link.target.nodelevel = link.nodelevel ;

This works almost fine except it shows no data or "undefined" for the very 1st node i.e. the root node. Can you please suggest a workaround for this?

Regards,
Koushik.
ReplyDelete
Replies
Unknown17 July 2015 at 08:48
I am new to the game and found your book a great help in getting started with the graph designs. I am working on a force directed graph and was wondering if there is a simple way via a button to pause or stop the force so I can drag some nodes. I understand once I start the force any positioning I had done would be changed.

Thanks
Perry
ReplyDelete
Replies
Unknown16 March 2016 at 22:20
Thanks for this awesome example D3noob... i want to know how will the json file be like if we were to use the same example?
ReplyDelete
Replies
Daniel Morillo24 May 2017 at 10:13
Hi D3noob, thank you for your explanation. I am a student of engineering and I am learning about graph optimization in my university. To explain how to some optimization algorithms work I need a directed graph from my data. So, Could I use your code to create a example graph for some slides?
ReplyDelete
Replies