Documentation for LogFile class from SLiM
LogFile is a class that can, optionally, be used to log out a table of information about the running simulation to a text file. The information logged out is completely configurable with generators, including the ability to use custom Eidos code as a generator. The resulting file can be formatted with comma separators (a CSV file), tab separators (a TSV file), or with any custom separator string between data values. The file can be plain text or can be compressed in .gz format (decompressible at the command line with the gunzip utility, among other tools). When compression is enabled, writes out to disk are buffered in memory for better performance and smaller file size. A new LogFile object attached to the simulation can be created with the Community method createLogFile(), discussed in section 25.3.2. Any number of LogFile objects can be active simultaneously, writing to different files. Logging can be done automatically, at the end of ticks at a given periodic interval (e.g., every 10th tick). This automatic logging is optional, and a log row can always be generated explicitly by called logRow(). Flushing compressed data to disk can be done automatically after a given number of rows have been generated, or can be requested explicitly with a call to flush(). Generators always generate a single value in each logged row, resulting in a single column of data in the log file. Some built-in generators are provided by LogFile for the most common cases; these can be added to a given LogFile by calling the add...() methods documented below. A generator with custom Eidos code can be added with addCustomColumn(), and a generator that expects to be supplied with the value to write, rather than generating the value itself, can be added with addSuppliedColumn(). LogFile expects to be fully configured, with calls to add...() methods to add generators, before the first row of data is written out, to ensure consistency in the file's data. When the first row of data is written (or buffered), the LogFile's configuration will then be frozen, and calls to add...() will no longer be allowed. Columns will be written, in each row, in the order in which add...() calls are made on the LogFile, and they will be named in the file's header line as documented in those methods. It is an error to have two columns with the same name. LogFile is a subclass of the Eidos class Dictionary, but unlike other SLiM classes that are Dictionary subclasses, this does not allow you to attach arbitrary key-value pairs to the object. Instead, LogFile uses its Dictionary-ness to make the data from the last logged row available through getValue(), using the name of the generator (i.e., the name of the data column) as the key. One quirk of LogFile is that because its keys are defined by the columns that it generates, and columns can sometimes contain an NA value, LogFile's dictionary can, in effect, contain NULL values (representing NA); this is not normally allowed by Dictionary. This should cause no trouble; just be aware that getValue() on a LogFile might return NULL for a key, representing NA, and that the result of serialize() might contain NA values. Finally: as a general rule, if a Subpopulation is referenced by one of the add...X() methods below it may be supplied as an object if it already exists (p1), or by id (1) even if it does not yet exist. The resulting column will generally have a name of the form pX_colname, where X is the id of the specified subpopulation. If a subpopulation-specific data logger refers to a Subpopulation that does not exist at the time a given row is logged, NA will be written. This class has the following methods (functions):
This class has the following properties:
A property of type string or string or integer or integer or integer. This property is a constant, so it is not modifiable. Property Description: This Dictionary property has an override in LogFile to return, in order, the names of the log file columns, which are the keys for LogFile's dictionary.
A property of type string or string or integer or integer or integer. It is of length one (a singleton). This property is a constant, so it is not modifiable. Property Description: The path of the log file being written to. This may be changed with setFilePath().
A property of type string or string or integer or integer or integer. It is of length one (a singleton). This property is a constant, so it is not modifiable. Property Description: The interval for automatic logging; a new row of data will be logged every logInterval ticks. This may be changed with setLogInterval(). If automatic logging has been disabled, this property will be 0.
A property of type string or string or integer or integer or integer. It is of length one (a singleton). This property is a variable, so it is modifiable. Property Description: The precision of float output. To be exact, precision specifies the preferred number of significant digits that will be output for float values. The default is 6; values in [1,22] are legal, but 17 is probably the largest value that makes sense given the limits of double-precision floating point.
A property of type string or string or integer or integer or integer. It is of length one (a singleton). This property is a variable, so it is modifiable. Property Description: A user-defined integer value. The value of tag is initially undefined, and it is an error to try to read it; if you wish it to have a defined value, you must arrange that yourself by explicitly setting its value prior to using it elsewhere in your code. The value of tag is not used by SLiM; it is free for you to use.
Other LogFile:
addCustomColumn(),
addCycleStage(),
addCycle(),
addKeysAndValuesFrom(),
addMeanSDColumns(),
addPopulationSexRatio(),
addPopulationSize(),
addSubpopulationSexRatio(),
addSubpopulationSize(),
addSuppliedColumn(),
addTick(),
clearKeysAndValues(),
flush(),
logRow(),
setFilePath(),
setLogInterval(),
setSuppliedValue(),
setValue(),
willAutolog()