SMARTPOP

By default, each run of SMARTPOP creates a parameter file called SMARTPOP_parameters.txt. This has exactly the same format as the input parameter file such that running ./smartpop -i SMARTPOP_parameters.txt will run the exact same set of simulations as you formerly ran. This is possible due to the fact that the random seed is one of the input parameters.

4.1.1.3 Windows executable

The available windows executable only handle input files. SMARTPOP will read the file SMARTPOP_parameters.txt which must be in the same directory. For each new launch of SMARTPOP you must set the parameters by modifying this file. If you want the seed to be picked randomly, remember to erase the line with the seed keyword from the parameter files.

4.2 Simulation parameters

4.2.1 Verbose

It is recommended to begin using SMARTPOP with the verbose option on. This will make SMARTPOP return relevant information one the command line when the simulations are running. It is a good way to check that the parameters are set correctly, as well as to visualize the progress of the program.

4.2.2 Random seed

Simulations are highly reliant on random processes. Such processes are simulated via sequences of random numbers which are a large part of the program. Each time the program starts, it calls a random seed from which this sequence is produced uniquely. By default, the random seed is random, but it is possible to set it to repeat earlier runs.

4.2.3 Population size

The population size set in SMARTPOP corresponds to the census population size at the beginning of the simulation. If the population size is set to be non constant, this will change through time.

4.2.4 Sample size

Instead of analyzing the entire population, you can sample a certain number of individuals. This situation would match a “real life” situation where you do not have access to the DNA of your whole population. If you define a sample size, all the outputs (diversity, but also fasta and arlequin files) will be generated on a random sample in your population of the defined size.

4.2.5 Number of simulations

You can define the number of simulations that will be run with this set of parameters. If you are loading a set of simulations from a directory, this number must be smaller or equal to the number of saved simulations.

4.2.6 Number of generations to run

During each simulation, the population will evolve for a number of generations t between two sampling events. By default, there is only one sampling event at the end of those t generations, where output files are produced and diversity is measured. If you define multiple sampling events (N_Sampling) through time, then t defines the number of generations to run between two sampling:

4.2.7 Mating system and number of offspring

The mating system is described by two parameters, the polygamy and the cousin alliance. You can set a maximum number of mate per individual, either for both sex (flag polygamy), or for male (polygyny) or female (polyandry).
For the cousin alliance, you can set a preferiential alliance of one or more cousin using the flag mat (X=:1 random, 2 MBD/FZS, 3 MZD/MZS, 4 FZD/MBS, FBD/FBS).

4.2.8 Sibling matings

For any mating system, you can forbid the mating between full or half siblings using the flag inbreeding.

4.2.9 Demography parameters

The demograpy is defined by a Markovian function:
popsize(t+1)=a + b x popsize(t) + c x popsize(t)²
Based on three parameters a, b and c, this definition permits a large range of demographic scenarios. This table presents the most simple example:

4.2.10 Mutation rates

Each type of DNA (mitochondrial, X, Y and autosome) has two mutation rates: a transition and transversion rate. These rates must be set in mutations/site/generation. Overall mutation rates can be defined, but you can set transitions equal to transversions equal to half the total mutation rate, if you do not know the ratio of transition over transversion.
The rationale behind having only eight mutation rates is that mutation rates measured for mtDNA, Y, X and autosomes can be different by more than an order of magnitude. Similarly, transition rates are usually an order of magnitude higher than transversion rates.

4.2.1 Burn-in phase

By default, simulations will start with the entire population having the same DNA. Alternatively, a burn-in phase allows you to start with an accelerated evolutionary process that will force your population to reach a high diversity from which your simulation will start. In this process, a higher mutation rate is applied to your population which quickly increases the diversity. The accelerated evolution stops when a set number of generation has been running. Another phase of burnin with a normal mutation rate can follow by setting the flag burnin to this chosen number of generations
When dealing with multiple populations, both burnin phase simulate a metapopulation with no division. The split between population happens at the end of the burnin, letting all populations with a similar diversity.

4.2.12 DNA sequences

Each individual has a set of sex-linked DNA sequences:

