Sequences

This module offers various data structures to create and manage groups of both agents and environments. Which structure best to use depends on the specific requirements of each model.

• AgentList is a list of agentpy objects with methods to select and manipulate its entries.

• AgentDList is an ordered collection of agentpy objects, optimized for removing and looking up objects.

• AgentSet is an unordered collection of agents that can access agent attributes.

• AgentIter and AgentDListIter are a list-like iterators over a selection of agentpy objects.

• AttrIter is a list-like iterator over the attributes of each agent in a selection of agentpy objects.

All of these sequence classes can access and manipulate the methods and variables of their objects as an attribute of the container. For examples, see AgentList.

Containers

class AgentList(model, objs=(), cls=None, *args, **kwargs)

List of agentpy objects. Attribute calls and assignments are applied to all agents and return an AttrIter with the attributes of each agent. This also works for method calls, which returns a list of return values. Arithmetic operators can further be used to manipulate agent attributes, and boolean operators can be used to filter the list based on agents’ attributes. Standard list methods can also be used.

Parameters

• model (Model) – The model instance.

• objs (int or Sequence, optional) – An integer number of new objects to be created, or a sequence of existing objects (default empty).

• cls (type, optional) – Class for the creation of new objects.

• **kwargs – Keyword arguments are forwarded to the constructor of the new objects. Keyword arguments with sequences of type AttrIter will be broadcasted, meaning that the first value will be assigned to the first object, the second to the second, and so forth. Otherwise, the same value will be assigned to all objects.

Examples

Prepare an AgentList with three agents:

>>> model = ap.Model()
>>> agents = model.add_agents(3)
>>> agents
AgentList [3 agents]

The assignment operator can be used to set a variable for each agent. When the variable is called, an AttrList is returned:

>>> agents.x = 1
>>> agents.x
AttrList of 'x': [1, 1, 1]

One can also set different variables for each agent by passing another AttrList:

>>> agents.y = ap.AttrIter([1, 2, 3])
>>> agents.y
AttrList of 'y': [1, 2, 3]

Arithmetic operators can be used in a similar way. If an AttrList is passed, different values are used for each agent. Otherwise, the same value is used for all agents:

>>> agents.x = agents.x + agents.y
>>> agents.x
AttrList of 'x': [2, 3, 4]

>>> agents.x *= 2
>>> agents.x
AttrList of 'x': [4, 6, 8]

Attributes of specific agents can be changed through setting items:

>>> agents.x[2] = 10
>>> agents.x
AttrList of 'x': [4, 6, 10]

Boolean operators can be used to select a subset of agents:

>>> subset = agents(agents.x > 5)
>>> subset
AgentList [2 agents]

>>> subset.x
AttrList of attribute 'x': [6, 8]

random(n=1, replace=False)

Creates a random sample of agents.

Parameters

• n (int, optional) – Number of agents (default 1).

• replace (bool, optional) – Select with replacement (default False). If True, the same agent can be selected more than once.

Returns

The selected agents.

Return type

AgentIter

select(selection)

Returns a new AgentList based on selection.

Parameters

selection (list of bool) – List with same length as the agent list. Positions that return True will be selected.

shuffle()

Shuffles the list in-place, and returns self.

sort(var_key, reverse=False)

Sorts the list in-place, and returns self.

Parameters

• var_key (str) – Attribute of the lists’ objects, based on which the list will be sorted from lowest value to highest.

• reverse (bool, optional) – Reverse sorting (default False).

class AgentDList(model, objs=(), cls=None, *args, **kwargs)

Ordered collection of agentpy objects. This container behaves similar to AgentList in most aspects, but comes with additional features for object removal and lookup.

The key differences to AgentList are the following:

• Faster removal of objects.

• Faster lookup if object is part of group.

• No duplicates are allowed.

• The order of agents in the group cannot be changed.

• Removal of agents changes the order of the group.

• AgentDList.buffer() makes it possible to remove objects from the group while iterating over the group.

• AgentDList.shuffle() returns an iterator instead of shuffling in-place.

Parameters

• model (Model) – The model instance.

• objs (int or Sequence, optional) – An integer number of new objects to be created, or a sequence of existing objects (default empty).

• cls (type, optional) – Class for the creation of new objects.

• **kwargs – Keyword arguments are forwarded to the constructor of the new objects. Keyword arguments with sequences of type AttrIter will be broadcasted, meaning that the first value will be assigned to the first object, the second to the second, and so forth. Otherwise, the same value will be assigned to all objects.

buffer()

Return AgentIter over the content of the group that supports deletion of objects from the group during iteration.

random(n=1, replace=False)

Creates a random sample of agents.

Parameters

• n (int, optional) – Number of agents (default 1).

• replace (bool, optional) – Select with replacement (default False). If True, the same agent can be selected more than once.

Returns

The selected agents.

Return type

AgentIter

select(selection)

Returns a new AgentList based on selection.

Parameters

selection (list of bool) – List with same length as the agent list. Positions that return True will be selected.

shuffle()

Return AgentIter over the content of the group with the order of objects being shuffled.

sort(var_key, reverse=False)

Returns a new sorted AgentList.

Parameters

• var_key (str) – Attribute of the lists’ objects, based on which the list will be sorted from lowest value to highest.

• reverse (bool, optional) – Reverse sorting (default False).

class AgentSet(model, objs=(), cls=None, *args, **kwargs)

Unordered collection of agentpy objects.

Parameters

• model (Model) – The model instance.

• objs (int or Sequence, optional) – An integer number of new objects to be created, or a sequence of existing objects (default empty).

• cls (type, optional) – Class for the creation of new objects.

• **kwargs – Keyword arguments are forwarded to the constructor of the new objects. Keyword arguments with sequences of type AttrIter will be broadcasted, meaning that the first value will be assigned to the first object, the second to the second, and so forth. Otherwise, the same value will be assigned to all objects.

Iterators

class AgentIter(model, source=())

Iterator over agentpy objects.

to_dlist()

Returns an AgentDList of the iterator.

to_list()

Returns an AgentList of the iterator.

class AgentDListIter(model, source=(), shuffle=False, buffer=False)

Iterator over agentpy objects in an AgentDList.

class AttrIter(source, attr=None)

Iterator over an attribute of objects in a sequence. Length, items access, and representation work like with a normal list. Calls are forwarded to each entry and return a list of return values. Boolean operators are applied to each entry and return a list of bools. Arithmetic operators are applied to each entry and return a new list. If applied to another AttrList, the first entry of the first list will be matched with the first entry of the second list, and so on. Else, the same value will be applied to each entry of the list. See AgentList for examples.