MCRobot (ver. 2.1) Help File

MCRobot (Markov Chain Robot) is a simulation program written for 32-bit Microsoft Windows operating systems that illustrates principles involved with the Markov Chain Monte Carlo (or MCMC) methods currently used in Bayesian statistical analyses.

MCRobot was originally written for the purpose of generating figures for the following paper:

Lewis, P. O.. 2001. Phylogenetic systematics turns a new leaf. Trends in Ecology and Evolution 16: 30-37.
 
The paper describes the MCMC methodology used in MCRobot, so this help file concentrates on the mechanics of using the program rather than explaining MCMC in detail. The title above is a link allowing you to download a PDF-format reprint of the paper.
 
The program proved to be such a nice teaching tool that more effort was subsequently invested (e.g. addition of Metropolis Coupled Markov Chain Monte Carlo, or MCMCMC, to illustrate the benefits of having additional "heated" chains). The program may be freely distributed but comes with no warranty of any kind. MCRobot was written by:

Paul O. Lewis
Department of Ecology and Evolutionary Biology
The University of Connecticut
75 North Eagleville Road Unit 3043
Storrs, CT 06269-3043
Ph: (860) 486-2069
Fax: (860) 486-6364
Email: paul.lewis@uconn.edu
WWW: http://lewis.eeb.uconn.edu/lewishome/

Quick Start Guide

When MCRobot starts, you will be presented with a plain black background. You can begin walking the robot by pressing Ctrl-F and continue walking the robot using Ctrl-N. Initially, the landscape has no topography, so the robot simply wanders aimlessly about. The robot walks in hops of varying length and changes direction randomly after each hop. A single Ctrl-F or Ctrl-N keystroke results in 100 hops (by default), with each endpoint marked by a colored dot and the path marked by a colored line.

