3.8. Advanced Configuration File Features

Advanced configuration file features

Reusing previously defined objects

Especially when using multiple epochs, in some cases it is necessary to keep a particular factor in the fitness function, while changing other factors.

While this could be achieved, in principle, by copying the definition of the factor, this is not only error-prone but also resets any state present in the object. For example, an age dependent or exposure dependent frequency function keeps track of allele frequency changes through time, and ideally this shouldn't be disturbed when entering a new epoch. Likewise, a purifying fitness function may be initialized using a random tie breaker, and you may want to keep this same initialization throughout all your epochs.

Therefore, there is a way to attach an id to some of the objects with state or random initialization, and later refer to these.

For example:

<simulation>

...

    <fitnessFunction>
        <!-- fitness function which sets, for each site, all amino acids observed at least once
             in the alignment neutral, and unobserved deleterious -->
        <purifyingFitness id="observed-neutral">
            <feature>protein ABC</feature>
            <rank id="alignment">
                <order>observed</order>
                <breakTies>random</breakTies>
            </rank>
            <fitness>
                <minimumFitness>0.0</minimumFitness>
                <lowFitness>1.0</lowFitness>
            </fitness>
        </purifyingFitness>
    </fitnessFunction>

    <epoch>
        <name>neutral</name>
        <generationCount>1000</generationCount>

        <fitnessFunction>
            <purifyingFitness ref="observed-neutral" />
        </fitnessFunction>
    </epoch>

    <epoch>
       	<name>neutral + selection</name>
        <generationCount>1000</generationCount>

        <fitnessFunction>
       	    <purifyingFitness ref="observed-neutral" />

            <!-- Add a fitness function which results in positive selection
                 at one site -->
            <empiricalFitness>
                ...
            </empiricalFitness>
	</fitnessFunction>
    </epoch>

    ...

</simulation>

The attributes id and ref may be used for the following objects:

• <rank>
• any <fitnessFunction> factor

Using run-time parameters

The configuration file supports the use of parameters, for which values may be defined at run time. This may be done for all numeric configuration parameters. Parameters must start with a '$' sign.

For example, the following population block allows you to specify the actual population size as a run-time parameter, and would be useful to study the effect of population size on the simulation, by running the simulator with different values for the parameter populationSize.

<population>
    <populationSize>$populationSize</populationSize>
    <inoculum>all</inoculum>
</population>

In the above example the populationSize parameter should be introduced upon invoking the program:

java -jar /path/to/santa.jar -populationSize=10000 configuration_file.xml