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. It is related to a phylogeny, but it is not a phylogeny and should not be mistaken for (or used as!) one.

1. Generating the Data

First you must obtain the necessary data -- you need population detail files (historic files are not necessary) 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. I generally use time slices of 100 or 50 updates, because storage is cheap and I like smooth graphs.

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

Producing a Flame Graph with flamegraph.py

flamegraph.py is a Python script found in avida-core/source/utils/hist_map/ which uses matplotlib to produce the flamegraph. (It requires both Python and matplotlib to work). It will handle both unzipped (.spop) and gzipped(.spop.gz) files.

To 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 detail files (.spop) use column 14 for phylogenetic depth and column 5 for number of organisms. (Older Avida population detail files with the .pop extension use columns 12 and 4, respectively.) 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 flame.pdf 14 5 detail-?00.spop* detail-??00.spop* detail-???00.spop* detail-????00.spop*

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.)

Producing a Flame Graph with hist_map and Matlab

This is the "classic" method.

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 detail files (.spop) use column 14 for phylogenetic depth and column 5 for number of organisms. (Older Avida population detail files with the .pop extension use columns 12 and 4, respectively.) 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.spop detail-??00.spop detail-???00.spop detail-????00.spop <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.

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