The program is more interesting once at least one hill has been defined. Hills are represented by bivariate normal densities. To create a hill, drag the mouse (using the leftmost button) across the window to create a small box (don't make the box big; about one tenth of the diameter of the window is good for starters). The dimensions of the box determine the mean and standard deviation of each of the two variables of the bivariate normal density. (The standard deviation is constrained to be the same for each dimension.) Once the mouse button has been released, a dialog box will appear allowing you to refine the parameters governing the hill you just created. Things you might wish to change at this point include: (1) the name of the hill; (2) the correlation coefficient (e.g., to make a ridge from lower left to upper right, use a coefficient of about 0.8); and (3) the weight (used to determine how "high" this hill is relative to other defined hills).

Once a hill is defined, it will be shown on the background by two yellow contours. The inner contour defines the region of 50% probability, whereas the outer contour circumscribes the region containing 95% of the probability for that particular bivariate normal hill.

After defining one or more hills, the robot will spend most of its time around the defined hills. The points representing the hop endpoints will be distributed according to the overall density defined by the mixture of bivariate normal hills on the landscape. To see just the points without the lines connecting them, uncheck the Show trajectory box in the dialog box invoked by the Robot | Options... menu item. This dialog box allows you to modify a number of other parameters as well, including the size of the dots used to denote hop endpoints (the Dot radius), the number of hops to take at one time (the Number of steps per walk), and the hill definition parameters. The position at which the robot begins its walk can also be set, as can the average length of each hop. The hop length is determined by gamma distributed random deviates. The Robot | Options... dialog box allows you to change the mean and standard deviation of the hops.

The original MCRobot has been upgraded to allow multiple chains to be run simultaneously, with all chains except one (the "cold" chain) experiencing a posterior density (landscape) that has been flattened to varying degrees by raising the posterior density to a power between 0 and 1. The cold chain is always the blue one (naturally), with the hottest chain being the red one. Chains heated to intermediate degrees have intermediate colors. The power used for each chain is 1/k, where k is the chain's rank (cold chain is 1, first heated chain is 2, etc.). Thus, the chain of rank 4 experiences a density that has been raised to the power 0.25. The colors used for these chains do not scale the same way: I simply use wavelength 450 nm for the coldest chain, 730 nm for the hottest chain, and determine the colors of intermediate chains by dividing up the total interval into equal pieces. Thanks to Dan Bruton (http://www.physics.sfasu.edu/astro/color/spectra.html) for making code available to translate wavelengths into RGB color triplets!

The sampled landscape is by default show from a vantage point directly above the field on which the imaginary robots are moving. You may wish to view the landscape from a different angle. To do this, you must check allow rotation from the Robot | Options... dialog box (Ctrl-R toggles this feature on and off). (Note: this will cause any points you have already generated to disappear.) Once new points have been generated, click (and hold down) the right mouse button over the main window. This will change the display to show a wire-frame pyramid to use as a guide in choosing a new viewing angle (Note: initially you will be viewing the pyramid from directly above, so it will only being looking like a pyramid after you rotate it a bit). Still holding down the right mouse button, move the mouse up slowly. This will rotate the pyramid. Once the pyramid is at a viewing angle that is desirable, release the right mouse button to view the landscape at that angle. This feature is initially turned off because viewing things in 3D requires saving the third dimension (one more value to save for every point). Thus, if memory is at a premium, avoid checking the allow rotation box, or limit the number of points you generate.

Command Reference

File Menu

Open
Allows you to open a file containing hill definitions (among other things).
Save, Save As...
Allows you to save the current hill configuration (among other things) to a file to read in at a later time.
Save Landscape...
This command allows you to specify a file name that will be used to save the landscape in a form that can be read into Excel. This makes it possible to create a 3-D chart in Excel depicting the landscape in much more detail than the simple contours used by MCRobot.
Save as Metafile...
This command allows you to save everything you see in the main window at any point in time in the form of a Windows Metafile. TheWindows Metafile format is recognized by a number of programs, including Microsoft Word. I created the figures for Box 4 in the TREE paper mentioned in the introduction using this feature.
Exit
Causes program to quit

Edit Menu

Copy
Places current trajectory as seen in the programs main window on the Windows clipboard for pasting into other Windows applications (keyboard shortcut is Ctrl-C)

Chains Menu

Note: choosing any item from this menu will result in the program resetting itself (all points will be deleted, but hills that have been defined will remain).
1 chain
The MCMC sampler will consist of only one markov chain.
2 chains
The MCMC sampler will consist of two markov chains (i.e. robots) running in parallel, one "cold" and the other "heated". Only the cold chain is used for purposes of estimating posterior probabilities. The hot chain roams a surface representing a "flattened" version of the posterior density roamed by the cold chain. Because the surface roamed by the hot chain involves shallower valleys between hills, the hot chain can easily move from one hill to another. After each chain takes a step, an attempt is made to swap the states of the two chains. This swap will be successful if the elevation of the "hot" robot is about the same as the elevation of the "cold" robot, even if the two robots are on different hills. You may wish to toggle the display of trajectories (Ctrl-T) when using multiple chains, because these swaps result in a tangled web of lines that is somewhat distracting.
3 chains
The MCMC sampler will consist of three markov chains (i.e. robots), all running in parallel, with one the cold chain and the other two heated to varying degrees. See notes on "2 chains" above.
4 chains
The MCMC sampler will consist of four markov chains (i.e. robots), all running in parallel, with one the cold chain and the other three heated to varying degrees. See notes on "2 chains" above

Show Menu

Chain 1
Only shows points and trajectories for chain 1. Available regardless of the number of chains being run (keyboard shortcut is F1).
Chain 2
Only shows points and trajectories for chain 2. Available if more than one chain is being run (keyboard shortcut is F2)
Chain 3
Only shows points and trajectories for chain 3. Available if more than two chains are being run (keyboard shortcut is F3)
Chain 4
Only shows points and trajectories for chain 4. Only available if four chains are being run (keyboard shortcut is F4)
All Chains
Shows points and trajectories for all chains being run. The hottest chains are displayed first, the cold chain last because this nicely shows how the hotter chains are more dispersed in their wanderings than the colder chains (keyboard shortcut is F5).
Summarize
Pops up a message box with details about the number of points sampled (cold chain only) and the number of points falling inside the inner and outer contour lines. This gives you some idea of how well the MCMC sampler is doing at estimating posterior probabilities. The proportion of points falling in all the inner circles combined should be about 0.50 and the proportion of points inside all the outer circles combined should be about 0.95.

Robot Menu

Options...
Invokes a dialog box allowing user to change parameters relating to the robot's random walk (keyboard shortcut is Ctrl-O)
Start walking
Deletes all currently-stored points and starts a new trajectory (keyboard shortcut is Ctrl-F)
Continue walking
Continues previously-started trajectory where robot left off (keyboard shortcut is Ctrl-N)
Toggle trajectory display
Toggles whether or not connecting lines showing robot's trajectory are shown (keyboard shortcut is Ctrl-T)
Allow Rotation
Toggles whether or not coordinates for third dimension are saved, allowing rotation to new viewing angles by dragging the right mouse button (keyboard shortcut is Ctrl-R)
Increment dot size
Makes dots representing position of robot larger (keyboard shortcut is Ctrl-L)
Decrement dot size
Makes dots representing position of robot smaller (keyboard shortcut is Ctrl-S)
Refresh
Repaints the screen
Clear
Deletes all points