RNetLogo (version 1.0-4)

NLGetAgentSet: Reports variable value(s) of one or more agent(s) as a data.frame (optional as a list or vector)

Description

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.

Usage

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

Arguments

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.

Value

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.

Details

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.

See Also

NLReport, NLGetPatches, NLGetGraph

Examples

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)