readFromPopulationFile: SLiM method readFromPopulationFile
In rdinnager/slimrlang: Write SLiM Population Genetics Simulation Scripts in R

Description Usage Arguments Details Value Copyright Author(s)

Documentation for SLiM function readFromPopulationFile, which is a method of the SLiM class SLiMSim. 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.

1	readFromPopulationFile(filePath)

filePath

An object of type string. Must be of length 1 (a singleton). See details for description.

Read from a population initialization file, whether in text or binary format as previously specified to outputFull(), and return the generation counter value represented by the file’s contents (i.e., the generation at which the file was generated). Although this is most commonly used to set up initial populations (often in an Eidos event set to run in generation 1, immediately after simulation initialization), it may be called in any Eidos event; the current state of all populations will be wiped and replaced by the state in the file at filePath. All Eidos variables that are of type object and have element type Subpopulation, Genome, Mutation, Individual, or Substitution will be removed as a side effect of this method, since all such variables would refer to objects that no longer exist in the SLiM simulation; if you want to preserve any of that state, you should output it or save it to a file prior to this call. New symbols will be defined to refer to the new Subpopulation objects loaded from the file. If the file being read was written by a version of SLiM prior to 2.3, then for backward compatibility fitness values will be calculated immediately for any new subpopulations created by this call, which will trigger the calling of any activated and applicable fitness() callbacks. When reading files written by SLiM 2.3 or later, fitness values are not calculated as a side effect of this call (because the simulation will often need to evaluate interactions or modify other state prior to doing so). In SLiM 2.3 and later when using the WF model, calling readFromPopulationFile() from any context other than a late() event causes a warning; calling from a late() event is almost always correct in WF models, so that fitness values can be automatically recalculated by SLiM at the usual time in the generation cycle without the need to force their recalculation (see chapter 21, and comments on recalculateFitness() below). In SLiM 3.0 when using the nonWF model, calling readFromPopulationFile() from any context other than an early() event causes a warning; calling from an early() event is almost always correct in nonWF models, so that fitness values can be automatically recalculated by SLiM at the usual time in the generation cycle without the need to force their recalculation (see chapter 22, and comments on recalculateFitness() below). As of SLiM 2.1, this method changes the generation counter to the generation read from the file. If you do not want the generation counter to be changed, you can change it back after reading, by setting sim.generation to whatever value you wish. Note that restoring a saved past state and running forward again will not yield the same simulation results, because the random number generator’s state will not be the same; to ensure reproducibility from a given time point, setSeed() can be used to establish a new seed value. Any changes made to the simulation’s structure (mutation types, genomic element types, etc.) will not be wiped and re-established by readFromPopulationFile(); this method loads only the population’s state, not the simulation configuration, so care should be taken to ensure that the simulation structure meshes coherently with the loaded data. Indeed, state such as the selfing and cloning rates of subpopulations, values set into tag properties, and values set onto objects with setValue() will also be lost, since it is not saved out by outputFull(). Only information saved by outputFull() will be restored; all other state associated with the simulation’s subpopulations, individuals, genomes, mutations, and substitutions will be lost, and should be re-established by the model if it is still needed. As of SLiM 2.3, this method will read and restore the spatial positions of individuals if that information is present in the output file and the simulation has enabled continuous space (see outputFull() for details). If spatial positions are present in the output file but the simulation has not enabled continuous space (or the number of spatial dimensions does not match), an error will result. If the simulation has enabled continuous space but spatial positions are not present in the output file, the spatial positions of the individuals read will be undefined, but an error is not raised. As of SLiM 3.0, this method will read and restore the ages of individuals if that information is present in the output file and the simulation is based upon the nonWF model. If ages are present but the simulation uses a WF model, an error will result; the WF model does not use age information. If ages are not present but the simulation uses a nonWF model, an error will also result; the nonWF model requires age information. As of SLiM 3.3, this method will restore the nucleotides of nucleotide-based mutations, and will restore the ancestral nucleotide sequence, if that information is present in the output file. Loading an output file that contains nucleotide information in a non-nucleotide-based model, and vice versa, will produce an error. This method can also be used to read tree-sequence (.trees) files saved by treeSeqOutput() or generated by the Python pyslim package. When loading a tree sequence, a crosscheck of the loaded data will be performed to ensure that the tree sequence was well-formed and was loaded correctly. When running a Release build of SLiM, however, this crosscheck will only occur the first time that readFromPopulationFile() is called to load a tree sequence; subsequent calls will not perform this crosscheck, for greater speed when running models that load saved population state many times (such as models that are conditional on fixation). If you suspect that a tree sequence file might be corrupted or read incorrectly, running a Debug build of SLiM enables crosschecks after every load.

An object of type integer. Return will be of length 1 (a singleton)

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/

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.