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

Description Usage Arguments Details Value Copyright Author(s)

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

defineSpatialMap(
  name,
  spatiality,
  gridSize,
  values,
  interpolate,
  valueRange,
  colors
)

`name`	An object of type string. Must be of length 1 (a singleton). See details for description.
`spatiality`	An object of type string. Must be of length 1 (a singleton). See details for description.
`gridSize`	An object of type null or integer. See details for description.
`values`	An object of type numeric. See details for description.
`interpolate`	An object of type logical. Must be of length 1 (a singleton). The default value is `F`. See details for description.
`valueRange`	An object of type null or integer or float. The default value is `NULL`. See details for description.
`colors`	An object of type null or string. The default value is `NULL`. See details for description.

Defines a spatial map for the subpopulation. The map will henceforth be identified by name. The map uses the spatial dimensions referenced by spatiality, which must be a subset of the dimensions defined for the simulation in initializeSLiMOptions(). Spatiality "x" is permitted for dimensionality "x"; spatiality "x", "y", or "xy" for dimensionality "xy"; and spatiality "x", "y", "z", "xy", "yz", "xz", or "xyz" for dimensionality "xyz". The spatial map is defined by a grid of values of a size specified by gridSize, which must have one value per spatial dimension (or gridSize may be NULL; see below); for a spatiality of "xz", for example, gridSize must be of length 2, specifying the size of the values grid in the x and z dimensions. The parameter values then gives the values of the grid; it must be of length equal to the product of the gridSize elements, and specifies values varying first (i.e., fastest) in the x dimension, then in y, then in z. Beginning in SLiM 2.6, the values parameter may be a matrix/array with the number of dimensions appropriate for the declared spatiality of the map; for example, a map with spatiality "xy" would require a (two-dimensional) matrix, whereas a map with spatiality of "xyz" would require a threedimensional array. (See the Eidos manual for discussion of matrices and arrays.) If a matrix/array argument is supplied for values, gridSize must either be NULL, or (for backward compatibility) may match the dimensions of values as they would be given by dim(values). The data in values is interpreted just as is described above for the vector case: varying first in x, then in y, then in z. BEWARE: since the values in Eidos matrices and arrays are stored in column- first order (following the convention established by R), this means that for a map with spatiality "xy" each column of the values matrix will provide map data as x varies and y remains constant. This will be confusing if you think of matrix columns as being "x” and matrix rows as being "y”, so try not to think that way; the opposite is true. This behavior is actually simple, self- consistent, and backward-compatible; if you before created a spatial map with a vector values before and a gridSize of c(x, y) specifying the dimensions of that vector, you can now supply matrix(values, nrow=x) for values to get exactly the same spatial map, and you can still supply the same value of c(x, y) for gridSize if you wish (or you may supply NULL). If, however, you are looking at a matrix as printed in the Eidos console, and want that matrix to be used as a spatial map in SLiM in the same orientation, you should use the transpose of the matrix, as supplied by the t() function. Actually, since matrices are printed in the console with each successive row having a larger index, whereas in Cartesian (x, y) coordinates yvalues increase as you go upward, you may also wish to reverse the order of rows in your matrix prior to transposing (or the order of columns after transposing), with an expression such as t(map[(nrow(map)-1): 0,]), in order to make the spatial map display in SLiMgui as you expect (since SLiMgui displays everything in Cartesian coordinates). Apologies if this is confusing; it would be nice if matrix notation, programming languages, and Descartes all agreed on such things, but they do not, so be very careful that your spatial maps are oriented as you wish them to be! Moving on to the other parameters of defineSpatialMap(): if interpolate is F, values across the spatial map are not interpolated; the value at a given point is equal to the nearest value defined by the grid of values specified. If interpolate is T, values across the spatial map will be interpolated (using linear, bilinear, or trilinear interpolation as appropriate) to produce spatially continuous variation in values. In either case, the corners of the value grid are exactly aligned with the corners of the spatial boundaries of the subpopulation as specified by setSpatialBoundary(), and the value grid is then stretched across the spatial extent of the subpopulation in such a manner as to produce equal spacing between the values along each dimension. The setting of interpolation only affects how values between these grid points are calculated: by nearest- neighbor, or by linear interpolation. Interpolation of spatial maps with periodic boundaries is not handled specially; to ensure that the edges of a periodic spatial map join smoothly, simply ensure that the grid values at the edges of the map are identical, since they will be coincident after periodic wrapping. The valueRange and colors parameters travel together; either both are unspecified, or both are specified. They control how map values will be transformed into colors, by SLiMgui and by the spatialMapColor() method. The valueRange parameter establishes the color-mapped range of spatial map values, as a vector of length two specifying a minimum and maximum; this does not need to match the actual range of values in the map. The colors parameter then establishes the corresponding colors for values within the interval defined by valueRange: values less than or equal to valueRange[0] will map to colors[0], values greater than or equal to valueRange[1] will map to the last colors value, and intermediate values will shade continuously through the specified vector of colors, with interpolation between adjacent colors to produce a continuous spectrum. This is much simpler than it sounds in this description; see the recipes in chapter 15 for an illustration of its use. Note that at present, SLiMgui will only display spatial maps of spatiality "x", "y", or "xy"; the colormapping parameters will simply be ignored by SLiMgui for other spatiality values (even if the spatiality is a superset of these values; SLiMgui will not attempt to display an "xyz" spatial map, for example, since it has no way to choose which 2D slice through the xyz space it ought to display). The spatialMapColor() method will return translated color strings for any spatial map, however, even if SLiMgui is unable to display the spatial map. If there are multiple spatial maps with color-mapping parameters defined, SLiMgui will choose just one for display; it will prefer an "xy" map if one is available, but beyond that heuristic its choice will be arbitrary.

An object of type void.

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.