NLGetAgentSet: Reports variable value(s) of one or more agent(s) as a...
In RNetLogo: Provides an Interface to the Agent-Based Modelling Platform 'NetLogo'

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

NLGetAgentSet is an easy way to access variable value(s) of one or more agent(s) (in a sorted way) by specifying the name of the agent or the name of an agentset containing the agents. An agent is a turtle, breed, patch, or link. An agentset is a collection of agents.

1 2	NLGetAgentSet(agent.var, agentset, as.data.frame=TRUE, agents.by.row=FALSE, as.vector=FALSE, nl.obj=NULL)

`agent.var`	A string or vector/list of strings with the variable names of the agent(s).
`agentset`	A string specifying the agent or agentset to be queried.
`as.data.frame`	(optional) If `TRUE` (default) the function will return a data.frame with a column for each `agent.var` and a row for each agent. The column names are taken from the names of the `agent.var` argument. If `FALSE` the function will return a list instead of a data.frame (little bit faster when not using `agents.by.row=TRUE`).
`agents.by.row`	(optional) This argument has an effect only in combination with `as.data.frame=FALSE`, i.e. when a list is returned. If `agents.by.row=FALSE` (default) the returned list contains one list element for each `agent.var`. Each list element contains a vector with the values of the different agents (`agentset`). If `agents.by.row=TRUE` the returned list contains one list element for each agent. Each list element contains a vector with the values of the different requested agent variables (`agent.var`). Attention: `agents.by.row=TRUE` makes the function very slow, especially when many agents are requested.
`as.vector`	(optional) Set this argument to `TRUE` for getting the result as a simple vector in case of requesting only one agent variable. This is the fastest way to access one agent variable. It does not make sense to set this variable to `TRUE` together with `as.data.frame=TRUE`, but `as.vector` is processed first and will win the race if you accidentally set `as.data.frame` 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 variables of an agent, which can be found in NetLogo's Agent Monitors. It isn't possible to get values from different types of agents (i.e. turtles, patches, links) with one call of NLGetAgentSet.

Returns a data.frame (optional a list) with the variable value(s) of an agent/agents of an agentset. One row for each agent and one column for each agent variable. The result is sorted in the same manner as using sort agentset in NetLogo, i.e. turtles are sorted by their who variable and patches from upper left to lower right.

Jan C. Thiele <rnetlogo@gmx.de>

NLReport, NLGetPatches, NLGetGraph

## Not run: 
nl.path <- "C:/Program Files/NetLogo 6.0/app"
NLStart(nl.path)
# NLLoadModel(...)
NLCommand("create-turtles 10")

colors <- NLGetAgentSet(c("who","xcor","ycor","color"), 
                        "turtles with [who < 5]")
str(colors)
                        
# or as a list (slightly faster):
colors.list <- NLGetAgentSet(c("who","xcor","ycor","color"), 
                        "turtles with [who < 5]", as.data.frame=FALSE)
str(colors.list)
            
# or as a list with one list element for each agent
# (very slow!, not recommended especially for large agentsets)
colors.list2 <- NLGetAgentSet(c("who","xcor","ycor","color"), 
                        "turtles with [who < 5]", as.data.frame=FALSE, 
                        agents.by.row=TRUE)
str(colors.list2)
                        
# getting the ends of links is a little bit more tricky, because they store only the
# reference to the turtles and turtles cannot directly be requested. 
# A way to go is:
# create some links
NLCommand("ask turtles [ create-links-with n-of 2 other turtles ]")
link.test <- NLGetAgentSet(c("[who] of end1","[who] of end2"),"links")
str(link.test)

## End(Not run)