An Introduction to Graphviz with a Crazy Story About Turnips

Audience: Slightly nerdy, comfortable installing software, not afraid of using the command-line, somewhat OCD about organization

Graphviz is a graph visualization suite (clever name huh?) created by AT&T to quickly and powerfully map out complicated networks.  This compelling, open-source project will allow you to to see the emergence of patterns that are not immediately obvious, and to bring a better understanding of the whole out of the sum of its parts.  This software can be used “by hand” or can be wired in to your own software to dynamically generate graph visualizations.

But slow down a second…what is a graph?

Copyright © 1996-2004 AT&T. All rights reserved. A graph, simply put, is a representation of the connections between objects.  In “graph speak” these objects are referred to as nodes _or _vertices.  These nodes could be people on Facebook, destinations on a road trip, or steps in a set of directions. Edges _are the lines that connect the _nodes in a graph.  Nodes can have multiple edges (connections), linking them to any of the other nodes.  An easy way to understand this is to think of how all of your friends know each other.  Some might know each other only through you.  Some might have a mutual friend, or a friend of a friend.  The concept is very natural to us, but trying to represent it and communicate it to others can get tricky very quickly.

Okay, this seems pretty simple but what can I use it for?

Assuming you are familiar with Facebook we are going to discover how “friend recommendations” on Facebook might work.  This concept could be extended to any number of “recommendation” applications as seen on Amazon, it could be used to analyze shipping routes, to understand family trees, to model the spread of disease - the applications are innumerable. In our scenario, we will spell out how various characters in a story are related to each other.

We must keep in mind, however, on a website like Facebook, this gigantic graph of human relations is always changing and rearranging.  The beauty of a graph is not only to describe situations we know, but to illuminate patterns in what we do not know. Keep in mind that the word graph is somewhat of a tricky term._ We are tempted to think of a graph on a purely visual basis, but it must be understood that this visual diagram is just a representation of the structure of a graph.  A graph can easily be an object in computer memory that is never seen in a visual manner. _

Let’s get started so we can see how this graphviz thing works

As we said earlier, we are going to use the example of a group of characters.  Presently, we will describe their connections and then turn these ideas into a visual graph using graphviz.  Never fear, for all the build up, graphviz only has a few “commands” to learn.  Once you understand these simple concepts, creating a graph becomes intuitive.

And our story goes something like this

One foggy evening in Lumpwick, California, Danielle Seal fell off the back of a turnip truck. Literally.  With a great, but non-injurious thud the small child landed in a basket of turnips owned by Steve Derosier.

Though the townsfolk attempted to track the whereabouts of Danielle’s parents, it was slowly forgotten over the years since Danielle had taken to her adopted family so quickly.

Louis Landa (president of  the Organization of Turnip Growers, Promoters and Devourers) came to Steve one day with a drastic plea.__

“We have to do something!”, Louis exclaimed.

“Slow down, slow down Louis”, said Steve.

After several minutes of heated discourse, the matter was clear, something did have to be done. That night Steve explained the dilemma to Danielle, and she knew what she had to do.

According to the OTGPD, turnip consumption has met an all time low.  If the calculations and the turnip favorability models hold true, then the turnip industry is surely doomed.  The case was clear.  People are not eating enough turnips and something must be done.  The OTGPD scientists have been working tirelessly and, fortunately, they have a plan.  Someone must sail to the thought-to-be-mythical island of Turniptopia and return with the thought-to-be-mythical variety of blue turnip.

Through many perils and adventures too harrowing to recount, Danielle and her first mate (and member in good standing with the OTGPD) Vivian Meier had finally landed on the not-so-mythical-shores of Turniptopia. From the distance walks Katrina Rash with the not-really-too-very-mysterious blue turnip.

After a thought-provoking, impassioned and too wordy to transcribe conversation, Katrina agrees to sail back to Lumpwick and help the crew save the day. Without question the OTGPD’s fate, and indeed the fate of producers the world around, was saved by the arrival of the blue turnip from lands previously unknown.

With much celebration the town decides to commemorate the events with a plaque celebrating all those that played a part in those fateful events.  They have decided to symbolize this with a graph showing all the players in this tale and how they were connected to each other.

Sheesh, really?  Well, you read it didn’t you?  No more talk of turnips, lets get on with things!

Getting started with Graphviz

Graphviz must, of course, be downloaded and installed before you can use it.  Here is where you would want to do that. Let’s get started.  First we need to create a “dot” file.  We will call ours (how appropriate).  This is the file that will contain all of our graph information.  We will use different programs from graphviz to act on this information and do things for us (like generate images or create a “live” graph). Here is our first try.

digraph turnipheads {
    Danielle [label="Danielle Seal"]
    Steve [label="Steve Derosier"]
    Louis [label="Louis Landa"]
    Vivian [label="Vivian Meier"]
    Katrina [label="Katrina Rash"]

Now to see our graph in all its glory.  We will be using the dotty command, which will generate a “live” graph in a new window.  Run it like this:



[](/assets/2009/12/graphviz-single-nodes.png)Lets review a few things about the current file before we move on. The line di__graph turnipheads _tells dotty that we are creating a graph called “turnipheads” and that everything enclosed within “{“ and “}” is part of that graph. Each name is a node.  A node consists of a _node name (must be a single word), like Danielle and a set of options enclosed in “[” and “]”.  For now we will only worry about the label option.  It should be obvious what this does.

Now that we have our people we need some way of linking them together.

To link Steve Derosier to Danielle Seal we use the -> command.  Yes, it really is that simple.

digraph turnipheads {
    Danielle [label="Danielle Seal"]
    Steve [label="Steve Derosier"]
    Louis [label="Louis Landa"]
    Vivian [label="Vivian Meier"]
    Katrina [label="Katrina Rash"]


Running this the same was as above, you should have something like this.


So, now, let’s go ahead an map out the whole crew.  The only new thing you will see is that some people are linked to more than one person.  This is another part of the power of graphvis.  You worry about the connections, graphviz will worry about how to connect the various nodes.

digraph turnipheads {
    Danielle [label="Danielle Seal"]
    Steve [label="Steve Derosier"]
    Louis [label="Louis Landa"]
    Vivian [label="Vivian Meier"]
    Katrina [label="Katrina Rash"]


Your result should look something like this:


This is just the beginning

In our examples, we created our “dotfile” by hand.  Graphviz really starts to shine when you automate it.  Rather than entering all the data and connections by hand, there are a multitude of bindings, generators, translators, etc. that will help you create graphviz data out of existing data.

I look forward to hearing how you plan to use graphviz!


Visualize function calls with Graphviz - Tutorial at IBM Developer Works

Graphviz Documentation - (Official Documentation)

Graphviz Resources - (Interfaces, Language Bindings, Generators, Translators…)

How will you use Graphviz?

Granted this was a brief, and somewhat ridiculous, introduction to Graphviz I am wondering how you will use it?  Do you have any unique ideas for Graphviz?  Does it solve any problems for you?  Create more?

I’d like to hear your thoughts as well as any suggestions for future posts!