RNetLogo (version 1.0-4)

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 you request all patches and only one patch variable, i.e. length of patch.var is 1.)

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 FALSE the function will return a list instead of a data.frame (little bit faster, when not using patches.by.row=TRUE).

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. Each list element contains a vector with the values of the different patches (patchset). If patches.by.row=TRUE the returned list contains one list element for each patch. Each list element contains a vector with the values of the different requested patch variables (patch.var). Attention: patches.by.row=TRUE makes the function very slow, especially when many patches are requested.

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 together with as.data.frame=TRUE or as.matrix=TRUE, but as.vector is processed first and will win the race if you accidentally set as.data.frame or as.matrix to TRUE as well. By default as.vector is FALSE.

nl.obj

(optional) A string identifying 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.

Details

It's possible to use all the variables of a patch, which can be found in NetLogo's Agent Monitors.

See Also

NLReport, NLGetAgentSet, NLGetGraph

Examples

nl.path <- "C:/Program Files/NetLogo 6.0/app"
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)