• A mitochondrial sequence
• A sequence from the non-recombining Y chromosome
• A set of unlinked loci on the X chromosome
• A set of unlinked loci on the autosomes

It is possible to choose the length of each loci by type. Note: all autosomal loci must share the same length; all X loci must share the same length. It is also possible to choose the number of loci on X and autosomes.
For computational reasons, the length of sequences must be a multiple of 32, or it will be automatically forced to the next higher multiple of 32. For instance, if you enter a length of 33, your simulated locus will have 64 sites. The size of the DNA considered unnecessary for a study can be set to 0, making the simulations faster.

4.2.13 Outputs

SMARTPOP can produce different outputs for each simulation:

• A file with the simulated DNA (at the end of the run) in fasta format
• A file with the simulated DNA (at the end of the run) in arlequin format [2]

SMARTPOP also produces output for the whole set of simulations:

• A diversity file for of genetic diversity of a set sample
• A file with interpopulation diversity.

If the output name is set to 'foo' in the parameters, then the different files produced would be foo.fasta, foo.arl, fooall.txt and foobetween.txt.

4.3 Outputs

4.3.1 Diversity tables

A file is created for the diversity of the given sample. If a name is provided, and the file already exists, the results will append to the end of the existing file.
This file contains different summary statistics for the population for each sample. Each line represent a sample at a specific time. For each sample, for each DNA type, SMARTPOP will write in the file:

• Population size (not the sample size)
• Number of sites in the sequence evaluated
• Number of polymorphic sites
• Proportion of polymorphic sites
• Mean pairwise difference
• Number of haplotypes
• Allele heterozygosity
• Nei’s heterozygosity (i.e. heterozygosity averaged per site) [4]
• Theta Watterson θ_w
• Theta homozygosity θ_H
• Theta Pi θ_π
• Tajima’s D

4.3.2 Fasta

You can output the population, or a sample of it, in a fasta format file. Such a file can easily be piped through other population genetics software, such as COMPUTE from the libSequence package[5].

4.3.3 Arlequin

You can output the population, or a sample of it, in a file of the format of ARLEQUIN software. This allows you to make inferences on your simulations using ARLEQUIN [2].

4.4 Running SMARTPOP in parallel mode

It is possible to run SMARTPOP in parallel. You must build a specific version of SMARTPOP using C++ compiler including Message Parsing Interface, such as mpic++.
When running in parallel, the simulations are distributed across several cores at the beginning at the simulation. Each process will write on different files to avoid conflict.

4.6 Starting conditions: burn-in and pre-run

The starting conditions are a fundamental problem in forward-in-time simulations. How to determine the complete genetic set of the population from which the evolution starts? This is equivalent to asking what is the DNA state of an ancient population, which is totally unknown in most studies. In studies based on modern DNA, you have (at most) knowledge about past individuals who left descendant but nothing about the other past members of the population.
The question remains what to start the simulation with. A fully random DNA set is in no way meaningful. Instead the genetic patterns of real population is the result of a long evolutionary process that creates haplotypes - individuals still sharing a large part of their DNA sequence.
The start must therefore be a sequence shared among individuals. From this null diversity, one must produce an artificial diversity, to correspond to a real population. There are three options:

• Assumed equilibrium
  It is possible that the population is in a state of equilibrium. The definition of "equilibrium" in population genetics is quite vague, but it is agreed that such equilibrium will be reached by running simulations for a very long time. How long is long enough? It must be at least the TMRCA, to be independent of starting conditions.
  As an indicator, the mean and variance of the time to the most recent common ancestor (TMRCA) assuming a constant population size [3, 1, 6] is:
• Burn-In
  Alternatively, we offer the user the possibility to apply an accelerated mutation scheme on the population. It will assign a mutation rate one order of magnitude higher than the real rate, run some generations and stop once the a set number of generation is reached. The real simulation can then start from this point.
  This approach is novel to SMARTPOP.
• Make your own recipe
  With the flexibility of SMARTPOP, you can choose your own starting scheme. Controlling the mutation rate, you may reach higher diversity than equilibrium. You can also use the demography feature to create your own burn-in phase.

A Default parameters

B References