ADMIXTOOLS version 8.0.2  9/06/24 (for Linux and Mac)

See README.INSTALL for installation info. 

The ADMIXTOOLS package implements 5 methods described in 
Patterson et al. (2012) Ancient Admixture in Human History. Details of the methods and algorithm can be found in this paper.

A user guide for qpAdm is now available in the supplementary materials for "Assessing the Performance of qpAdm:  A Statistical Tool for Studying Population Admixture" by Harney et al. (2020). 
https://gsajournals.figshare.com/articles/dataset/Supplemental_Material_for_Harney_et_al_2020/13403225?file=26425355
https://doi.org/10.25386/genetics.13403225.v2

The package contains 6 programs: 
convertf: See README.CONVERTF for documentation of programs for converting file formats.
qp3Pop: See README.3PopTest for details of running f_3 test. This test can be used as a format test of admixture with 3 populations.
qpBound: See README.3PopTest for details of running qpBound. This test can be used for estimating bounds on the admixture proportions, given 3 populations (2 reference and one target).
qpDstat: See README.Dstatistics for details of running D-statistics. This is a formal test of admixture with 4 populations.
qpF4Ratio: See README.F4RatioTest for details of running F4 ratio estimation. This program computes the admixture proportion by taking the ratio of two f4 tests.
rolloff:  See README.ROLLOFF/ README.ROLLOFF_OUTPUT for details for running rolloff. This program can be used for dating admixture events.
 
Executables and source code:
----------------------------
All C executables are in the bin/ directory.

We have placed source code for all C executables in the src/ directory, 
for users who wish to modify and recompile our programs.  For example, to
recompile the programs, type
"cd src"
"make clobber"
"make install"      

If you are building on a Mac, you will need gsl and openblas installed. 
"brew install gsl"
"brew install openblas"
"brew install argp" 

make using Makefile.mac in src

If these packages are not in standard directories, you can specify the 
appropriate include and library directories with the CFLAGS and LDFLAGS 
make variables. 
For example, on the Harvard Medical School O2 cluster, the command is:
'make CFLAGS="-I/n/app/openblas/0.2.19/include -I/n/app/gsl/2.3/include" LDFLAGS="-L/n/app/openblas/0.2.19/lib -L/n/app/gsl/2.3/lib/"'

If you have issues with missing lapacke symbols, for example "undefined reference to `LAPACKE_dlange'", run make with the corresponding additional libraries linked:
'make LDLIBS="-llapacke"' on Linux Mint 18. 
Similarly for Ubuntu, for "undefined reference to dspev_"
'make LDLIBS="-llapack"'

For questions about building this software: 
Matthew Mah <matthew_mah@hms.harvard.edu>

If you have trouble compiling and running our code, try compiling and
running the examples in the examples/ directory. Download the example
datasets from https://reich.hms.harvard.edu/sites/reich.hms.harvard.edu/files/inline-files/AdmixTools_Example_Data.tar_.gz
and untar in the root AdmixTools directory, creating a subdirectory called ./data. 

"cd examples"
"./mklog"

If you are unable to run the examples successfully, please contact
your system administrator for help, as this is probably systems issue which is
beyond our scope. 

Nick Patterson
<nickp@broadinstitute.org>


1)
version 7.0 has numerous upgrades.
a) Two new executables --qpfstats qpfmv allow precomputation of f-statistic basis.
This can greatly reduce computation costs.
b) qpAdm, qpWave, qpGraph support qpfstats output as input.
*** This is a much improved way of running with allsnps: YES.    ***
c)  A new experimental feature of qpGraph (halfscore: YES) allows
 comparison of 2 phylogenies + a (weak) goodness of fit score.  Be careful
 if running with a large number of populations and consider reducing block size say
 blgsize: .005

Version 7.0.2 has important bugfixes to qpfstats.  See README.qpfstats  

2)
Note that several of the new ideas implemented in version 7.0 were developed collaboratively with Robert Maier, 
who has implemented them along with the great majority of other ADMIXTOOLS functionality in R:
See https://github.com/uqrmaie1/admixtools
Executables run fast, and it has features not available in this C version, such as interactive exploration of graph phylogenies.
A manuscript describing the algorithmic ideas and providing documentation of the methods is in preparation.



*** Fairly NEW *** 
Lightweight onlline documentation added, thanks to Eric Deveaud                             
<executable>  or <executable> -h  to get brief documentation or

*** Fairly NEW ***  
Alter number of chromosomes:   
numchrom:  <zzz>
zzz should be the autosome number (default 22 -- the number for humans) 

Custom block numbers (for jackknife) 
blockname:  <bbb> 
bbb should contain a list of snps 1 / line followed by a block number (integer) 
block number should be at least 1.  -1 -> snp ignored.  If this option is used 
snps not in list will be ignored. 

*** New data format *** 
Version 8.0.0 supports a new data format transpose_geno (or tgeno) 
See ./transpose_info and ./convertf/README 
The key code for this was written by Matthew Mah 

Version 8.0.1 is a minor bugfix release.
Version 8.0.2 is a minor bugfix release, affecting transpose packed files > 2GB.

----------------------------
SOFTWARE COPYRIGHT NOTICE AGREEMENT
This software and its documentation are copyright (2010) by Harvard University 
and The Broad Institute. All rights are reserved. This software is supplied 
without any warranty or guaranteed support whatsoever. Neither Harvard 
University nor The Broad Institute can be responsible for its use, misuse, or 
functionality. The software may be freely copied for non-commercial purposes, 
provided this copyright notice is retained.