Revised 2009-09-10 BLW

Return to the Index

# Creating a Flame Graph

A flame graph is a visual representation of genetic diversity and "speciation" through an Avida run, graphing genetic distance over time.

## 1. Generating the Data

First you must obtain the necessary data -- you need population detail files (historic files are not necessary) or flame_data files. The default events.cfg generates these only every 50,000 updates, so you must change this to get finer timeslices. More timeslices yield a smoother graph, but also increase the storage space necessary for your run.

Once you have your population files, there are two ways to create a flamegraph. Choose according to your preferred tools.

## 2a. Producing a Flame Graph with hist_map and Matlab

This is the "classic" method.

### 2a.1 hist_map

If you have not already compiled hist_map, do so. It is located in source/utils/hist_map/, and you can simply use the Makefile. (Type "make" on the command line while in this directory.)

Now run it:

`hist_map <column # of phylogenetic depth> <column # of number of organisms> <files> > <output file>`

In the current default Avida, the population details files use column 12 for phylogenetic depth and column 4 for number of organisms. Additionally, you will want to ensure that hist_map reads the detail files the correct order. Altogether, your command should look something like this:

`hist_map 12 4 detail-?00.pop detail-??00.pop detail-???00.pop detail-????00.pop > <output file>`

When it has run, you may wish to check the reported number of rows -- it should be the number of detail files provided.

### 2a.2 Matlab

Load the file created by hist_map into matlab, using zl or your favorite matrix-loading tool. E.g.:

`flame_matrix = zl('<file generated by hist_map>');`

What you will actually graph is the transpose of the log of this matrix + 1:

`flame_graphable = (log(flame_matrix + 1))';`

Finally, pcolor it -- for flame-colored flame graphs, use the hot colormap:

`colormap('hot')`
`flame_graph = pcolor(flame_graphable)`

If at this point your flame graph is pure black, try the command

`shading flat`

## 2b. Producing a Flame Graph with flamegraph.py

This process is very similar, but requires only one step; all of the matlab steps are incorporated into the script. In addition, it can handle both unzipped (.pop) and gzipped(.pop.gz) files.

Please note that flamegraph.py requires Python and matplotlib.

### 2b.1 flamegraph.py

flamegraph.py does not require compilation. You can find it in source/utils/hist_map/

Now run it:

`python flamegraph.py <output file> <column # of phylogenetic depth> <column # of number of organisms> <files>`

matplotlib can produce graphs in png, pdf, ps, eps, or svg format; choose the extension of your output file appropriately.

In the current default Avida, the population details files use column 12 for phylogenetic depth and column 4 for number of organisms. Additionally, you will want to ensure that flamegraph.py reads the detail files the correct order, and that you include any files still gzipped. Altogether, your command should look something like this:

`python flamegraph.py <output file> 12 4 detail-?00.pop* detail-??00.pop* detail-???00.pop* detail-????00.pop*`

When it has run, you may wish to check the reported number of rows -- it should be the number of detail files provided.

(If you wish to immediately see the graph produced, you can add the `-g` flag. The `-q` flag will stop all those "Processing..." messages from appearing.)