Overview
logolink
is an R package that makes it easy to set up and run NetLogo simulations directly from R. It is built for NetLogo 7 and does not support older versions.
The package takes a modern, streamlined approach to running NetLogo models. It follows the tidyverse principles and integrates naturally with the tidyverse ecosystem.
If you find this project useful, please consider giving it a star!
Another R Package for NetLogo?
While other R packages connect R and NetLogo, logolink
is currently the only one that fully supports the latest NetLogo release (NetLogo 7). It is actively maintained, follows tidyverse conventions, and is designed to be simple and straightforward to use.
For context, RNetLogo
works only with older versions (up to version 6.0.0, released in December 2016) and has not been updated since June 2017. nlrx
provides a powerful framework for managing experiments and results, but supports only up to NetLogo 6.3.0 (released in September 2022) and has many unresolved issues. logolink
complements these packages by focusing on simplicity, full compatibility with NetLogo 7, and seamless integration into modern R workflows.
Installation
You can install the released version of logolink
from CRAN with:
install.packages("logolink")
And the development version from GitHub with:
# install.packages("remotes")
remotes::install_github("danielvartan/logolink")
Usage
logolink
usage is very straightforward. The main functions are:
-
create_experiment
: Create a NetLogo BehaviorSpace experiment XML file. -
run_experiment
: Run a NetLogo BehaviorSpace experiment.
Along with this package, you will also need NetLogo 7 or higher installed on your computer. You can download it from the NetLogo website.
Setting the NetLogo Path
logolink
requires the path to the NetLogo executable when running simulations with the run_experiment
function. This path is OS-independent, but easy to locate. On Windows, for example, it is typically something like C:\Program Files\NetLogo 7.0.0\NetLogo.exe
.
Example (Linux):
netlogo_path <- file.path("", "opt", "netlogo-7-0-0", "bin", "NetLogo")
netlogo_path
#> [1] "/opt/netlogo-7-0-0/bin/NetLogo"
Creating an Experiment
To start running your model from R you first need to setup an experiment. You can do this by setting a BehaviorSpace experiment with the create_experiment
function. This function will create a XML file that contains all the information about your experiment, including the parameters to vary, the metrics to collect, and the number of runs to perform.
Alternatively, you can set up your experiment directly in NetLogo and save it as part of your model. In this case, you can skip the create_experiment
step and just provide the name of the experiment when running the model with run_experiment
.
Example:
library(logolink)
setup_file <- create_experiment(
name = "Wolf Sheep Simple Model Analysis",
repetitions = 10,
sequential_run_order = TRUE,
run_metrics_every_step = TRUE,
setup = "setup",
go = "go",
time_limit = 1000,
metrics = c(
'count wolves',
'count sheep'
),
run_metrics_condition = NULL,
constants = list(
"number-of-sheep" = 500,
"number-of-wolves" = list(
first = 5,
step = 1,
last = 15
),
"movement-cost" = 0.5,
"grass-regrowth-rate" = 0.3,
"energy-gain-from-grass" = 2,
"energy-gain-from-sheep" = 5
)
)
setup_file |> inspect_experiment_file()
#> <experiments>
#> <experiment name="Wolf Sheep Simple Model Analysis" repetitions="10" sequentialRunOrder="true" runMetricsEveryStep="true">
#> <setup>setup</setup>
#> <go>go</go>
#> <timeLimit steps="1000"></timeLimit>
#> <metric>count wolves</metric>
#> <metric>count sheep</metric>
#> <enumeratedValueSet variable="number-of-sheep">
#> <value value="500"></value>
#> </enumeratedValueSet>
#> <steppedValueSet variable="number-of-wolves" first="5" step="1" last="15"></steppedValueSet>
#> <enumeratedValueSet variable="movement-cost">
#> <value value="0.5"></value>
#> </enumeratedValueSet>
#> <enumeratedValueSet variable="grass-regrowth-rate">
#> <value value="0.3"></value>
#> </enumeratedValueSet>
#> <enumeratedValueSet variable="energy-gain-from-grass">
#> <value value="2"></value>
#> </enumeratedValueSet>
#> <enumeratedValueSet variable="energy-gain-from-sheep">
#> <value value="5"></value>
#> </enumeratedValueSet>
#> </experiment>
#> </experiments>
Running an Experiment
With the experiment file created, you can now run your model using the run_experiment
function. This function will execute the NetLogo model with the specified parameters and return the results as a tidy data frame.
model_path <- file.path(
"", "opt", "netlogo-7-0-0", "models", "IABM Textbook", "chapter 4",
"Wolf Sheep Simple 5.nlogox"
)
results <- run_experiment(
netlogo_path = netlogo_path,
model_path = model_path,
setup_file = setup_file
)
library(dplyr)
results |> glimpse()
#> Rows: 110,110
#> Columns: 10
#> $ run_number <dbl> 9, 4, 1, 2, 8, 6, 7, 5, 3, 4, 3, 7, 1, 8, 9,…
#> $ number_of_sheep <dbl> 500, 500, 500, 500, 500, 500, 500, 500, 500,…
#> $ number_of_wolves <dbl> 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5,…
#> $ movement_cost <dbl> 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5,…
#> $ grass_regrowth_rate <dbl> 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3,…
#> $ energy_gain_from_grass <dbl> 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2,…
#> $ energy_gain_from_sheep <dbl> 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5,…
#> $ step <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1,…
#> $ count_wolves <dbl> 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5,…
#> $ count_sheep <dbl> 500, 500, 500, 500, 500, 500, 500, 500, 500,…
Analyzing the Data (Bonus Section)
Below is a simple example of how to visualize the results using ggplot2
.
library(dplyr)
data <-
results |>
group_by(step, number_of_wolves) |>
summarise(
across(everything(), ~ mean(.x, na.rm = TRUE))
) |>
arrange(number_of_wolves, step)
library(ggplot2)
data |>
mutate(number_of_wolves = as.factor(number_of_wolves)) |>
ggplot(
aes(
x = step,
y = count_sheep,
group = number_of_wolves,
color = number_of_wolves
)
) +
labs(
x = "Time step",
y = "Average number of sheep",
color = "Wolves"
) +
geom_line()
Please refer to the BehaviorSpace Guide for complete guidance on how to set and run experiments in NetLogo. To gain a better understand of the mechanics behind R and NetLogo communication, see the Running from the Command Line section.
Click here to see logolink
full list of functions.
Citation
If you use this package in your research, please cite it to acknowledge the effort put into its development and maintenance. Your citation helps support its continued improvement.
citation("logolink")
#> To cite logolink in publications use:
#>
#> Vartanian, D. (2025). logolink: Run NetLogo from R [Computer
#> software]. https://github.com/danielvartan/logolink
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Misc{,
#> title = {logolink: Run NetLogo from R},
#> author = {Daniel Vartanian},
#> year = {2025},
#> url = {https://github.com/danielvartan/logolink},
#> note = {R package},
#> }
License
Copyright (C) 2025 Daniel Vartanian
logolink is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <https://www.gnu.org/licenses/>.
Contributing
Contributions are welcome! Whether you want to report bugs, suggest features, or improve the code or documentation, your input is highly valued. Please check the issues tab for existing issues or to open a new one.
You can also support the development of logolink
by becoming a sponsor. Click here to make a donation. Please mention logolink
in your donation message.
Acknowledgments
logolink
brand identity is based on the NetLogo brand identity.