NLGetPatches: Reports the values of patch variables as a data.frame...
In RNetLogo: Provides an Interface to the Agent-Based Modelling Platform 'NetLogo'

Description Usage Arguments Details Value Author(s) See Also Examples

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

1
2
3

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

`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`.

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

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.

Jan C. Thiele <rnetlogo@gmx.de>

NLReport, NLGetAgentSet, NLGetGraph

## Not run: 
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)

## End(Not run)