4 Output files

4.1 Log file

When FREGENE is executing, summary information describing the initial population, the simulation features and the evolution of the population over generations are sent to standard output, and can be redirected to a log file (see Example/log_example.xml).

4.2 Main output file (-o file_name; required)

The output file is formatted to enable its reuse as a -i input file. It contains the basic information as presented in Section 3.1. This file also contains variables required to ensure that, during iterated runs, FREGENE works with appropriate values. These variables detailed below and summarized in Table 1.

• $<IS\_SCALED>$ : = 1 if the output population is scaled. Then the output population size is the value specified by $<SEGMENTS>$ divided by the scaling factor; = 0 if the output population is unscaled: either the run was unscaled or a scaled run was terminated with a population expansion (using the -sel_exp option).
• $<SCALING\_FACTOR>$ : (we refer to this as $\lambda$ ) If $\lambda \ne1$ , the assigned population size and number of generations for the simulation are both divided by $\lambda$ , while the rate parameters are all multiplied by $\lambda$ . This allows the target population to be approximated with reduced computation time and memory requirements.
• $<GROUPS>$ and $<GROUPS\_SIZE>$ : gives the number of subpopulations and their respective sizes. These variables can be specified in the command line.
• $<SEED>$ : the random seed is updated automatically in case of successive runs of FREGENE. However, to allow run replications, the user might want to specify the same seed for multiple runs. This variable can be defined in the command line.
• $<NB\_SWAPPED\_SITES>$ and $<LIST\_SWAPPED\_SITES>$ : respectively the number and the location of sites for which the derived allele has become the major allele.
• $<NB\_SELECTED_\_SITES>$ : the number of sites under selection in the final generation. Each selected site is associated with a position ( $<POSN\_SELECTED\_SITES>$ ), a generation at which it arose ( $<SEL\_GENERATION>$ ), a value for the selection coefficient $s$ and for the dominance coefficient $h$ ( $<SEL\_COEF>$ and $<SEL\_DOM>$ ), and the subpopulation(s). $<GROUP\_SELECTED\_SITES>$ specifies in which subpopulation(s) each site is under selection. If a site is under selection only locally ($i.e.$ in the subpopulation where it arose), the number of the corresponding subpopulation is reported in that list. Otherwise, the site is under selection in all subpopulations, which is coded by 100 in the list.

4.3 Other output files enabled by additional options

Other files can be generated if the corresponding option, from the following list, is selected by the user in the command line:

• -sel file_name option:
  Calling this option, will print in file_name all the selected sites that have gone to fixation since the first generation (see Example/data/sel_example.txt). Selected sites are described by:
  1. Their position (Posn)
  2. Their $s$ value (SelCoef)
  3. Their $h$ value (SelDom)
  4. The generation at which they arose (SelGeneration)
  5. The generation at which the site reached fixation (Gener)
  6. The number subpopulation(s) in which the site is under selection: (GroupSel).

• -hz file_name option:
  If chosen, this option will print in file_name the homozygozity after each deletion interval (see Example/data/homozgyosity_example.txt). (N.B. We use ``homozygosity'' as shorthand for the probability that two random chromosomes are the same at a randomly-chosen site.)
• -freq file_name option:
  The allele counts of all polymorphic sites (under selection or not) in the final generation are printed in file_name. The first column is the position of the polymorphism and the second column is the corresponding allele count (see Example/data/freq_example.txt).

• -ADDS file_name1 ...file_name6 option:
  This option requires five file names as argument:
  1. file_name1 (see Example/data/Monitor_example.txt):
     In this file, each column corresponds to a generation. The first line gives the population mean fitness, the second and third lines are, respectively, the number of recombinant and non-recombinant individuals.

  2. file_name2 (see Example/data/List_fixed_example.txt):
     This lists all selected sites that have gone to fixation. Each site is described as previously (see -sel option).

  3. file_name3 (see Example/data/List_deleted_example.txt):
     The list of selected sites that have disappeared from the population.
  4. file_name4 (see Example/data/List_selected_example.txt):
     The list of all sites that were under selection at any time in the the simulation.
  5. file_name5 (see Example/data/List_Kept_example.txt):
     Sites that were under selection during at least two deletion operations.
  6. file_name6 (see Example/data/List_SwitchedOff_example.txt):
     Selected sites that were switched off during the simulation.

  The use of this option is useful to follow up the mutations that have appeared in the population over generations as well as for describing the behavior of the selection model, but it can generate large files.

• -af file_name option:
  This option writes in file_name information about all polymorphic sites present at the last generation (see Example/data/sim_example.txt). For each site (column), it records the position (1st line); the population MAF (2nd line) and swapping status (3rd line). If a site is not swapped (=0), then the minor allele is the derived allele, if (=1) the minor allele is ancestral.

• -bckMut file_name and -dbleHit file_name options:
  These two options, which can be called separately, keep track of new mutations that arose at a polymorphic site. If the ancestral allele mutates, it is a double hit, whereas if it is the derived allele, the site reverts to the ancestral allele: a back mutation.

  Each double hit and/or back mutation are described as follows:

  • Gener: the generation at which the event occurred.
  • Chromosome: the number of the chromosome on which the event occurred.
  • Posn: the position on the chromosome.
  • Swapped: specifies if the sites where the event has been recorded was swapped when it was notified.
  • Count: gives the number of copies of the allele in the population, when the event occurred. If swapped, this number represents the number of copies of the derived allele, otherwise, this represents the number of derived copies that present in the population at the time of the event.
  Multi hit (triple or over), which may be important in case of high mutation rates ($e.g.$ in viruses) are also tracked: if the same back mutation and/or double hit ($i.e.$ same location, chromosome and generation) appears more than once in the file. This option requires alleles to be counted in each generation, which slows the algorithm.

• -histAF int file_name option:
  This option enables the distribution of allele frequency to be tracked. Calling this function will create a vector whose first element is the cumulative number of monomorphic sites (allele frequency =0), and whose next 100 elements are then the cumulative number of sites for all percentiles of the allele frequency. This vector is refreshed and printed out every int generations, and the resulting matrix is saved in file_name.

• -RecOut file_name option:
  If chosen this option will save in file_name a summary of the recombination model. Regions (Level=0), subregions (Level=1) and hotspots (Level=2) are first described by their beginning and ending position (Posn_init and Posn_final). Per-base recombination rates (Intensity) are also stored: for subregions, background rates over the whole subregion are reported and, for hotspots, this column corresponds to the per-base recombination rate applicable throughout the given hotspot.