The nldoc package provides tools to create NetLogo documentations using R. The package searches NetLogo model files for Markdown headers. The documentation can be created in different formats (html, pdf, docx) and styles. There are also utility functions, such as creation of a procedure network.


~~You can install the released version of nlrx from~~ ~~CRAN with:~~ ~~install.packages("nldoc")~~

And the development version from GitHub with:

# install.packages("devtools")


Model documentation

In order to create NetLogo model documentations with nldoc, documentatin tags need to be added to the NetLogo model. These tags are very similar to roxygen documentation tags and are called noxygen tags for the purpose of this package. Noxygen tags are organized in three main groups:

For example, the start of a NetLogo model file with noxygen code could look like this:

;`@model Wolf Sheep Predation (NetLogo models library)
;`@author Uri Wilenski

;`@global Subfiles
;`@details We included a subilfe to the wolf sheep model to demonstrate that nls files are supported by nldoc
;`@code TRUE
__includes["Wolf Sheep Predation Extra.nls"]

;`@global Global variables
;`@details There is only one global variable that stores the max number of sheep allowed
;`@code TRUE
globals [ max-sheep ]  ; dont let sheep population grow too large

;`@global Breeds
;`@details There are two breeds: sheep and wolves
;`@code TRUE
breed [ sheep a-sheep ]  ; sheep is its own plural, so we use "a-sheep" as the singular.
breed [ wolves wolf ]

;`@global Agent properties
;`@details Sheep and wolves have a energy variable. Patches have a countdown variable to store the current state of the grass regrowth countdown.
;`@code TRUE
turtles-own [ energy ]       ; both wolves and sheep have energy
patches-own [ countdown ]

;`@procedure Setup
;`@details The setup procedure first resets the model.
;`@details Depending on the chosen model version, grass patches are initialized.
;`@details Finally, wolves and sheep are created.
;`@code FALSE
to setup

One, or more model files containing noxygen tags, can be used to call the nldoc function of the nldoc package. The procedure creates a markdown file and renders the documentation in the specified output. As an example, we added noxygen tags to the Wolf Sheep model from the NetLogo models library. These modified model files are hosted on github. We use these files to render a documentation in html. nldoc documentation

# List model files (.nls subfiles are also supported)
modelfiles <- c("",

## Create documentation:
# Themes: "journal", "cerulean", "flatly", "readable", "spacelab", "united", "cosmo"
# output_format: "pdf "html" "docx"
nldoc(modelfiles = modelfiles,
      outpath = "C:/out",
      output_format = "html",
      number_sections = TRUE,
      theme = "cosmo",
      date = date(),
      toc = TRUE)

Model procedure network

Another useful function of the nldoc package is the creation of model procedure graphs. This function can be used for any NetLogo model, even if the code does not contain noxygen tags. nldoc procedure network

## Determine the function network with nldoc:
nw <- procedure_nw(modelfiles)

## Determine communities within the network and plot using Igraph package:
com <-
V(nw)$community <- com$membership
rain <- rainbow(14, alpha=.5)
V(nw)$color <- rain[V(nw)$community]

     layout=layout_with_fr(nw, niter = 2000))

## Interactive plot using igraph::tkplot
tkplot(nw, layout=layout_with_fr(nw, niter = 2000))


nldoc/nldoc documentation built on May 13, 2019, 9:52 p.m.