These instructions supersede any older version in the README file included with the program.
The binary packages and the source code can be downloaded from https://pm2.phs.ed.ac.uk/downloads/.
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.
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.
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.
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.
Distributed with the admixmap executable are the following:
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.
Set the parameters as environment variables by using the R commands:
Sys.setenv("RESULTSDIR" = "myresults")
Sys.setenv("RPLOTS" = "pdf")
There are two ways to specify the parameters:
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
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
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
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")