RNETLOGO: an R package for running and exploring individual‐based models implemented in NETLOGO

Summary

1. NetLogo is a free software platform for implementing individual‐based and agent‐based models. However, NetLogo’s support of systematic design, performance and analysis of simulation experiments is limited. The statistics software R includes such support.

2. RNetLogo is an R package that links R and NetLogo: any NetLogo program can be controlled and run from R and model results can be transferred back to R for statistical analyses. RNetLogo includes 16 functions, which are explained and demonstrated in the user manual and tutorial. The design of RNetLogo was inspired by a similar link between Mathematica and NetLogo.

3. RNetLogo is a powerful tool for making individual‐based modelling more efficient and less ad hoc. It links two fast growing user communities and constitutes a new interface for integrating descriptive statistical analyses and individual‐based modelling.

Introduction

Individual‐based models (IBMs) are simulation models that explicitly represent individual organisms and how they interact with each other and their environment (Grimm & Railsback 2005; Thiele, Kurth & Grimm 2011). IBMs are an established and widely used tool in ecology and evolution (DeAngelis & Mooij 2005). A remaining challenge, however, is that analyses of many IBMs are still more or less superficial (Grimm 1999; Grimm & Railsback 2005; Lorscheid, Heine & Meyer 2011). Much more could be learned from IBMs if they would be embedded in a rigorous framework for designing simulation experiments (Oh et al. 2009), storing simulation results in a systematic way and using statistical toolboxes for analysing these results.

RNetLogo is designed for this purpose. It is a package for the free statistics software R (R Development Core Team 2011) which allows running and analysing IBMs that are implemented in NetLogo (Wilensky 1999), a free software platform for implementing individual‐based or agent‐based models. Both R and NetLogo are increasingly used in their fields, slowly but surely turning into standard software platforms which are also the basis for training the next generation of researchers (see, e.g., Bolker 2008; Railsback & Grimm 2011).

Linking NetLogo with R is therefore desirable. One such link already exists: the R extension of NetLogo (Thiele & Grimm 2010). It allows calling any R command from a NetLogo program. It is mainly designed for using R commands to support the implementation of IBMs, or their sub models. For example, if a population model of a territorial animal requires, while the model is running, to calculate home range sizes based on the animals’ movement, existing R packages for calculating home range sizes can be used (e.g., Calenge 2006). Or, if random numbers are needed from probability distributions which are not provided by NetLogo, they can easily be imported from R. There are, however, good reasons for linking R and NetLogo also the other way round, i.e. to call NetLogo programs and commands from R: the R user community is much larger than the NetLogo user community so it makes sense to provide a tool that starts with R; the R extension can, for technical reasons, be cumbersome to install whereas RNetLogo is as easy to load as any other R package; RNetLogo can be used to create self‐documented simulation experiments and reports using Sweave (Leisch 2002), SWord (Baier 2009) or odfWeave (Kuhn 2010); RNetLogo opens a way to integrate NetLogo simulation into spreadsheets using RExel (Heidberger & Neuwirth 2009), ROOo (Drexel 2011) or R4Calc (Gryc 2008).

RNetLogo is not designed for using R within NetLogo programs but for running and exploring simulation experiments of a given NetLogo program. R is already widely used to analyse file output of simulation models, including those implemented in NetLogo. However, a seamless integration of both tools would facilitate the combined use of R and NetLogo. Such a seamless integration was already the reason for linking Mathematica (Wolfram Research 2010) and NetLogo (Bakshy & Wilensky 2007), which was designed to make use of the Mathematica tools for ‘advanced import capabilities, statistical functions, data visualization and document creation. With the NetLogo‐Mathematica link, you can run all of these tools side‐by‐side with NetLogo’ (Bakshy & Wilensky 2007), RNetLogo’s scope is virtually the same: all these tools support systematic and comprehensive analyses of model behaviour.

NetLogo itself includes a flexible tool for performing experiments on models, BehaviorSpace (Shargel & Wilensky 2002), which is routinely used by NetLogo users. However, links to Mathematica or R provide direct access to a wide array of additional ready‐to‐use powerful tools which go beyond BehaviorSpace’s scope.

For an overview of RNetLogo, its main functions are listed in Table 1. Basic usage examples of the different functions are shown in the examples section of the manual pages and are included in the examples/code_samples folder of the package. In the following we briefly describe typical example applications. These and further examples are included in the tutorial and the examples/applications folder of the package.

Table 1. Most important functions of RNetLogo. RNetLogo includes six further functions. For details, see the user manual and tutorial.

