Correspondence site: http://www.respond2articles.com/MEE/

APPLICATION

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

Article first published online: 18 JAN 2012

DOI: 10.1111/j.2041-210X.2011.00180.x

© 2012 The Authors. Methods in Ecology and Evolution © 2012 British Ecological Society

Additional Information

#### How to Cite

Thiele, J. C., Kurth, W. and Grimm, V. (2012), RNETLOGO: an R package for running and exploring individual-based models implemented in NETLOGO. Methods in Ecology and Evolution, 3: 480–483. doi: 10.1111/j.2041-210X.2011.00180.x

#### Publication History

- Issue published online: 7 JUN 2012
- Article first published online: 18 JAN 2012
- Received 23 August 2011; accepted 21 November 2011 Handling Editor: Robert Freckleton

### Keywords:

- agent-based modelling;
- design of experiments;
- Gnu R;
- individual-based modelling;
- model analysis;
- Modelling software;
- NetLogo;
- simulation

### 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.

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).

#### 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.

### References

- 2011) CRAN Task View: Survival Analysis, Version: 2011-08-04. URL http://cran.r-project.org/web/views/Survival.html [accessed 24 October 2011]. & (
- 2009) SWordInstaller: SWord: Use R in Microsoft Word (Installer). URL http://CRAN.R-project.org/package=SWordInstaller [accessed 18 August 2011]. (
- 2007) NetLogo-Mathematica Link. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL. URL http://ccl.northwestern.edu/netlogo/mathematica.html [accessed 24 October 2011]. & (
- 2011) CRAN Task View: Analysis of Spatial Data, Version: 2011-09-21. URL http://cran.r-project.org/web/views/Spatial.html [accessed 24 October 2011]. (
- 2008) Ecological Models and Data in R. Princeton University Press, Princeton N.J. (
- 2006) The package “adehabitat” for the R software: a tool for the analysis of space and habitat use by animals. Ecological Modelling, 197, 516–519. (
- 2007) The R Book. Wiley, Chichester. (
- 2008) Introductory Statistics with R, 2nd edn. Springer, New York. (
- 2005) Individual-based modeling of ecological and evolutionary processes. Annual Reviews of Ecological and Evolutionary Systematics, 36, 147–168. & (
- 2011) ROOo v 0.751. URL http://rcom.univie.ac.at/download.html [accessed 18 August 2011]. (
- 2010) Ryacas: R Interface to the Yacas Computer Algebra System, R package version 0.2-10. URL http://CRAN.R-project.org/package=Ryacas [accessed 18 August 2011]. , , & (
- 1999) Ten years of individual-based modelling in ecology: what have we learned, and what could we learn in the future? Ecological Modelling, 115, 129–148. (
- 2005) Individual-based Modeling and Ecology. Princeton University Press, Princeton, N.J. & (
- 2011) CRAN Task View: Design of Experiments (DoE) & Analysis of Experimental Data, Version: 2011-08-10. URL http://cran.r-project.org/web/views/ExperimentalDesign.html [accessed 24 October]. (
- 2008) R and Calc v 0.1.12. URL http://wiki.services.openoffice.org/wiki/R_and_Calc [accessed 18 August 2011]. (
- 2009) R Through Excel: A Spreadsheet interface for Statistics, Data Analysis, and Graphics. Springer, New York. & (
- 2011) About SQLite. URL http://www.sqlite.org/about.html [accessed 18 August 2011]. (
- 2011) CRAN Task View: Time Series Analysis, Version: 2011-09-19. URL http://cran.r-project.org/web/views/TimeSeries.html [accessed 24 October 2011]. & (
- 2010) odfWeave: Sweave Processing of Open Document Format (ODF) files, R package version 0.7.17. URL http://CRAN.R-project.org/package=odfWeave [accessed 18 August 2011]. , with Contributions from Weston, S., Coulter, N., Lenon, P. & Otles, Z. (
- 2002) Sweave: dynamic generation of statistical reports using literate data analysis. Compstat 2002 – Proceedings in Computational Statistics (eds W. Härdle & B. Rönz), pp. 575–580. Physica Verlag, Heidelberg, ISBN 3-7908-1517-9. (
- 2011) Opening the ‘Black Box’ of Simulations: Transparency of Simulation Models and Effective Results Reports Through the Systematic Design of Experiments. Hamburg University of Technology (TUHH), Research Paper No. 001. URL http://ssrn.com/abstract=1860904 [accessed 24 October 2011]. , & (
- 2011) CRAN Task View: Statistical Genetics, Version: 2011-05-11. URL http://cran.r-project.org/web/views/Genetics.html [accessed 24 October 2011]. (
- 2009) Efficient experimental design tools for exploring large simulation models. Computational and Mathematical Organization Theory, 15, 237–257. , , , & (
- 2007) Simecol: an object-oriented framework for ecological modeling in R. Journal of Statistical Software, 22, 1–31. URL http://www.jstatsoft.org/v22/i09 [accessed 18 August 2011]. & (
- R Development Core Team (2011) R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna. URL http://www.r-project.org/ [accessed 18 August 2011].
- 2012) Agent-based and Individual-based Models: A Practical Introduction. Princeton University Press, Princeton N.J. & (
- 2002) BehaviorSpace. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL. URL http://ccl.northwestern.edu/netlogo/docs/behaviorspace.html [accessed 24 October 2011]. & (
- 2011) CRAN Task View: Analysis of Ecological and Environmental Data, Version: 2011-08-27. URL http://cran.r-project.org/web/views/Environmetrics.html [accessed 24 October 2011]. (
- 2010) NetLogo meets R: linking agent-based models with a toolbox for their analysis. Environmental Modelling and Software, 25, 972–974. & (
- 2011) Agent- and individual-based Modelling with NetLogo: introduction and New NetLogo Extensions. Die Grüne Reihe 22. Tagung der Sektion Forstliche Biometrie und Informatik des Deutschen Verbandes Forstlicher Forschungsanstalten und der Arbeitsgemeinschaft Ökologie und Umwelt der Internationalen Biometrischen Gesellschaft – Deutsche Region, 20–21th September 2010 in Göttingen (Germany) (eds K. Römisch, A. Nothdurft & U. Wunn), pp. 68–101, ISSN 1860-4064. , & (
- 1997) NetLogo Fire model. Center for Connected Learning and Computer-Based Modeling. Northwestern University, Evanston, IL. URL http://ccl.northwestern.edu/netlogo/models/Fire [accessed 18 August 2011]. (
- 1999) NetLogo. Center for Connected Learning and Computer-Based Modeling. Northwestern University, Evanston, IL. URL http://ccl.northwestern.edu/netlogo [accessed 18 August 2011]. (
- Wolfram Research, Inc. (2010) Mathematica, Version 8.0. URL http://www.wolfram.com/mathematica/ [accessed 24 October 2011].

### Supporting Information

**Data S1.** Supplemental document.

As a service to our authors and readers, this journal provides supporting information supplied by the authors. Such materials may be re-organized for online delivery, but are not copy-edited or typeset. Technical support issues arising from supporting information (other than missing files) should be addressed to the authors.

Filename | Format | Size | Description |
---|---|---|---|

MEE3_180_sm_DataS1.pdf | 71K | Supporting info item |

Please note: Wiley Blackwell is not responsible for the content or functionality of any supporting information supplied by the authors. Any queries (other than missing content) should be directed to the corresponding author for the article.