This sketch of a page is intended to help people understand and use the script visualizeRates.pl to make nice bubbleplots of Markov chain rate matrices. It was used to e.g. produce many of the figures in the Xrate paper, a description of our generic Phylo Grammar engine.
(A bubbleplot, as shown above, is a visualization of the rate matrix corresponding to a Wikipedia:substitution_model. The circle in the i'th row & j'th column is scaled such that its area is proportional to the substitution rate from state i to state j. Beneath the main matrix is an extra row, where the area of the circle in the j'th column is proportional to the equilibrium probability of state j.)
visualizeRates.pl is in the dart/perl subdirectory of the DART package: see Downloading Dart for info on how to get this. Run the program with no arguments to get a detailed help message with explanations of available command-line options.
The visualizeRates.pl script depends on the following perl modules, also included in DART:
- ChainDat.pm handles the conversion of Markov chain substitution models, specified in xrate format grammar files, to the so-called dat format (parsing parameters, etc.)
- Bubbles.pm does all of the graphics work
- PhyloGram.pm parses xrate format grammar files
- PhyloGram::Chain.pm models a Markov chain in a grammar file
- DartSexpr.pm is used by PhyloGram.pm to parse S-expressions
The default output of visualizeRates is a bubbleplot of the mutation rates, beneath which is a bubbleplot of the initial probability distribution. There are command-line flags to change many of the default graphics options. For example, the flag '--ratesonly' can be used to suppress display of the initial probability distribution.
A figure legend (for colorcodes, NOT figure captions) is printed at the bottom of the figure unless the '--nolegend' flag is set. Only some legend descriptions are automated; feel free to fix this!
visualizeRates.pl tries to guess an appropriate scale for the rates and initial probability distribution; you can change it manually with command-line options.
The script can output a file in either Postsript (.ps) or Encapsulated Postscript (.eps) format. If the outfile is specified and has an extension '.eps', it will automatically produce an eps file. If the outfile isn't specified but the command-line flag '--toeps' is, then it will produce an eps file. To manually convert a file 'bubbleplot.ps' to Encapsulated Postscript (.eps) format, do:
ps2epsi bubbleplot.ps bubbleplot.epsi eps2eps bubbleplot.epsi bubbleplot.eps
This is exactly what the script does internally. From a practical standpoint, the conversion to .eps encloses the graphic in a bounding box for inclusion in another (e.g. latex) document.
Some useful tips:
- In the algebraic expressions for rates and probabilities in parametric grammars, there must be whitespace separating operators from operands (e.g. 'ka*0.3' is not ok, but 'ka * 0.3' is).
- If you are getting latex errors (e.g. 'Dimensions too large'), check your grammar for very high rates and scale the bubbles using -rscale as appropriate.
-- Robert Bradley - 26 May 2006