nl_experiment R Documentation

Create NetLogo experiment object

Description

Use this function to create NetLogo experiment object.

Usage

nl_experiment(model_file, iterations = NULL, while_condition = NULL,
  repetitions = 1, random_seed = NULL, step_measures = NULL,
  run_measures = NULL, mapping = NULL, param_values = NULL,
  agents_after = NULL, agents_step = NULL, patches_after = NULL,
  export_view = FALSE, export_world = FALSE, setup_commands = "setup",
  go_command = "go", eval_criteria = NULL, eval_aggregate_fun = NULL,
  eval_mutate = NULL, data_handler = NULL)

Arguments

model_file

An absolute path to your NetLogo model file (.nlogo)
iterations

Number of iterations to run. Alternatively define while_condition to stop simulation.
while_condition

A string with a NetLogo conditional reporter. (for example: "ticks < 100")
repetitions

How many times to run the model with the same parameters. It is set to 1 by default. Result data sets will include run_id as additional variable to identify the specific runs. To change repetitions of existing experiment object use nl_set_run_options
random_seed

If defined, random seed will be set for each run. Note: using random seed and repetitions > 1 does not make sense.
step_measures

Measures per each simulation step in a named character vector. Use measures() function to construct measures in right format. To change step measures of existing experiment object use nl_set_measures
run_measures

Measures per each simulation run in a named character vector. Use measures() function to construct measures in right format. To change run measures of existing experiment object use nl_set_measures
mapping

Mapping between R and NetLogo parameters in named character vector. For example: c(diffusion_rate = "diffusion-rate", population = "population")
param_values

A data.frame with parameter values or a list of values to be expanded to all combinations of values
agents_after

Agents reporters see nl_set_agent_reports
agents_step

Agents reporters see nl_set_agent_reports
patches_after

Patches reporters see nl_set_agent_reports
export_view

If set to TRUE, the views will be exported to a png image files for each run (when running the experiment)
export_world

If set to TRUE, the world will be exported to a csv file for each run
setup_commands

NetLogo command strings to execute to setup the model
go_command

NetLogo command string to execute the step in the model
eval_criteria

A criteria calculation expressions. May use step or run data frames to calculate criteria. Elements from step should be aggregated. Must return named numeric vector.
eval_aggregate_fun

Aggregation function (used to aggregate criteria values when repetitions > 1)
eval_mutate

Add criteria based on aggregated values
data_handler

Function to handle observations. If handler is defined the observations will not be stored in result elements when running the experiment with 'nl_run' function.

Value

NetLogo experiment object

See Also

To run experiment use nl_run. To change existing experiment object see nl_set_measures, nl_set_run_options and nl_set_param_values.

Examples

experiment <- nl_experiment(
  model_file = "models/Sample Models/Earth Science/Fire.nlogo",
  while_condition = "any? turtles",
  repetitions = 20,
  run_measures = measures(
    percent_burned = "(burned-trees / initial-trees) * 100",
    progress = "max [pxcor] of patches with [pcolor > 0 and pcolor < 55]"
  ),
  param_values = list(
    density = seq(from = 55, to = 62, by = 1)
  )
)