Users manual

Important notes

If you don't want to read the full manual, at least read the following important notes...

  1. If you want to simulate diploid data make sure that population and sample sizes are multiples of 2 (e.g. 60, not 59). In fact, in the diploid scenario, if you want to simulate a population of size n, you might want to input 2*n. If you want to know more you can read Simcoal2 manual about this topic.
  2. In some models, if you put high values, generating the model might be computationally intensive by itself. For example, if you do an island model with 100 demes, then 2 10.000 (100 by 100) item matrices will be created. You might have to wait, just to get the model created. Has an extreme example, if you simulate a Stepping Stone Model (SMM), 2D with a dimension of 100x100, this will require the creation of a matrix of 100.000.000 items (10.000 by 10.000), it won't fly, trust me...
  3. If you run Simcoal2 from inside m4s2, we try to monitor its progress, in some cases (some operating systems), that is not completely possible. If, when Simcoal2 is running m4s2 frozes, we suggest you to wait, most probably it is just Simcoal2 that is running. m4s2 will resume when Simcoal2 finishes.
  4. After Simcoal2 (and, maybe, Arlequin3) is run, m4s2 gives no more support (e.g., to do analysis). If you need such a tool, please contact us, as we would probably be interested in helping and cooperating in the creation of such a tool.

Introduction

The initial screen looks like this (you can click on the images to see a full-size version):

Available are:

Species modeler

The Species modeler main screen looks like this:

On the main window, a graphical description of the current "species" can be found. In this case we have 5 chromosome blocks. The first one repeats 2 times and the 3rd one 4 times.

Lets take as an example the second chromosome block (called "Complex Chromosme"). It is composed of 4 markers, one RFLP, one SNP, one Microsatellite and one DNA sequence.

For all markers, all the parameters are shown, e.g., for RFLPs mutation rate and recombination rate.

On the bottom left table current chromosome blocks are displayed. The user can create new ones (including specifiying number of repetitions) and edit or delete old ones.

On the bottom center table the markers on the currently choosen chromosome block are displayed, again the user can do the usual operations. Recombination and number of repetions of markers, being common parameters to all markers can be edited here.

On the bottom right table, the parameters for the marker currently choosen are presented, in this case, as a Microsatellite is choosen, the parameters are mutation rate, geometric parameter and range constraint. An excelent explanation about the underlying mutation model is available on Simcoal2 site.

We recomend the reading of Simcoal2 documentation to understand all possible markers, linkage patterns and underlying mutation models.

From other screens you can choose to create, erase or edit new species. Each species will have a name in order to be used on the demography modeler.

Demography modeler

The demography model includes 2 phases: choosing the model to simulate and parametrizing it.

Before the user can choose from a list of models, if there are external sources, the user is offered to load them, this can take some time, depending on the network.

Here is a screenshot of the model list (which can vary, depending on external sources):

So, in this case, we have nine visible models (more are would be available if the user scrolls down). We can see here several models: from a simple, constant size, single population model, to an Island model to a 2D Stepping Stone Model, among others. The user should click on the desired model (on the figure), and then click Next.

Here is a screenshot of the parametrization of a model. Different models have different parameters, thus different screens.

On the left, we can see an image documenting the model. On the right the parameters (name, description, type - integer or float, and a box that needs to be filled.

An important note over time: As we are modelling the coalescent, time 0 is now. All times (generations) are in the past. So, 0 is now, 100 is in the past, 200 is even more in the past. Time goes backward, think coalescent! Figurewise, the top of the figure represents the past, the bottom represents time 0 (i.e., now). As an example, in our figure, T1 is smaller than T2. T1 is, thus, a past event, but more recent than T2.

The user will choose the parameters, including which "species" to model (as designed on the Species Modeler).

If some constraints are violated (e.g., in this example T1 has to be smaller than T2) the system will warn the user, and won't proceed until the user makes the desired changes.

After this, the user can call Simcoal2 (if that was specified on the configuration screen - see below), specifying how many runs are desired and if the data is haploid or diploid. Again, if the simulation is diploid, than all population sizes and sample sizes have to be multiples of 2.

After the end of Simcoal2, Arlequin3 (if configured) can be called.

Configuration

The user can specify external model sources. Models can be specified and tested.

An example of adding extra models can be seen on the next image. We provide extra models ourselves (related to human and domesticated animals), please see here.

The user can also specify where Simcoal2 and Arlequin3 can be found (both programs might not be available in all the operating systems where m4s2 can run).

Odds and Ends

The screenshots might not be completely up to date with the current version. We only change them if there are major differences between the documented version and the current one.