Get and set simulation parameters

params, P and Par (an active binding, like "mod") access the parameter slot in the simList. params has a replace method, so can be used to update a parameter value.

params(sim)

# S4 method for class 'simList'
params(sim)

params(sim) <- value

# S4 method for class 'simList'
params(sim) <- value

P(sim, param, module)

P(sim, param, module) <- value

parameters(sim, asDF = FALSE)

# S4 method for class 'simList'
parameters(sim, asDF = FALSE)

Arguments

sim

A simList object from which to extract element(s) or in which to replace element(s).

value

The parameter value to be set (in the corresponding module and param).

param

Optional character string indicating which parameter to choose.

module

Optional character string indicating which module params should come from.

asDF

Logical. For parameters, if TRUE, this will produce a single data.frame of all model parameters. If FALSE, then it will return a data.frame with 1 row for each parameter within nested lists, with the same structure as params.

Value

Returns or sets the value of the slot from the simList object.

Details

parameters will extract only the metadata with the metadata defaults, NOT the current values that may be overwritten by a user. See examples.

Note

The differences between P(), params() and being explicit with passing arguments are mostly a question of speed and code compactness. The computationally fastest way to get a parameter is to specify moduleName and parameter name, as in: P(sim, "paramName", "moduleName") (replacing moduleName and paramName with your specific module and parameter names), but it is more verbose than P(sim)$paramName. Note: the important part for speed (e.g., 2-4x faster) is specifying the moduleName. Specifying the parameter name is <5% faster.

See also

SpaDES.core-package, specifically the section 1.2.1 on Simulation parameters.

Other functions to access elements of a 'simList' object: .addDepends(), checkpointFile(), envir(), events(), globals(), inputs(), modules(), objs(), packages(), paths(), progressInterval(), times()

Examples

s <- simInit()
#> Setting:
#>   options(
#>     reproducible.cachePath = '/tmp/RtmpIQ0Aky/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpIQ0Aky/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpIQ0Aky/myProject/outputs'
#>     spades.modulePath = '/tmp/RtmpIQ0Aky/myProject/modules'
#>     spades.scratchPath = '/tmp/RtmpIQ0Aky/SpaDES/scratch'
#>   )
#> Jan27 19:04:04 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Elpsed time for simInit: 0.02879572 secs
# add a parameter to tmp module
params(s)$tmp <- list(a = 1)

# Only work inside a module, inside a function with `sim` is an argument
# P(s, "a") # get "a" parameter inside the current module
# Par$a     # same. Get "a" parameter inside the current module

if (requireNamespace("NLMR", quietly = TRUE) &&
    requireNamespace("SpaDES.tools", quietly = TRUE)) {
  opts <- options("spades.moduleCodeChecks" = FALSE) # not necessary for example
  modules <- list("randomLandscapes")
  paths <- list(modulePath = getSampleModules(tempdir()))
  mySim <- simInit(modules = modules, paths = paths,
                   params = list(.globals = list(stackName = "landscape")))

  # update some parameters using assignment -- currently only params will work
  params(mySim)$randomLandscapes$nx <- 200
  params(mySim)$randomLandscapes$ny <- 200

  parameters(mySim) # Does not contain these user overridden values

  # These next 2 are same here because they are not within a module
  P(mySim)          # Does contain the user overridden values
  params(mySim)     # Does contain the user overridden values

  # NOTE -- deleting a parameter will affect params and P, not parameters
  params(mySim)$randomLandscapes$nx <- NULL
  params(mySim)$randomLandscapes$ny <- NULL

  parameters(mySim) # Shows nx and ny

  # These next 2 are same here because they are not within a module
  P(mySim)          # nx and ny are Gone
  params(mySim)     # nx and ny are Gone

  options(opts) # reset
}
#> Setting:
#>   options(
#>     spades.modulePath = '/tmp/RtmpIQ0Aky/sampleModules'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/RtmpIQ0Aky/SpaDES/scratch/raster'
#>     reproducible.cachePath = '/tmp/RtmpIQ0Aky/myProject/cache'
#>     spades.inputPath = '/tmp/RtmpIQ0Aky/myProject/inputs'
#>     spades.outputPath = '/tmp/RtmpIQ0Aky/myProject/outputs'
#>     spades.modulePath = '/tmp/RtmpIQ0Aky/sampleModules'
#>     spades.scratchPath = '/tmp/RtmpIQ0Aky/SpaDES/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/RtmpIQ0Aky/SpaDES/scratch/terra'
#> Loading required package: RColorBrewer
#> Loading required package: NLMR
#> Some functions in this package require the 'RandomFields' and
#> 'RandomFieldsUtil' packages which are not available on CRAN anymore. To
#> install them, please run 'install.packages('RandomFields', repos =
#> 'https://predictiveecology.r-universe.dev', type = 'source')'.
#> Jan27 19:04:04 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jan27 19:04:04 simInit The following .globals were used:
#> Jan27 19:04:04 simInit Key: <global, module>
#> Jan27 19:04:04 simInit               module    global
#> Jan27 19:04:04 simInit               <char>    <char>
#> Jan27 19:04:04 simInit  1: randomLandscapes stackName
#> Elpsed time for simInit: 0.06385732 secs