initializeTreeSeq: SLiM method initializeTreeSeq

Description Usage Arguments Details Value Copyright Author(s)

View source: R/slim_lang.R

Description

Documentation for SLiM function initializeTreeSeq, which is a method of the SLiM class Initialize. Note that the R function is a stub, it does not do anything in R (except bring up this documentation). It will only do anything useful when used inside a slim_block function further nested in a slim_script function call, where it will be translated into valid SLiM code as part of a full SLiM script.

Usage

1
2
3
4
5
6
7
initializeTreeSeq(
  recordMutations,
  simplificationRatio,
  simplificationInterval,
  checkCoalescence,
  runCrosschecks
)

Arguments

recordMutations

An object of type logical. Must be of length 1 (a singleton). The default value is T. See details for description.

simplificationRatio

An object of type null or integer or float. Must be of length 1 (a singleton). The default value is NULL. See details for description.

simplificationInterval

An object of type null or integer. Must be of length 1 (a singleton). The default value is NULL. See details for description.

checkCoalescence

An object of type logical. Must be of length 1 (a singleton). The default value is F. See details for description.

runCrosschecks

An object of type logical. Must be of length 1 (a singleton). The default value is F. See details for description.

Details

Configure options for tree sequence recording. 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. The recordMutations flag controls whether information about individual mutations is recorded or not. 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. The simplificationRatio and simplificationInterval parameters control how often automatic simplification of the recorded tree sequence occurs. This is a speed– memory tradeoff: more frequent simplification (lower simplificationRatio or smaller simplificationInterval) means the stored tree sequences will use less memory, but at a cost of somewhat longer run times. Conversely, a larger simplificationRatio or simplificationInterval means that SLiM will wait longer between simplifications. There are three ways these parameters can be used. With the first option, with a non- NULL simplificationRatio and a NULL value for simplificationInterval, SLiM will try to find an optimal generation interval for simplification such that the ratio of the memory used by the tree sequence tables, (before:after) simplification, is close to the requested ratio. The default of 10 (used if both simplificationRatio and simplificationInterval are NULL) thus requests that SLiM try to find a generation interval such that the maximum size of the stored tree sequences is ten times the size after simplification. INF may be supplied to indicate that automatic simplification should never occur; 0 may be supplied to indicate that automatic simplification should be performed at the end of every generation. Alternatively – the second option – simplificationRatio may be NULL and simplificationInterval may be set to the interval, in generations, between simplifications. This may provide more reliable performance, but the interval must be chosen carefully to avoid exceeding the available memory. The simplificationInterval value may be a very large number to specify that simplification should never occur (not INF, though, since it is an integer value), or 1 to simplify every generation. Finally – the third option – both parameters may be non-NULL, in which case simplificationRatio is used as described above, while simplificationInterval provides the initial interval first used by SLiM (and then subsequently increased or decreased to try to match the requested simplification ratio). The default initial interval, used when simplificationInterval is NULL, is usually 20; this is chosen to be relatively frequent, and thus unlikely to lead to a memory overflow, but it can result in rather slow spool-up for models where the equilibrium simplification interval, as determined by the simplification ratio, is much longer. It can therefore be helpful to set a larger initial interval so that the early part of the model run is not excessively bogged down in simplification. The checkCoalescence parameter controls whether a check for full coalescence is conducted after each simplification. If a model will call treeSeqCoalesced() to check for coalescence during its execution, checkCoalescence should be set to T. Since the coalescence checks entail a performance penalty, the default of F is preferable otherwise. See the documentation for treeSeqCoalesced() for further discussion. The runCrosschecks parameter controls whether cross-checks between SLiM’s internal data structures and the tree-sequence recording data structures will be conducted. These two sets of data structures record much the same thing (mutations in genomes), but using completely different representations, so such cross-checks can be useful to confirm that the two data structures do indeed represent the same conceptual state. This slows down the model considerably, however, and would normally be turned on only for debugging purposes, so it is turned off by default.

Value

An object of type void.

Copyright

This is documentation for a function in the SLiM software, and has been reproduced from the official manual, which can be found here: http://benhaller.com/slim/SLiM_Manual.pdf. This documentation is Copyright © 2016–2020 Philipp Messer. All rights reserved. More information about SLiM can be found on the official website: https://messerlab.org/slim/

Author(s)

Benjamin C Haller (bhaller@benhaller.com) and Philipp W Messer (messer@cornell.edu)


rdinnager/slimrlang documentation built on June 20, 2020, 8:17 p.m.