AMCMC, an R/C package for running Adaptive MCMC

This package is licensed for general copying, distribution and modification according to the GNU General Public License.

Note: This package is in a rather preliminary state, and there is lots of room for improvement, and it probably won't work well on some MCMC examples. Use at your own risk. Comments and suggestions are most welcome.

Computer Platforms: This package uses the C compiler ("cc" or "gcc") and was designed for Unix/Linux/Mac machines, where it should work without difficulty. With Mac OS X, it is necessary to first install gcc. This package does not run on Microsoft Windows at this time, due to the difficulties of interfacing with the C compiler; I may fix this in the future if there is sufficient demand.

FILES IN THIS DIRECTORY:

• amcmcinfo.txt -- documentation for the package, in plain text
  
  
• amcmc -- R source file
  
  
• amcmc.c -- C source file
  
  
• amcmc.so -- C pre-compiled file (compiled for i686 Debian Linux; not required)
  
  
• simple.c -- auxiliary C source file for a simple one-dimensional normal example
  
  
• baseball.c -- auxiliary C source file for the baseball data example

TO INSTALL AND USE THIS PACKAGE ON YOUR LOCAL MACHINE:

1. If your computer doesn't already have it, install the (free) R statistical software package, from e.g. CRAN or its Canadian mirror.
   
   
2. Copy the files amcmc and amcmc.c to a local directory.
   
   
3. Run R (usually with the command "R" at the Unix/Linux prompt) from that directory.
   
   
4. At the R prompt (i.e., from within R), type the command:

   source('amcmc')

   (This command will, among other things, create a dummy file "dummyhold.c", and then -- if necessary -- run the C compiler command 'R CMD SHLIB amcmc.c dummyhold.c'. NOTE: The file amcmc.so on this webpage was pre-compiled on Debian Linux [distribution 'lenny'] for i686 architecture, so it might perhaps work for you. But it is better to not copy this file, but rather let amcmc automatically redo the compiling locally as above.)
   
   
5. You can then (at the R prompt) use the command amcmc(), with many options; see the file amcmcinfo.txt for more information.

TO PRE-COMPILE YOUR OWN C FUNCTIONS:

As an alternative, you may pre-compile your density and/or functional in C, to allow for much faster computation. To do this:

1. Choose an appropriate filename, NAME (e.g. NAME="baseball").
   
   
2. Edit -- either directly, or with editcfns('NAME') -- your own auxiliary file NAME.c, so that it defines mydim, mydensity, and/or myfunctional as C functions. (See the example files simple.c and baseball.c.)
   
   
3. From within R, type the command:

   cfns('NAME')

   e.g. cfns('baseball').
   
   
4. You can now run amcmc() with the cdensity and/or cfunctional flags set to TRUE, to greatly speed up the running time:

   amcmc(cdensity=TRUE, cfunctional=TRUE, ...)

   or equivalently:

   amcmc(cfns=TRUE, ...)

5. To switch to another auxiliary C file, OTHERNAME.c, simply type the command:

   cfns('OTHERNAME')

6. To recompile the package without any user-defined pre-compiled C functions, simply type cfns() on its own, i.e. with a null argument.
   
   
7. You may optionally use editcfns('NAME') to edit and compile the auxiliary file NAME.c, or showcfns() to show the base name of the "current" auxiliary C file, i.e. the most recent one compiled. See the file amcmcinfo.txt for more information.

SOME RELATED RESEARCH PAPERS:

• J.S. Rosenthal, AMCMC: An R interface for adaptive MCMC (Comp. Stat. & Data Anal. 51:5467-5470, 2007) [This citation can be used when citing the AMCMC software.]
  
  
• G.O. Roberts and J.S. Rosenthal, Examples of adaptive MCMC (J. Comp. Graph. Stat., to appear.)
  
  
• G.O. Roberts and J.S. Rosenthal, Coupling and ergodicity of adaptive MCMC (J. Appl. Prob. 44:458-475, 2007.)

AND FINALLY:

This package is available at probability.ca/amcmc. See also the author's home page and contact information.