NLGetPatches: Reports the values of patch variables as a data.frame (optional as a list, matrix or simple vector)

Description

NLGetPatches is an easy way to access variables of all patches (default) or of a subset of patches.

Usage

NLGetPatches(patch.var, patchset="patches", as.matrix=FALSE, 
             as.data.frame=TRUE, patches.by.row=FALSE,
             as.vector=FALSE, nl.obj=NULL)

Arguments

patch.var

A string or vector/list of strings with the names of patch variables to report.

patchset

(optional) A string defining which patches to request. By default, values of all patches are returned.

as.matrix

(optional) If this variable is TRUE (default is FALSE), the function will return the result as a matrix representing the NetLogo world. (This option is Only available, if the argument patchset is not used, i.e. if

as.data.frame

(optional) If TRUE (default) the function returns a data.frame with one column for each patch.var and one row for each patch. The column names are taken from the names of the patch.var argument. If FALS

patches.by.row

(optional) This argument has an effect only in combination with as.data.frame=FALSE, i.e. when a list is returned. If patches.by.row=FALSE (default) the returned list contains one list element for each patch.var

as.vector

(optional) Set this argument to TRUE for getting the result as a simple vector in case of requesting only one patch variable. This is the fastest way to access one patch variable. It does not make sense to set this variable to TRUE

nl.obj

(optional) A reference to a NetLogo instance created with NLStart.

Value

Returns a data.frame (optional a list) with the variable value(s) of a patch/patches of a patchset. One row for each patch and one column for each patch variable. The result is sorted (like using sort patchset in NetLogo, e.g. patches are sorted from upper left to lower right. To get the same result as with default settings until RNetLogo version 0.9.2 use: as.data.frame=FALSE and patches.by.row=TRUE.

Details

It's possible to use all the variables of a patch, which can be found in NetLogo's Agent Monitors. See the vignette performanceNotes.pdf for performance details and notes on changes since version 0.9.3.

Examples

Run this code

nl.path <- "C:/Program Files/NetLogo 5.0.3"
NLStart(nl.path)
# NLLoadModel(...)

allpatches <- NLGetPatches(c("pxcor","pycor","pcolor"))
str(allpatches)

# only a subset of patches
subsetpatches <- NLGetPatches(c("pxcor","pycor","pcolor"), 
                              "patches with [pxcor < 5]")
str(subsetpatches)

# or as a list (slightly faster):
colors.list <- NLGetPatches(c("pxcor","pycor","pcolor"), 
                        "patches with [pxcor < 5]", as.data.frame=FALSE)
str(colors.list)

# or as a list with one list element for each patch
# (very slow!, not recommended especially for large patchsets)
colors.list2 <- NLGetPatches(c("pxcor","pycor","pcolor"), 
                        "patches with [pxcor < 5]", as.data.frame=FALSE, 
                        patches.by.row=TRUE)
str(colors.list2)

Run the code above in your browser using DataLab

Last chance! 50% off unlimited learning