|
145 | 145 | <p class="p3">The <span class="s3">avatar</span> parameter, if not <span class="s3">""</span>, sets a <span class="s3">string</span> value used to represent the species graphically, particularly in SLiMgui but perhaps in other contexts also.<span class="Apple-converted-space"> </span>The <span class="s3">avatar</span> should generally be a single character – usually an emoji corresponding to the species, such as <span class="s3">"</span><span class="s9">🦊</span><span class="s3">"</span> for foxes or <span class="s3">"</span><span class="s9">🐭</span><span class="s3">"</span> for mice.<span class="Apple-converted-space"> </span>If <span class="s3">avatar</span> is the empty string, <span class="s3">""</span>, SLiMgui will choose a default avatar.</p> |
146 | 146 | <p class="p3">The <span class="s3">color</span> parameter, if not <span class="s3">""</span>, sets a <span class="s3">string</span> color value used to represent the species in SLiMgui.<span class="Apple-converted-space"> </span>Colors may be specified by name, or with hexadecimal RGB values of the form <span class="s3">"#RRGGBB"</span> (see the Eidos manual for details).<span class="Apple-converted-space"> </span>If <span class="s3">color</span> is the empty string, <span class="s3">""</span>, SLiMgui will choose a default color.</p> |
147 | 147 | <p class="p4">(object<Trait>$)initializeTrait(string$ name, string$ type, [Nf$ baselineOffset = NULL], [float$ individualOffsetMean = 0.0], [float$ individualOffsetSD = 0.0], [logical$ directFitnessEffect = F], [logical$ baselineAccumulation = T])</p> |
148 | | -<p class="p3">Calling this function, added in SLiM 5.2, configures a phenotypic trait in the species being initialized.<span class="Apple-converted-space"> </span>The new <span class="s3">Trait</span> object is returned.<span class="Apple-converted-space"> </span>For more details on the way that traits work in SLiM, beyond what is given below, see the <span class="s3">Trait</span> class documentation.</p> |
| 148 | +<p class="p3">Calling this function, added in SLiM 6.0, configures a phenotypic trait in the species being initialized.<span class="Apple-converted-space"> </span>The new <span class="s3">Trait</span> object is returned.<span class="Apple-converted-space"> </span>For more details on the way that traits work in SLiM, beyond what is given below, see the <span class="s3">Trait</span> class documentation.</p> |
149 | 149 | <p class="p3">The <span class="s3">name</span> parameter gives the name of the new trait.<span class="Apple-converted-space"> </span>This may be any (non-empty) string, except that it must not have the same name as another trait in the species, it must be syntactically valid as an Eidos symbol (not containing a space, for example), and it must not conflict with the name of any existing property on the <span class="s3">Individual</span>, <span class="s3">Species</span>, <span class="s3">Mutation</span>, or <span class="s3">Substitution</span> classes.<span class="Apple-converted-space"> </span>These requirements are necessary because, after the new trait is created, new properties are added to those classes, with the same name as the new trait, for convenience.<span class="Apple-converted-space"> </span>The new <span class="s3">Individual</span> property allows trait values to be accessed directly through a property; for example, if the new trait is named <span class="s3">height</span>, getting and setting an individual’s trait value would be possible through the property <span class="s3">individual.height</span>.<span class="Apple-converted-space"> </span>The new <span class="s3">Species</span> property allows traits themselves to be accessed directly through a property; continuing the previous example, <span class="s3">sim.height</span> would provide the <span class="s3">Trait</span> object named <span class="s3">height</span>.<span class="Apple-converted-space"> </span>See the <span class="s3">Mutation</span> and <span class="s3">Substitution</span> classes for details on the trait-related properties defined for them.<span class="Apple-converted-space"> </span>If desired, <span class="s3">defineConstant()</span> may also be used to set up a global constant for a trait; for example, <span class="s3">defineConstant("height", height)</span> would allow the <span class="s3">Trait</span> object to be referenced simply as <span class="s3">height</span>.</p> |
150 | 150 | <p class="p3">The <span class="s3">type</span> parameter gives the type of trait to be created, as a <span class="s3">string</span> value.<span class="Apple-converted-space"> </span>This should be either <span class="s3">"multiplicative"</span>, if the trait value should be the result of multiplying effects together (as in a typical population-genetics model); <span class="s3">"additive"</span>, if the trait value should be the result of adding effects together (as in a typical quantitative-genetics model); or <span class="s3">"logistic"</span>, if the trait value should be the result of a logistic transformation of an additive trait value (for modeling a trait that represents a probability, such as a disease risk).<span class="Apple-converted-space"> </span>(Because the logistic trait type is based upon an underlying additive trait value that is transformed, it will often be grouped together in this manual as having “additive” effects; this is in reference to that underlying model, prior to the logistic transformation.)<span class="Apple-converted-space"> </span>The shorter versions <span class="s3">"m"</span>, <span class="s3">"a"</span>, and <span class="s3">"l"</span> are also allowed.</p> |
151 | 151 | <p class="p3">The <span class="s3">baselineOffset</span> parameter sets the baseline offset for the trait, incorporated (multiplicatively or additively) to the trait value of every individual.<span class="Apple-converted-space"> </span>If <span class="s3">NULL</span> is passed, the default baseline offset is <span class="s3">1.0</span> for multiplicative traits, <span class="s3">0.0</span> for additive and logistic traits, such that the baseline offset has no effect upon the trait value.<span class="Apple-converted-space"> </span>Note that for multiplicative traits all effects, including the baseline offset, will be clamped to a minimum of <span class="s3">0.0</span>.</p> |
152 | 152 | <p class="p3">The <span class="s3">individualOffsetMean</span> and <span class="s3">individualOffsetSD</span> parameters together define a normal distribution from which individual offsets are drawn to provide what is often called “environmental variance” or “developmental noise”.<span class="Apple-converted-space"> </span>For additive traits, these drawn values are used directly as individual offsets; for multiplicative traits, they are transformed with <span class="s3">exp()</span> before use (or alternatively, one could instead say that the values are drawn from a lognormal distribution with the given mean and standard deviation specified on the log scale); and for logistic traits, they are used directly as individual offsets for the underlying additive trait.<span class="Apple-converted-space"> </span>The default values for these parameters provide a zero-width individual offset distribution that produces no effect; for additive and logistic traits, the resulting effect is <span class="s3">0.0</span>, whereas for multiplicative traits it is <span class="s3">1.0</span> due to the <span class="s3">exp()</span> transform.<span class="Apple-converted-space"> </span>Note that individual offsets can be set on individuals with <span class="s3">setOffsetForTrait()</span> or the <span class="s3"><i><trait-name></i>Offset</span> property, both on class <span class="s3">Individual</span>, so you are not limited to this built-in mechanism for drawing individual offsets; it is just provided for convenience.</p> |
153 | 153 | <p class="p3">The <span class="s3">directFitnessEffect</span> parameter specifies whether the final calculated trait value for an individual should be used directly as a fitness effect for that individual.<span class="Apple-converted-space"> </span>This will typically be <span class="s3">T</span> (the default) in population-genetics models where the product of all mutation effects (<span class="s3">1+s</span> or <span class="s3">1+hs</span> for each mutation) is used as the fitness of the individual, but will typically be <span class="s3">F</span> in quantitative-genetics models where the sum of all mutation effects is a trait value that is then translated into a fitness effect through a fitness function.<span class="Apple-converted-space"> </span>It would also be <span class="s3">F</span> for any trait that affects an aspect of the individual other than fitness – dispersal distance, for example, or aggression.</p> |
154 | | -<p class="p3">Finally, the <span class="s3">baselineAccumulation</span> parameter specifies the behavior of the trait when fixed mutations are turned into <span class="s3">Substitution</span> objects (see section 1.5.2).<span class="Apple-converted-space"> </span>If <span class="s3">baselineAccumulation</span> is <span class="s3">F</span>, no special action is taken upon substitution, and so the effect of the substituted mutation will no longer be present; this was the behavior of SLiM prior to SLiM 5.2, and remains the behavior of the default trait for backward compatibility.<span class="Apple-converted-space"> </span>If <span class="s3">baselineAccumulation</span> is <span class="s3">T</span>, the effect of the substituted mutation will be combined (multiplicatively or additively, according to the trait type) into the trait’s baseline offset.<span class="Apple-converted-space"> </span>As a result, the trait values of individuals should not change across a substitution, because the effect that used to come from the mutation will now come from the baseline offset.<span class="Apple-converted-space"> </span>(If a <span class="s3">mutationEffect()</span> callback used to modify that effect, however, that modification will no longer occur, since <span class="s3">mutationEffect()</span> callbacks are not called for substitutions; in this case, it might be desirable to prevent substitution with <span class="s3">MutationType</span>’s <span class="s3">convertToSubstitution</span> property.)<span class="Apple-converted-space"> </span>Allowing baseline accumulation is usually desirable; it allows substitution to occur safely even in nonWF models (if <span class="s3">convertToSubstitution</span> is set to <span class="s3">T</span>), which can make such models more efficient.</p> |
155 | | -<p class="p3">The use of the <span class="s3">initializeTrait()</span> function is optional.<span class="Apple-converted-space"> </span>If it is not called, a new <span class="s3">Trait</span> object will be created automatically, with a name generated from the species name plus a <span class="s3">"T"</span>; typically, then, the name is <span class="s3">simT</span>, except in multispecies models.<span class="Apple-converted-space"> </span>This default trait is configured to be multiplicative, with default values for the other parameters except <span class="s3">directFitnessEffect</span>, which is <span class="s3">T</span> for the default trait, and <span class="s3">baselineAccumulation</span>, which is <span class="s3">F</span> for the default trait.<span class="Apple-converted-space"> </span>This provides the behavior of SLiM prior to the introduction of multiple traits in SLiM 5.2.<span class="Apple-converted-space"> </span>The creation of the default trait occurs as a side effect of the first call to <span class="s3">initializeMutationType()</span>, if <span class="s3">initializeTrait()</span> has not already been called.</p> |
| 154 | +<p class="p3">Finally, the <span class="s3">baselineAccumulation</span> parameter specifies the behavior of the trait when fixed mutations are turned into <span class="s3">Substitution</span> objects (see section 1.5.2).<span class="Apple-converted-space"> </span>If <span class="s3">baselineAccumulation</span> is <span class="s3">F</span>, no special action is taken upon substitution, and so the effect of the substituted mutation will no longer be present; this was the behavior of SLiM prior to SLiM 6.0, and remains the behavior of the default trait for backward compatibility.<span class="Apple-converted-space"> </span>If <span class="s3">baselineAccumulation</span> is <span class="s3">T</span>, the effect of the substituted mutation will be combined (multiplicatively or additively, according to the trait type) into the trait’s baseline offset.<span class="Apple-converted-space"> </span>As a result, the trait values of individuals should not change across a substitution, because the effect that used to come from the mutation will now come from the baseline offset.<span class="Apple-converted-space"> </span>(If a <span class="s3">mutationEffect()</span> callback used to modify that effect, however, that modification will no longer occur, since <span class="s3">mutationEffect()</span> callbacks are not called for substitutions; in this case, it might be desirable to prevent substitution with <span class="s3">MutationType</span>’s <span class="s3">convertToSubstitution</span> property.)<span class="Apple-converted-space"> </span>Allowing baseline accumulation is usually desirable; it allows substitution to occur safely even in nonWF models (if <span class="s3">convertToSubstitution</span> is set to <span class="s3">T</span>), which can make such models more efficient.</p> |
| 155 | +<p class="p3">The use of the <span class="s3">initializeTrait()</span> function is optional.<span class="Apple-converted-space"> </span>If it is not called, a new <span class="s3">Trait</span> object will be created automatically, with a name generated from the species name plus a <span class="s3">"T"</span>; typically, then, the name is <span class="s3">simT</span>, except in multispecies models.<span class="Apple-converted-space"> </span>This default trait is configured to be multiplicative, with default values for the other parameters except <span class="s3">directFitnessEffect</span>, which is <span class="s3">T</span> for the default trait, and <span class="s3">baselineAccumulation</span>, which is <span class="s3">F</span> for the default trait.<span class="Apple-converted-space"> </span>This provides the behavior of SLiM prior to the introduction of multiple traits in SLiM 6.0.<span class="Apple-converted-space"> </span>The creation of the default trait occurs as a side effect of the first call to <span class="s3">initializeMutationType()</span>, if <span class="s3">initializeTrait()</span> has not already been called.</p> |
156 | 156 | <p class="p4"><span class="s1">(void)initializeTreeSeq([logical$ recordMutations = T], [Nif$ simplificationRatio = NULL], [Ni$ simplificationInterval = NULL], [logical$ checkCoalescence = F], [logical$ runCrosschecks = F], [logical$ </span>retainCoalescentOnly<span class="s1"> = T]</span>, [Ns$ timeUnit = NULL]<span class="s1">)</span></p> |
157 | 157 | <p class="p3">Configure options for tree sequence recording.<span class="Apple-converted-space"> </span>Calling this function turns on tree sequence recording, as a side effect, for later reconstruction of the simulation’s evolutionary dynamics; if you do not want tree sequence recording to be enabled, do not call this function.<span class="Apple-converted-space"> </span>Note that tree-sequence recording internally uses SLiM’s “pedigree tracking” feature to uniquely identify individuals and haplosomes; however, if you want to use pedigree tracking in your script you must still enable it yourself with <span class="s3">initializeSLiMOptions(keepPedigrees=T)</span>.<span class="Apple-converted-space"> </span>A separate tree sequence will be recorded for each chromosome in the simulation, as configured with <span class="s3">initializeChromosome()</span>.</p> |
158 | 158 | <p class="p3">The <span class="s3">recordMutations</span> flag controls whether information about individual mutations is recorded or not.<span class="Apple-converted-space"> </span>Such recording takes time and memory, and so can be turned off if only the tree sequence itself is needed, but it is turned on by default since mutation recording is generally useful.</p> |
|
0 commit comments