[Avida-SVN] r3398 - development/documentation
blwalker at myxo.css.msu.edu
blwalker at myxo.css.msu.edu
Thu Sep 10 13:39:25 PDT 2009
Author: blwalker
Date: 2009-09-10 16:39:25 -0400 (Thu, 10 Sep 2009)
New Revision: 3398
Added:
development/documentation/flamegraph.html
Modified:
development/documentation/index.html
Log:
Added flamegraph-creation documentation (both hist_map/matlab and python methods) to documentation.
Added: development/documentation/flamegraph.html
===================================================================
--- development/documentation/flamegraph.html (rev 0)
+++ development/documentation/flamegraph.html 2009-09-10 20:39:25 UTC (rev 3398)
@@ -0,0 +1,102 @@
+<html>
+<head>
+ <title>Avida : Creating a Flame Graph</title>
+ <link rel="stylesheet" type="text/css" href="main.css" />
+</head>
+<body>
+
+<div class="revision">
+Revised 2009-09-10 BLW
+</div>
+
+<p><a href="index.html">Return to the Index</a></p>
+<hr />
+
+<div align="center">
+<h1>Creating a Flame Graph</h1>
+</div>
+
+<p>
+A flame graph is a visual representation of genetic diversity and "speciation" through an Avida run, graphing genetic distance over time.
+</p>
+
+<h2>1. Generating the Data</h2>
+<p>
+First you must obtain the necessary data -- you need population detail files (historic files are not necessary). 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.
+</p>
+<p>
+Once you have your population files, there are two ways to create a flamegraph. Choose according to your preferred tools.
+</p>
+
+<h2>2a. Producing a Flame Graph with hist_map and Matlab</h2>
+This is the "classic" method.
+
+<h3>2a.1 hist_map</h3>
+<p>
+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.)
+</p>
+
+<p>
+Now run it:
+</p>
+<code>hist_map <column # of phylogenetic depth> <column # of number of organisms> <files> > <output file></code>
+<p>
+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:
+</p>
+<code>hist_map 12 4 detail-?00.pop detail-??00.pop detail-???00.pop detail-????00.pop > <output file></code>
+
+<p>
+When it has run, you may wish to check the reported number of rows -- it should be the number of detail files provided.
+</p>
+
+<h3>2a.2 Matlab</h3>
+<p>
+Load the file created by hist_map into matlab, using zl or your favorite matrix-loading tool. E.g.:
+</p>
+<code>flame_matrix = zl('<file generated by hist_map>');</code>
+<p>
+What you will actually graph is the transpose of the log of this matrix + 1:
+</p>
+<code>flame_graphable = (log(flame_matrix + 1))';</code>
+<p>
+Finally, pcolor it -- for flame-colored flame graphs, use the hot colormap:
+</p>
+<code>colormap('hot')</code>
+<br>
+<code>flame_graph = pcolor(flame_graphable)</code>
+<p>
+If at this point your flame graph is pure black, try the command
+</p>
+<code>shading flat</code>
+
+<h2>2b. Producing a Flame Graph with flamegraph.py</h2>
+<p>
+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.
+</p>
+<p>
+Please note that flamegraph.py requires Python and <a href="http://matplotlib.sourceforge.net/">matplotlib</a>.
+</p>
+
+<h3>2b.1 flamegraph.py</h3>
+<p>
+flamegraph.py does not require compilation. You can find it in source/utils/hist_map/
+</p>
+<p>
+Now run it:
+</p>
+<code>python flamegraph.py <output file> <column # of phylogenetic depth> <column # of number of organisms> <files> </code>
+<p>
+matplotlib can produce graphs in png, pdf, ps, eps, or svg format; choose the extension of your output file appropriately.
+</p>
+<p>
+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:
+</p>
+<code>python flamegraph.py <output file> 12 4 detail-?00.pop* detail-??00.pop* detail-???00.pop* detail-????00.pop* </code>
+<p>
+When it has run, you may wish to check the reported number of rows -- it should be the number of detail files provided.
+</p>
+<p>
+(If you wish to immediately see the graph produced, you can add the <code>-g</code> flag. The <code>-q</code> flag will stop all those "Processing..." messages from appearing.)
+</p>
+</body>
+</html>
\ No newline at end of file
Modified: development/documentation/index.html
===================================================================
--- development/documentation/index.html 2009-09-10 17:31:06 UTC (rev 3397)
+++ development/documentation/index.html 2009-09-10 20:39:25 UTC (rev 3398)
@@ -26,6 +26,7 @@
<br /><a href="structure.html">The Directory and File Structure</a>
<br /><a href="svn.html">Using Subversion to Obtain Avida</a>
<br />[@TODO]<a href="as_overview.html">The Avida Scripting Language</a>
+<br /><a href="flamegraph.html">Creating a Flame Graph</a>
</p>
More information about the Avida-cvs
mailing list