logolink <a href = "https://danielvartan.github.io/logolink/"><img src = "man/figures/logo.svg" align="right" width="120" /></a>

Overview

logolink is an R package that simplifies setting up and running NetLogo simulations from R. It provides a modern, intuitive interface that follows tidyverse principles and integrates seamlessly with the tidyverse ecosystem.

The package is designed to work with NetLogo 7.0.1 and above. Earlier versions are not supported. See NetLogo’s Transition Guide to upgrade your models if needed.

If you find this project useful, please consider giving it a star!

The continuous development of logolink depends on community support. If you can afford to do so, please consider becoming a sponsor.

Another R Package for NetLogo?

While other R packages connect R to NetLogo, logolink is currently the only one that fully supports the latest NetLogo release. It is actively maintained, follows tidyverse conventions, and is designed to be simple and straightforward to use.

For context, RNetLogo supports only older versions (up to 6.0.0, released in December 2016) and has not been updated since June 2017. nlrx offers a powerful framework for managing experiments and results, but supports only up to NetLogo 6.3.0 (released in September 2022), requires additional system dependencies, uses its own internal conventions that diverge from NetLogo standards, and has many unresolved issues.

logolink complements these packages by prioritizing simplicity, offering finer control over output, ensuring full compatibility with NetLogo 7, and integrating seamlessly with 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")

logolink do not install NetLogo itself. You will need to have NetLogo 7.0.1 or higher installed on your computer to use this package. You can download it from the NetLogo website.

Usage

logolink usage is very straightforward. The main functions are:

create_experiment: Create NetLogo BehaviorSpace experiment
run_experiment: Run NetLogo BehaviorSpace experiment

Along with this package, you will also need NetLogo 7.0.1 or higher installed on your computer. You can download it from the NetLogo website.

Setting the Stage

After installing NetLogo and logolink, start by loading the package with:

library(logolink)

logolink will try to find out the path to the NetLogo installation automatically. This is usually successful, but if it fails, you can set it manually. See the documentation for the run_experiment function for more details.

To start our example analysis, we’ll need to first specify the path to the NetLogo model.

This example uses Wilensky’s Wolf Sheep Simple model, a classic predator-prey simulation grounded in the Lotka-Volterra equations developed by Alfred J. Lotka (1925) and Vito Volterra (1926). Since this model comes bundled with NetLogo, no download is required.

We’ll use find_netlogo_home() function to locate the NetLogo installation directory, then build the path to the model file:

model_path <-
  find_netlogo_home() |>
  file.path(
    "models",
    "IABM Textbook",
    "chapter 4",
    "Wolf Sheep Simple 5.nlogox"
  )

Creating an Experiment

To run the model from R, we’ll need to setup an experiment. We can do this by setting a BehaviorSpace experiment with the create_experiment() function. This function will create a BehaviorSpace XML file that contains all the information about the experiment, including the parameters to vary, the metrics to collect, and the number of runs to perform.

setup_file <- create_experiment(
  name = "Wolf Sheep Simple Model Analysis",
  repetitions = 10,
  run_metrics_every_step = TRUE,
  setup = "setup",
  go = "go",
  time_limit = 1000,
  metrics = c(
    'count wolves',
    'count sheep'
  ),
  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
  )
)

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.

Running the Simulation

With the experiment file created, we can now run the model using the run_experiment() function. This function will execute the NetLogo model with the specified parameters and return the results as tidy data frames.

results <-
  model_path |>
  run_experiment(
    setup_file = setup_file
  )
#> ✔ Running model [13.4s]
#> ✔ Gathering metadata [15ms]
#> ✔ Processing table output [8ms]

Checking the Results

logolink supports the four output formats available in BehaviorSpace: Table, Spreadsheet, Lists, and Statistics. By default, only the Table format is returned, along with some metadata about the experiment run.

library(dplyr)

results |> glimpse()
#> List of 2
#>  $ metadata:List of 6
#>   ..$ timestamp       : POSIXct[1:1], format: "2026-02-11 12:46:59"
#>   ..$ netlogo_version : chr "7.0.3"
#>   ..$ output_version  : chr "2.0"
#>   ..$ model_file      : chr "Wolf Sheep Simple 5.nlogox"
#>   ..$

Logolink

Install / Use

README