Introduction
----------------

The goal of these scripts should be that you can reproduce the results from
Peter & Excoffier (2009). 

The script is written in GNU bash, and should therefore run easily under a linux
environment. However, running it under a Windows OS will require an additional
step. 


Installation 
----------------
0. (windows only) install cygwin (http://www.cygwin.com)
1. extract all files from the psc-vs-rfi.zip file to any folder.
2. download the ABCtoolbox (Wegmann et al., 2009) from
http://cmpg.unibe.ch/software/ABCtoolbox/ , move the ABCsampler binary (either
windows/linux) to the apps_windows or apps_linux subfolder in your extraction
folder
3. make sure you have the R software installed. If not, you may download the latest
	version from http://cran.r-project.org/
4. One of the two model choice procedures implemented (that by Beaumont, 2008) requires
	the VGAM R-package. If you do not have it installed, you may download it from
	http://cran.r-project.org
5. Open the run-psc-vs-rfi.sh file. In the first half, set your desired
options (see below).


Parameters
----------------
The following parameters may be set:
  windows:           set to true if you run the script under windows
  inputFilePath:     path to the input file, in arlequin format
  output:            output file
  logfile:           log file
  tidyUp:            set to true if you want all temporary files to be removed
  noLoci:            number of loci in the sample. If set to -1, automatically estimated
  sampleSize:        number of (diploid) samples. If set to -1, automatically estimated

Mutation model
  mu:                mean mutation rate (mutation rate as in simcoal (Excoffier et al, 2005)
  alpha:             shape parameter for mutation distribution among loci
  
PSC model parameters
  n0:                prior for n0, current population size
  a:                 prior for a, size change parameter
  t:                 prior for t, time since decline

RFI model parameters
  D:                 prior for D, number of demes
  N:                 prior for N, number of genes(1n) per deme
  Nm:                prior for Nm, Migration parameter
  T:                 prior for T, time to population split
  Na:                prior for Na, ancient population size
  S:                 prior for S, sampling parameter

ABC settings
  numberOfCPUs:      for dualcore/quadcore processors, sets how many
                     parallelized instances are run
  numberOfIterationsPerModel: size of ABC reference file
  numberOfRetainesSimulations: number of simulations retained for model choice

Model Choice parameters
  beaumont:          set to true to use the model choice procedure by Beaumont
                     (2008)
  pritchard:         set to true to use the model choice procedure by
                      Pritchard et al (1999)

Summary statistics: enter true to use the following statistic to summarize the
      data
  K:                 mean number of alleles per locus
  sdK:               standard deviation of K
  H:                 mean heterozygozity per locus
  sdH:               standard deviation of H
  GW:                Garza & Williamson (2001)'s M: K/(R+1)
  sdGW:              standard deviation of GW
  R:                 mean allelic range per locus
  sdR:               standard deviation of R
  FIS:               add FIS to summary statistics

Programs: set path/name to the programs to use; make sure to enter exact path
  abcSampler:         set path to ABCSampler
  coalescenceSimulator: set the version of simcoal you use
  ssCalculator:       set name of arlsumstat
  estimator:          give name of ABCest
  rPath:              Path to R binary, on many linux systems, just entering R
                      should be sufficient





Citation
--------------

If you use ABCSampler, please cite
Wegmann D, Leuenberger C, Neuenschwander S & Excoffier L (2009:
  ABCtoolbox: A versatile toolkit for Approximate Bayesian Computation
  Bioinformatics, submitted

If you use Simcoal, please cite
Excoffier L, Laval G & Schneider S (2005): Arlequin ver 3.0: An 
  integrated software package for population genetic data analysis
  Evolutionary Bioinformatics Online, 1, 47-50

If you use arlsumstat and abcEst, please cite
Laval G & Excoffier L (2005): Simcoal 2.0: a program to simulate genomic
  diversity over large recombining regions in a subdivided population with 
  complex history, Bioinformatics 20, 2485-2487

If you use R, please cite
R Development Core Team (2009). R: A language and environment for 
  statistical computing. R Foundation for Statistical Computing, 
  Vienna, Austria. ISBN 3-900051-07-0, URL http://www.R-project.org.
 
If you use the procedure by Beaumont, please cite
Beaumont M (2008) Joint determination of topology, divergence time and 
  immigration in population trees. In: Simulations, Genetics and Human 
  Prehistory (eds. Matsumura S, Forster P, Renfrew C), pp. 135-154. 
  McDonald Institute for Archaeological Research, Cambridge.

If you use this procedure by Pritchard et al, please cite
Pritchard JK, Seielstad MT, Perez-Lezaun A & Feldman MW (1999) 
  Population growth of human Y chromosomes: A study of Y chromosome
  microsatellites. Molecular Biology and Evolution 16, 1791-1798.