ADMIXMAP installation instructions

These instructions supersede any older version in the README file included with the program.

Obtaining and installing the binary package

The binary packages and the source code can be downloaded from https://pm2.phs.ed.ac.uk/downloads/.

Windows

Open the file admixmap-X.XX.XXXX.zip and unzip the contents into a suitable directory.

Admixmap may have problems if the filenames or directory paths contain spaces. For best results, extract the contents of the zip file to a directory for which the path does not contain any spaces.

Linux

Unpack the file admixmap-X.XX.XXXX-<arch>.tar.gz, where <arch> is the architecture of your machine (one of i686, x86_64 or x86_64-openmp), in a suitable directory (tar -xzf admixmap*.tar.gz). You may need to change the permissions in order to run the program. Use the command chmod a=x admixmap to do this.

You can move the executable admixmap.exe to any directory that is in your PATH. The R script (AdmixmapOutput.R) should not be moved, unless you edit the perl scripts to specify its new location.

Other platforms

The source code is available as a tarball as admixmap-X.XX.XXX-src.tar.gz. Instructions for compiling it are provided. The source code is also available from our Subversion repository: instructions for accessing the repository are here.

Requirements for running ADMIXMAP

For the program to be usable, R and Perl should be installed.

R is a free statistical analysis program that can be downloaded from http://www.r-project.org. If you are using Windows, you will need to add the path for R to your PATH. For Windows XP, go to Start-Control Panel-System. On the Advanced tab, click on Environment Variables. Select the PATH variable and click on Edit. Add the path of the R binary directory to the end of the path variable. This is usually something like ";C:\Program Files\R\bin".

Perl is included in Linux distributions. Windows users can download it from http://www.activestate.com/Products/activeperl.

Contents of the installed directory

Distributed with the admixmap executable are the following:

Running the program

From the command line, specifying an options file

This is the simplest (but not the most user-friendly) way to run the program.

If you have placed the ADMIXMAP executable in a directory that lies on your search path, the program can be invoked directly by typing

admixmap <optionsfile>

where optionsfile contains statements of the form optionname=value, one line per option name. The complete list of options supported can be obtained by typing

admixmap --options

A sample optionsfile, testArguments.txt is provided with the test files. To try this, using the test dataset and the options file testArguments.txt (supplied as an example), open a console window (Start -> Run ->cmd in Windows), navigate to the admixmap directory, and type

admixmap testArguments.txt

Note: Do not use the name 'args.txt' for your options file as this may be overwritten by the program. If the admixmap executable is in your current directory and you are running Linux, you may have to prefix the word admixmap with "./" (the current directory is not in your search path by default).

The output will be written to a directory named results.

To generate summary statistics, tables and graphics from the output files generated by ADMIXMAP you will need to run the script AdmixmapOutput.R. The easiest way to do this is to run the Perl script as described below. If for some reason you prefer to run the R script from the command line or from an R session, you can do this as follows:

If your output files are in a directory other than 'results', you will need to supply R with the directory name.You can also optionally specify which format you want the graphical output. Available formats are PostScript(default), pdf, jpeg and png. Suppose your results are in a subdirectory of the working directory called 'myresults' and you want pdf graphics.

If you are running R from an interactive session (Rterm, Rgui)

Set the parameters as environment variables by using the R commands:

Sys.setenv("RESULTSDIR" = "myresults")
Sys.setenv("RPLOTS" = "pdf")

If you are running the R script in batch mode

There are two ways to specify the parameters:

1. Using environment variables

First set the RESULTSDIR environment variable.

To do this in Linux use: export RESULTSDIR=myresults

and in Windows use: set RESULTSDIR=myresults

Then run the R script using either:

R --vanilla <AdmixmapOutput.R >myresults/Rlog.txt

or

R CMD BATCH --vanilla AdmixmapOutput.R myresults/Rlog.txt

2. Using command-line options

R --vanilla --args myresults pdf <AdmixmapOutput.R >myresults/Rlog.txt

Alternatively, if you have version 2.5 or later of R, you can use the 'Rscript' frontend:

Rscript AdmixmapOutput.R myresults pdf >resultsdir/Rlog.txt

Invoking the program from a Perl script

If you are running several analyses with different options, it is easiest to use a Perl script, based on the example scripts supplied, to automate the above steps. For each analysis, the Perl script

  1. specifies the program options (making it easy to see which options are changed in successive analyses)
  2. writes these analyses to a file
  3. starts admixmap with the options file .
  4. sets the environment variable RESULTSDIR
  5. runs the R script Consult the documentation for details of the options.

Viewing and editing Perl scripts is easier if you use a text editor that provides syntax highlighting, such as emacs (all platforms) or Crimson Editor (windows only).

To run the Perl script admixmap.pl, open a console window and type

perl admixmap.pl

You can now view the contents of the results directory. The file Rlog.txt contains a log file written by R.

If you want to do more processing of the program output, you can set the RESULTSDIR environment variable as described above, start an R session and run the R script by typing

source("AdmixmapOutput.R")