nlrx v0.4.1

0

Monthly downloads

0th

Percentile

Setup, Run and Analyze 'NetLogo' Model Simulations from 'R' via 'XML'

Setup, run and analyze 'NetLogo' (<https://ccl.northwestern.edu/netlogo/>) model simulations in 'R'. 'nlrx' experiments use a similar structure as 'NetLogos' Behavior Space experiments. However, 'nlrx' offers more flexibility and additional tools for running and analyzing complex simulation designs and sensitivity analyses. The user defines all information that is needed in an intuitive framework, using class objects. Experiments are submitted from 'R' to 'NetLogo' via 'XML' files that are dynamically written, based on specifications defined by the user. By nesting model calls in future environments, large simulation design with many runs can be executed in parallel. This also enables simulating 'NetLogo' experiments on remote high performance computing machines. In order to use this package, 'Java' and 'NetLogo' (>= 5.3.1) need to be available on the executing system.

Readme

nlrx

Build
StatusBuild
status Codecov test
coverage lifecycle CRAN
status ropensci DOI:10.1111/2041-210X.13286

The nlrx package provides tools to setup and execute NetLogo simulations from R. NetLogo is a free, open-source and cross-platform modelling environment for simulating natural and social phenomena. NetLogo focusses on implementation of agent-based and spatially explicit simulation models, although system dynamics models are supported as well. NetLogo is developed and maintained at the Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL. More details on NetLogo itself are available online: NetLogo online documentation

NetLogo comes with the built-in experiment tool Behavior Space that allows to setup and execute model simulations with different settings and parameter variations and to collect model output. This experiment tool can be executed via command line in combination with an XML file that contains the experiment specifications, such as runtime, variables, output measurements, stop conditions, and more. One limitation of Behavior Space is, that it only supports full-factorial parameter designs, which may not be appropriate for complex model analyses. Furthermore, Behavior Space experiment specifications are stored within the NetLogo file and are not easily accessible from R. However, in many cases it is useful to store such specifications along with the model output and analyses results in order to enable fully reproducible model analyses.

The nlrx package utilizes the commandline functionality of Behavior Space to execute NetLogo simulations directly from R. Instead of defining experiments within NetLogo Behavior Space, experiments are defined in R using the class objects of the nlrx package. These class objects hold all the information that is needed to run these experiments remotely from R, such as path to NetLogo installation folder, path to the model file and the experiment specifications itself. nlrx provides useful helper functions to generate parameter input matrices from parameter range definitions that cover a wide range of parameter exploration approaches. By storing all relevant information on simulation experiments, including the output of the model simulations in one class object, experiments can be easily stored and shared.

In summary, the nlrx package uses a similar structure as NetLogos Behavior Space but offers more flexibility and additional tools for running reproducible complex model analyses directly from R.

Publication

Further information on the package functionality and detailed code examples can be found in our accompanying publication: Salecker J, Sciaini M, Meyer KM, Wiegand K. The nlrx r package: A next-generation framework for reproducible NetLogo model analyses. Methods Ecol Evol. 2019;2041-210X. https://doi.org/10.1111/2041-210X.13286.

Get citation information for nlrx in R doing citation(package = 'nlrx').

Prerequirements

In order to use the nlrx package, NetLogo (>=5.3.1) needs to be installed on the system that is used to execute model simulations (local/remote). For remote execution, NetLogo needs to be installed on remote machines as well. The nlrx package provides a utility function (download_netlogo()) that can be used to download and unzip (only unix systems) a specified NetLogo version to a local folder. For windows machines, the downloaded file needs to be executed in order to install NetLogo on the local system.

Java

Because NetLogo is executed in a Java virtual machine, Java needs to be installed on the local/remote system as well. We recommend the Oracle Java SE Development Kit 8 or the openjdk. While the nlrx package might work without setting the Java system path explicitly, we recommend to make sure that JAVA_HOME points to the correct Java installation of the system.

Installation

You can install the released version of nlrx from CRAN with:

install.packages("nlrx")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("ropensci/nlrx")

Get started

General information that is needed to run NetLogo simulations remotely, such as path to the NetLogo installation folder is stored within a nl class object. Nested within this nl class are the classes experiment and simdesign. The experiment class stores all experiment specifications. After attaching a valid experiment, a simdesign class object can be attached to the nl class object, by using one of the simdesign helper functions. These helper functions create different parameter input matrices from the experiment variable definitions that can then be executed by the run_nl_one() and run_nl_all() functions. The nested design allows to store everything related to the experiment within one R object. Additionally, different simdesign helper functions can be applied to the same nl object in order to repeat the same experiment with different parameter exploration methods (simdesigns).

Step by step application example

The “Wolf Sheep Predation” model from the NetLogo models library is used to present a basic example on how to setup and run NetLogo model simulations from R.

Step 1: Create a nl object:

The nl object holds all information on the NetLogo version, a path to the NetLogo directory with the defined version, a path to the model file, and the desired memory for the java virtual machine. Depending on the operation system, paths to NetLogo and the model need to be adjusted.

library(nlrx)
# Windows default NetLogo installation path (adjust to your needs!):
netlogopath <- file.path("C:/Program Files/NetLogo 6.0.3")
modelpath <- file.path(netlogopath, "app/models/Sample Models/Biology/Wolf Sheep Predation.nlogo")
outpath <- file.path("C:/out")
# Unix default NetLogo installation path (adjust to your needs!):
netlogopath <- file.path("/home/NetLogo 6.0.3")
modelpath <- file.path(netlogopath, "app/models/Sample Models/Biology/Wolf Sheep Predation.nlogo")
outpath <- file.path("/home/out")

nl <- nl(nlversion = "6.0.3",
         nlpath = netlogopath,
         modelpath = modelpath,
         jvmmem = 1024)

Step 2: Attach an experiment

The experiment object is organized in a similar fashion as NetLogo Behavior Space experiments. It contains all information that is needed to generate a simulation parameter matrix and to execute the NetLogo simulations. Details on the specific slots of the experiment class can be found in the package documentation (?experiment) and the “Advanced configuration” vignette.

nl@experiment <- experiment(expname="wolf-sheep",
                            outpath=outpath,
                            repetition=1,
                            tickmetrics="true",
                            idsetup="setup",
                            idgo="go",
                            runtime=50,
                            evalticks=seq(40,50),
                            metrics=c("count sheep", "count wolves", "count patches with [pcolor = green]"),
                            variables = list('initial-number-sheep' = list(min=50, max=150, qfun="qunif"),
                                             'initial-number-wolves' = list(min=50, max=150, qfun="qunif")),
                            constants = list("model-version" = "\"sheep-wolves-grass\"",
                                             "grass-regrowth-time" = 30,
                                             "sheep-gain-from-food" = 4,
                                             "wolf-gain-from-food" = 20,
                                             "sheep-reproduce" = 4,
                                             "wolf-reproduce" = 5,
                                             "show-energy?" = "false"))

Step 3: Attach a simulation design

While the experiment defines the variables and specifications of the model, the simulation design creates a parameter input table based on these model specifications and the chosen simulation design method. nlrx provides a bunch of different simulation designs, such as full-factorial, latin-hypercube, sobol, morris and eFast (see “Simdesign Examples” vignette for more information on simdesigns). All simdesign helper functions need a properly defined nl object with a valid experiment design. Each simdesign helper also allows to define a number of random seeds that are randomly generated and can be used to execute repeated simulations of the same parameter matrix with different random-seeds (see “Advanced configuration” vignette for more information on random-seed and repetition management). A simulation design is attached to a nl object by using one of the simdesign helper functions:

nl@simdesign <- simdesign_lhs(nl=nl,
                               samples=100,
                               nseeds=3,
                               precision=3)

Step 4: Run simulations

All information that is needed to run the simulations is now stored within the nl object. The run_nl_one() function allows to run one specific simulation from the siminput parameter table. The run_nl_all() function runs a loop over all simseeds and rows of the parameter input table siminput. The loops are constructed in a way that allows easy parallelisation, either locally or on remote HPC machines (see “Advanced configuration” vignette for more information on parallelisation).

results <- run_nl_all(nl)

Step 5: Attach results to nl and run analysis

nlrx provides method specific analysis functions for each simulation design. Depending on the chosen design, the function reports a tibble with aggregated results or sensitivity indices. In order to run the analyze_nl function, the simulation output has to be attached to the nl object first. The simdesign class within the nl object provides a slot for attaching output results (simoutput). An output results tibble can be attached to this slot by using the simdesign setter function setsim(nl, "simoutput"). After attaching the simulation results, these can also be written to the defined outpath of the experiment object.

# Attach results to nl object:
setsim(nl, "simoutput") <- results

# Write output to outpath of experiment within nl
write_simoutput(nl)

# Do further analysis:
analyze_nl(nl)

Meta

  • Please report any issues or bugs.
  • License: GPL3
  • Get citation information for nlrx in R doing citation(package = 'nlrx')
  • We are very open to contributions - if you are interested check Contributing.
    • Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

ropensci\_footer

Functions in nlrx

Name Description
analyze_ff Analyze NetLogo simulation output of simdesign full-factorial
run_nl_all Execute all NetLogo simulations from a nl object
nldoc_network Create NetLogo procedure network
nl_simple Wolf Sheep model sample data: simdesign simple
nldoc_parse_modelcode Parse model code
import_nl Import NetLogo Experiment
eval_variables_constants Evaluate variable validity
run_nl_dyn Execute NetLogo simulation without pregenerated parametersets
nl_distinct Wolf Sheep model sample data: simdesign distinct
analyze_morris Analyze NetLogo simulation output of simdesign morris
getnl Getter function to get a variable of a nl object
nl_sobol Wolf Sheep model sample data: simdesign sobol
export_nl Export NetLogo Experiment
init-classes initClasses
simdesign_GenAlg Add a Genetic Algorithm simdesign to a nl object
nl_spatial Wolf Sheep model sample data: spatial
simdesign_GenSA Add a Simulated Annealing simdesign to a nl object
experiment Construct a new experiment object
getexp Getter function to get a variable of an experiment object
nl_to_graph Generate igraph objects from measured turtles and links metrics
util_generate_seeds Generate a vector of random seeds
util_gather_results Load output file from simulations
nldoc Create NetLogo documentation
util_create_lhs Identify and report the current OS
nl_lhs Wolf Sheep model sample data: simdesign lhs
util_create_sim_XML Create a temporary behavior space xml file to setup NetLogo via command line
nl_to_points Get spatial data from metrics.turtles output
run_nl_one Execute one NetLogo simulation from a nl object
setexp<- Setter function to set a variable of an experiment object
nldoc_table_gui Read NetLogo GUI elements from files
nl_soboljansen Wolf Sheep model sample data: simdesign soboljansen
simdesign_ff Add a full-factorial simdesign to a nl object
getsim Getter function to get a variable of a simdesign object
simdesign_lhs Add a latin-hypercube simdesign to a nl object
nl_sobol2007 Wolf Sheep model sample data: simdesign sobol2007
setnl<- Setter function to set a variable of a nl object
setsim<- Setter function to set a variable of a simdesign object
nldoc_find_procedure_calls Determine procedure calls
simdesign_ABCmcmc_Marjoram_original Add an Approximate Bayesian Computation (Monte-Carlo Markov-Chain) simdesign using the Majoram Original algorithm to a nl object
nl_eFast Wolf Sheep model sample data: simdesign eFast
nldoc_write_nldoc Write NetLogo documentation
nl_morris Wolf Sheep model sample data: simdesign morris
util_run_nl_dyn_ABCmcmc ABCmcmc call simulations function
simdesign_ABCmcmc_Wegmann Add an Approximate Bayesian Computation (Monte-Carlo Markov-Chain) simdesign using the Wegmann algorithm to a nl object
util_run_nl_dyn_GenAlg Genetic Algorithm call simulations function
nl_to_raster Get spatial data from metrics.patches output
util_cleanup Delete temporary files
nl_ff Wolf Sheep model sample data: simdesign ff
util_call_nl Setup and execute NetLogo via command line
unnest_simoutput Get spatial data from metrics.turtles and metrics.patches output
simdesign_soboljansen Add a soboljansen simdesign to a nl object
nldoc_read_nlogo Read NetLogo model code from files
nldoc_table_bs Read NetLogo behavior space experiments from files
print.nl Print content of nl object
report_model_parameters Report globals from a NetLogo model that is defined within a nl object
%>% Pipe operator
nlrx-package nlrx: A package for running NetLogo simulations from R.
simdesign_distinct Add a distinct simdesign to a nl object
util_eval_constants Evaluate if constants list of an experiment object is empty
simdesign_ABCmcmc_Marjoram Add an Approximate Bayesian Computation (Monte-Carlo Markov-Chain) simdesign using the Majoram algorithm to a nl object
simdesign Construct a new simdesign object
util_eval_variables_sa Evaluate variables list of an experiment object for sensitivity analysis simdesigns
simdesign_sobol Add a sobol simdesign to a nl object
util_print.simdesign Print simdesign object content
simdesign_sobol2007 Add a sobol2007 simdesign to a nl object
util_eval_variables_op Evaluate variables list of an experiment object for optimization simdesigns
simdesign_eFast Add an eFast simdesign to a nl object
simdesign_morris Add a morris elementary effects simdesign to a nl object
simdesign_simple Add a simple simdesign to a nl object
util_eval_experiment Evaluate all slots of an experiment object
util_print.nl Print nl object content
util_print.summary Print nl object summary
util_read_write_batch Write a modified batchfile that executes NetLogo
util_run_nl_dyn_GenSA Simulated Annealing call simulations function
util_eval_variables Evaluate if variables list of an experiment object is empty
util_eval_variables_ff Evaluate variables list of an experiment object for full-factorial simdesign
util_run_nl_dyn_GenAlg_fn Genetic Algorithm run simulation function
util_eval_variables_distinct Evaluate variables list of an experiment object for distinct simdesign
util_get_os Identify and report the current OS
util_eval_simdesign Evaluate all slots of a simdesign object
write_simoutput Write attached NetLogo simulation output to file
util_run_nl_dyn_GenSA_fn Simulated Annealing run simulation function
util_print.experiment Print experiment object content
analyze_lhs Analyze NetLogo simulation output of simdesign latin-hypercube
download_netlogo Download NetLogo
analyze_sobol2007 Analyze NetLogo simulation output of simdesign sobol2007
nl Construct a new nl object
analyze_sobol Analyze NetLogo simulation output of simdesign sobol
analyze_soboljansen Analyze NetLogo simulation output of simdesign soboljansen
analyze_nl Analyze NetLogo simulation output
analyze_simple Analyze NetLogo simulation output of simdesign simple
analyze_eFast Analyze NetLogo simulation output of simdesign eFast
No Results!

Vignettes of nlrx

Name
abc.Rmd
calibration.R
calibration.html
furthernotes.Rmd
getstarted.Rmd
optimization.Rmd
sensitivity.Rmd
simdesign-examples.Rmd
No Results!

Last month downloads

Details

Type Package
License GPL-3
Encoding UTF-8
LazyData true
RoxygenNote 6.1.1
URL https://docs.ropensci.org/nlrx, https://github.com/ropensci/nlrx/
BugReports https://github.com/ropensci/nlrx/issues/
VignetteBuilder knitr
SystemRequirements NetLogo (>= 5.3.1), Java (JDK 1.8), pandoc, OpenSSL, udunits-2, PROJ.4, GEOS, GDAL, libxml2
NeedsCompilation no
Packaged 2020-02-07 09:20:38 UTC; jan
Repository CRAN
Date/Publication 2020-02-07 09:40:02 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/nlrx)](http://www.rdocumentation.org/packages/nlrx)