RNetLogo function	The function’s scope
NLStart	Initializes the connection to NetLogo, creates an object storing the instance
NLLoadModel	Loads a NetLogo model into an NetLogo instance
NLCommand	Executes the submitted string in NetLogo
NLDoCommand, NLDoCommandWhile	Repeated execution of the submitted string. In the first case with a fixed number of repetitions, in the second case while a condition remains true within NetLogo.
NLReport	Send the result of a NetLogo reporter back to R. Results can be String, Number, Boolean or NetLogo lists which are transformed to appropriate R data types.
NLDoReport, NLDoReportWhile	Repeated execution of a NetLogo command combined with a reporter. The result of the report is sent back to R after every execution of the NetLogo command. In the first case with a fixed number of repetitions, in the second case while a condition remains true within NetLogo.
NLGetAgentSet	An easy‐to‐use way to access variables of an agent or an agentset. An agent is a NetLogo turtle, breed, patch or link. An agentset is a collection of agents. Results can be transformed to R lists or R data.frames.

Examples

Exploring models

Simulation experiments can be defined, run and evaluated using RNetLogo for any existing NetLogo program (Fig. 1). For this, first model and simulation parameters are set and then the central ‘go’ procedure, which contains the schedule of an IBM, is run for a given number of time steps or repetitions. Simulation output can be conveniently stored in R data.frames, lists or matrices and then processed for visualization and statistical analyses. Running simulation experiments via R has the advantage that modellers more easily and directly adopt the perspective of experimentalists, which will facilitate more thorough model analyses than with homespun designs programmed in NetLogo. R contains a large number of powerful packages that can be used for analysing simulation models (see for example the R function and package listings of Groemping (2011) for Design of Experiments, Simpson (2011) for the analysis of ecological and environmental data, Montana (2011) for statistical genetics, Bivand (2011) for the analysis of spatial data, Allignol & Latouche (2011) for the analysis of survival data or Hyndman & Zeileis (2011) for the analysis of time series data).

Figure 1

R Console (on the left) with loaded RNetLogo package and a NetLogo (on the upper right) instance started in interactive mode with Graphical User Interface. The Fire model (Wilensky 1997) was loaded from within R and the model output (percentage of burned forest patches) has been evaluated over different initial forest density values from 1% to 100% (R plot window A). The critical range between 30% and 60% of forest density is then evaluated with repeated simulations to take into account stochasticity in the model, with a step width of 5% and 10 replications (R plot window B) and with a step width of 1% and 20 replications (R plot window C). The full code for this analysis is shown in red in the R Console (29 lines of code).

Linking to analytical models

For many ecological and evolutionary questions, it can be helpful to compare output from simulation models to analytical approximations. By using R packages for solving analytical models, for example Ryacas (Goedman et al. 2010), this can be performed directly via RNetLogo.

Visualization

R comes with all kinds of graphics packages which facilitate visual analyses of model output. In particular, it can be used to overcome the limitation of NetLogo that only one instance of the model world can be displayed. If a model’s grid cells and individuals have several state variables, which usually is the case, it is helpful to visualize them simultaneously in separate panels, plus any summary statistics of interest. If in addition such visualizations for a given time are stored for entire simulations, modellers can ‘slide’ forth and back through the output of a simulation run, thereby developing a better understanding of spatio‐temporal dynamics and how they are related to aggregated output variables. The RNetLogo tutorial includes such an example.

Databases

For complex models, exploratory simulations can create so much output data that it can be difficult to store them in a logical, consistent and easily accessible way. Especially the small, file‐based SQLLite (Hipp 2011) database enables the modeller to save model results together with model metadata (like inputs such as parameter sets) in a single file. R comes with all kinds of database management packages, which can be used by the individual‐based modeller via RNetLogo. This later allows for the use of database query language (SQL) to extract the right data needed for further analyses.

Conclusions

RNetLogo links two ‘worlds’ and related software platforms. R is a free and open source software and has turned into a standard tool, which is clearly indicated by the growing number of R textbooks (Crawley 2007; Bolker 2008; Dalgaard 2008). In RNetLogo, R represents the world of statistics, including design of experiments, visualizations and all kinds of statistical inference. R can also be used for implementing simple simulations (e.g., Petzoldt & Rinke 2007) but does not provide specific support for making model development and simulation efficient. NetLogo was originally developed as a teaching tool, but is increasingly used for research. In RNetLogo, it represents the world of individual‐based and agent‐based modelling, which has considerably matured over the last 10 years but still has not yet established a culture of systematic design and analysis of simulation experiments.

RNetLogo is easy to install and use and thereby opens R and NetLogo users’ access to each others’ world and software platform. This, we hope, will lead to more rigorous model analyses and, thereby, to making better use of individual‐ and agent‐based models for answering theoretical and applied questions in ecology and evolution.

The RNetLogo package is available on CRAN (http://cran.r‐project.org/web/packages/RNetLogo) and R‐Forge (http://rnetlogo.r‐forge.r‐project.org). This package includes the aforementioned user manual and tutorial. See the Data S1 here for installation and quick start usage instructions.

Acknowledgements

The authors would like to thank three anonymous reviewers for their useful comments on an earlier version of the manuscript.