Agents

class mesa_frames.AgentSetPolars(model: ModelDF)

The AgentSetDF class is a container for agents of the same type.

Parameters:

• model (ModelDF) – The model that the agent set belongs to.

• AgentSetDF. (Polars-based implementation of)

Methods:

__init__	Initialize a new AgentSetPolars.
add	Add agents to the AgentSetPolars.
contains	Check if agents with the specified IDs are in the AgentContainer.
get	Retrieve the value of a specified attribute for each agent in the AgentContainer.
set	Set the value of a specified attribute or attributes for each agent in the mask in AgentContainer.
select	Select agents in the AgentContainer based on the given criteria.
shuffle	Shuffles the order of agents in the AgentContainer.
sort	Sorts the agents in the agent set based on the given criteria.
__getattr__	Fallback for retrieving attributes of the AgentContainer.
__getitem__	Implement the [] operator for the AgentContainer.
__add__	Add agents to a new AgentSetDF through the + operator.
__contains__	Check if an agent is in the AgentContainer.
__copy__	Create a shallow copy of the AgentContainer.
__deepcopy__	Create a deep copy of the AgentContainer.
__iadd__	Add agents to the AgentSetDF through the += operator.
__isub__	Remove agents from the AgentContainer through the -= operator.
__iter__	Iterate over the agents in the AgentContainer.
__repr__	Get a string representation of the DataFrame in the AgentContainer.
__setitem__	Implement the [] operator for setting values in the AgentContainer.
__str__	Get a string representation of the agents in the AgentContainer.
__sub__	Remove agents from a new AgentContainer through the - operator.
copy	Create a copy of the Class.
discard	Remove an agent from the AgentSetDF.
do	Invoke a method on the AgentContainer.
remove	Remove the agents from the AgentContainer.
step	Run a single step of the AgentSetDF.
__len__	Get the number of agents in the AgentContainer.
__reversed__	Iterate over the agents in the AgentContainer in reverse order.

Attributes:

model	The model that the AgentContainer belongs to.
random	The random number generator of the model.
space	The space of the model.
agents	The agents in the AgentContainer.
active_agents	The active agents in the AgentContainer.
inactive_agents	The inactive agents in the AgentContainer.
index	The ids in the AgentContainer.
pos	The position of the agents in the AgentContainer.

__init__(model: ModelDF) → None

Initialize a new AgentSetPolars.

Parameters:

model (ModelDF) – The model that the agent set belongs to.

add(agents: DataFrame | Sequence[Any] | dict[str, Any], inplace: bool = True) → Self

Add agents to the AgentSetPolars.

Parameters:

• agents (pl.DataFrame | Sequence[Any] | dict[str, Any]) – The agents to add.

• inplace (bool, optional) – Whether to add the agents in place, by default True.

Returns:

The updated AgentSetPolars.

Return type:

Self

contains(agents: int | Collection[int] | Series) → bool | Series

Check if agents with the specified IDs are in the AgentContainer.

Parameters:

agents (IdsLike) – The ID(s) to check for.

Returns:

True if the agent is in the AgentContainer, False otherwise.

Return type:

bool | BoolSeries

get(attr_names: int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | Series | None | Iterable[int | float | Decimal | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | Series | None], mask: Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame = None) → Series | DataFrame

Retrieve the value of a specified attribute for each agent in the AgentContainer.

Parameters:

• attr_names (str | Collection[str] | None, optional) – The attributes to retrieve. If None, all attributes are retrieved. Defaults to None.

• mask (AgentMask | None, optional) – The AgentMask of agents to retrieve the attribute for. If None, attributes of all agents are returned. Defaults to None.

Returns:

The attribute values.

Return type:

Series | dict[str, Series] | DataFrame | dict[str, DataFrame]

set(attr_names: str | Collection[str] | dict[str, Any] | None = None, values: Any | None = None, mask: Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame = None, inplace: bool = True) → Self

Set the value of a specified attribute or attributes for each agent in the mask in AgentContainer.

Parameters:

• attr_names (DataFrameInput | str | Collection[str]) – The key can be: - A string: sets the specified column of the agents in the AgentContainer. - A collection of strings: sets the specified columns of the agents in the AgentContainer. - A dictionary: keys should be attributes and values should be the values to set. Value should be None.

• values (Any | None) – The value to set the attribute to. If None, attr_names must be a dictionary.

• mask (AgentMask | None) – The AgentMask of agents to set the attribute for.

• inplace (bool) – Whether to set the attribute in place.

Returns:

The updated agent set.

Return type:

Self

select(mask: Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame = None, filter_func: Callable[[Self], Series] | None = None, n: int | None = None, negate: bool = False, inplace: bool = True) → Self

Select agents in the AgentContainer based on the given criteria.

Parameters:

• mask (AgentMask | None, optional) – The AgentMask of agents to be selected, by default None

• filter_func (Callable[[Self], AgentMask] | None, optional) – A function which takes as input the AgentContainer and returns a AgentMask, by default None

• n (int | None, optional) – The maximum number of agents to be selected, by default None

• negate (bool, optional) – If the selection should be negated, by default False

• inplace (bool, optional) – If the operation should be performed on the same object, by default True

Returns:

A new or updated AgentContainer.

Return type:

Self

shuffle(inplace: bool = True) → Self

Shuffles the order of agents in the AgentContainer.

Parameters:

inplace (bool) – Whether to shuffle the agents in place.

Returns:

A new or updated AgentContainer.

Return type:

Self

sort(by: str | Sequence[str], ascending: bool | Sequence[bool] = True, inplace: bool = True, **kwargs) → Self

Sorts the agents in the agent set based on the given criteria.

Parameters:

• by (str | Sequence[str]) – The attribute(s) to sort by.

• ascending (bool | Sequence[bool]) – Whether to sort in ascending order.

• inplace (bool) – Whether to sort the agents in place.

• **kwargs – Keyword arguments to pass to the sort

Returns:

A new or updated AgentContainer.

Return type:

Self

__getattr__(key: str) → Series

Fallback for retrieving attributes of the AgentContainer. Retrieve an attribute of the underlying DataFrame(s).

Parameters:

name (str) – The name of the attribute to retrieve.

Returns:

The attribute value

Return type:

Any | dict[str, Any]

__getitem__(key: str | Collection[str] | Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame, str] | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame, Collection[str]]) → Series | DataFrame

Implement the [] operator for the AgentContainer.

The key can be: - An attribute or collection of attributes (eg. AgentContainer[“str”], AgentContainer[[“str1”, “str2”]]): returns the specified column(s) of the agents in the AgentContainer. - An AgentMask (eg. AgentContainer[AgentMask]): returns the agents in the AgentContainer that satisfy the AgentMask. - A tuple (eg. AgentContainer[AgentMask, “str”]): returns the specified column of the agents in the AgentContainer that satisfy the AgentMask.

Parameters:

key (str| Collection[str] | AgentMask | tuple[AgentMask, str] | tuple[AgentMask, Collection[str]]) – The key to retrieve.

Returns:

The attribute values.

Return type:

Series | DataFrame | dict[str, Series] | dict[str, DataFrame]

__add__(other: DataFrame | Sequence[Any] | dict[str, Any]) → Self

Add agents to a new AgentSetDF through the + operator.

Other can be: - A DataFrame: adds the agents from the DataFrame. - A Sequence[Any]: should be one single agent to add. - A dictionary: keys should be attributes and values should be the values to add.

Parameters:

other (DataFrame | Sequence[Any] | dict[str, Any]) – The agents to add.

Returns:

A new AgentContainer with the added agents.

Return type:

Self

__contains__(agents: int | AgentSetDF) → bool

Check if an agent is in the AgentContainer.

Parameters:

agents (int | AgentSetDF) – The ID(s) or AgentSetDF to check for.

Returns:

True if the agent is in the AgentContainer, False otherwise.

Return type:

bool

__copy__() → Self

Create a shallow copy of the AgentContainer.

Returns:

A shallow copy of the AgentContainer.

Return type:

Self

__deepcopy__(memo: dict) → Self

Create a deep copy of the AgentContainer.

Parameters:

memo (dict) – A dictionary to store the copied objects.

Returns:

A deep copy of the AgentContainer.

Return type:

Self

__iadd__(other: DataFrame | Sequence[Any] | dict[str, Any]) → Self

Add agents to the AgentSetDF through the += operator.

Other can be: - A DataFrame: adds the agents from the DataFrame. - A Sequence[Any]: should be one single agent to add. - A dictionary: keys should be attributes and values should be the values to add.

Parameters:

other (DataFrame | Sequence[Any] | dict[str, Any]) – The agents to add.

Returns:

The updated AgentContainer.

Return type:

Self

__isub__(other: int | Collection[int] | Series | AgentSetDF | Collection[AgentSetDF]) → Self

Remove agents from the AgentContainer through the -= operator.

Parameters:

other (IdsLike | AgentSetDF | Collection[AgentSetDF]) – The agents to remove.

Returns:

The updated AgentContainer.

Return type:

Self

__iter__() → Iterator[dict[str, Any]]

Iterate over the agents in the AgentContainer.

Returns:

An iterator over the agents.

Return type:

Iterator[dict[str, Any]]

__repr__() → str

Get a string representation of the DataFrame in the AgentContainer.

Returns:

A string representation of the DataFrame in the AgentContainer.

Return type:

str

__setitem__(key: str | Collection[str] | Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame, str | Collection[str]], values: Any) → None

Implement the [] operator for setting values in the AgentContainer.

The key can be: - A string (eg. AgentContainer[“str”]): sets the specified column of the agents in the AgentContainer. - A list of strings(eg. AgentContainer[[“str1”, “str2”]]): sets the specified columns of the agents in the AgentContainer. - A tuple (eg. AgentContainer[AgentMask, “str”]): sets the specified column of the agents in the AgentContainer that satisfy the AgentMask. - A AgentMask (eg. AgentContainer[AgentMask]): sets the attributes of the agents in the AgentContainer that satisfy the AgentMask.

Parameters:

• key (str | Collection[str] | AgentMask | tuple[AgentMask, str | Collection[str]]) – The key to set.

• values (Any) – The values to set for the specified key.

__str__() → str

Get a string representation of the agents in the AgentContainer.

Returns:

A string representation of the agents in the AgentContainer.

Return type:

str

__sub__(other: int | Collection[int] | Series | AgentSetDF | Collection[AgentSetDF]) → Self

Remove agents from a new AgentContainer through the - operator.

Parameters:

other (IdsLike | AgentSetDF | Collection[AgentSetDF]) – The agents to remove.

Returns:

A new AgentContainer with the removed agents.

Return type:

Self

copy(deep: bool = False, memo: dict | None = None, skip: list[str] | None = None) → Self

Create a copy of the Class.

Parameters:

• deep (bool, optional) – Flag indicating whether to perform a deep copy of the AgentContainer. If True, all attributes of the AgentContainer will be recursively copied (except attributes in self._copy_reference_only). If False, only the top-level attributes will be copied. Defaults to False.

• memo (dict | None, optional) – A dictionary used to track already copied objects during deep copy. Defaults to None.

• skip (list[str] | None, optional) – A list of attribute names to skip during the copy process. Defaults to None.

Returns:

A new instance of the AgentContainer class that is a copy of the original instance.

Return type:

Self

discard(agents: int | Collection[int] | Series, inplace: bool = True) → Self

Remove an agent from the AgentSetDF. Does not raise an error if the agent is not found.

Parameters:

• agents (IdsLike) – The ids to remove

• inplace (bool, optional) – Whether to remove the agent in place, by default True

Returns:

The updated AgentSetDF.

Return type:

Self

do(method_name: str, *args, mask: Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame = None, return_results: bool = False, inplace: bool = True, **kwargs) → Self | Any

Invoke a method on the AgentContainer.

Parameters:

• method_name (str) – The name of the method to invoke.

• *args (Any) – Positional arguments to pass to the method

• mask (AgentMask | None, optional) – The subset of agents on which to apply the method

• return_results (bool, optional) – Whether to return the result of the method, by default False

• inplace (bool, optional) – Whether the operation should be done inplace, by default False

• **kwargs (Any) – Keyword arguments to pass to the method

Returns:

The updated AgentContainer or the result of the method.

Return type:

Self | Any | dict[AgentSetDF, Any]

property model: ModelDF

The model that the AgentContainer belongs to.

Return type:

ModelDF

property random: Generator

The random number generator of the model.

Return type:

Generator

remove(agents: int | Collection[int] | Series, inplace: bool = True) → Self

Remove the agents from the AgentContainer.

Parameters:

• agents (IdsLike | AgentSetDF | Collection[AgentSetDF]) – The agents to remove.

• inplace (bool, optional) – Whether to remove the agent in place.

Returns:

The updated AgentContainer.

Return type:

Self

property space: SpaceDF

The space of the model.

Return type:

SpaceDF

abstractmethod step() → None

Run a single step of the AgentSetDF. This method should be overridden by subclasses.

__len__() → int

Get the number of agents in the AgentContainer.

Returns:

The number of agents in the AgentContainer.

Return type:

int

__reversed__() → Iterator

Iterate over the agents in the AgentContainer in reverse order.

Returns:

An iterator over the agents in reverse order.

Return type:

Iterator

property agents: DataFrame

The agents in the AgentContainer.

Return type:

DataFrame | dict[str, DataFrame]

property active_agents: DataFrame

The active agents in the AgentContainer.

Return type:

DataFrame | dict[str, DataFrame]

property inactive_agents: DataFrame

The inactive agents in the AgentContainer.

Return type:

DataFrame | dict[AgentSetDF, DataFrame]

property index: Series

The ids in the AgentContainer.

Return type:

Index | dict[AgentSetDF, Index]

property pos: DataFrame

The position of the agents in the AgentContainer.

Return type:

DataFrame | dict[str, DataFrame]

class mesa_frames.AgentsDF(model: ModelDF)

A collection of AgentSetDFs. All agents of the model are stored here.

Methods:

__init__	Initialize a new AgentsDF.
add	Add an AgentSetDF to the AgentsDF.
contains	Check if agents with the specified IDs are in the AgentContainer.
do	Invoke a method on the AgentContainer.
get	Retrieve the value of a specified attribute for each agent in the AgentContainer.
remove	Remove the agents from the AgentContainer.
select	Select agents in the AgentContainer based on the given criteria.
set	Set the value of a specified attribute or attributes for each agent in the mask in AgentContainer.
shuffle	Shuffles the order of agents in the AgentContainer.
sort	Sorts the agents in the agent set based on the given criteria.
step	Advance the state of the agents in the AgentsDF by one step.
__add__	Add AgentSetDFs to a new AgentsDF through the + operator.
__getattr__	Fallback for retrieving attributes of the AgentContainer.
__getitem__	Implement the [] operator for the AgentContainer.
__iadd__	Add AgentSetDFs to the AgentsDF through the += operator.
__iter__	Iterate over the agents in the AgentContainer.
__isub__	Remove AgentSetDFs from the AgentsDF through the -= operator.
__len__	Get the number of agents in the AgentContainer.
__repr__	Get a string representation of the DataFrame in the AgentContainer.
__reversed__	Iterate over the agents in the AgentContainer in reverse order.
__setitem__	Implement the [] operator for setting values in the AgentContainer.
__contains__	Check if an agent is in the AgentContainer.
__copy__	Create a shallow copy of the AgentContainer.
__deepcopy__	Create a deep copy of the AgentContainer.
__str__	Get a string representation of the agents in the AgentContainer.
copy	Create a copy of the Class.
discard	Remove agents from the AgentContainer.
__sub__	Remove AgentSetDFs from a new AgentsDF through the - operator.

Attributes:

model	The model that the AgentContainer belongs to.
random	The random number generator of the model.
space	The space of the model.
agents	The agents in the AgentContainer.
active_agents	The active agents in the AgentContainer.
agentsets_by_type	Get the agent sets in the AgentsDF grouped by type.
inactive_agents	The inactive agents in the AgentContainer.
index	The ids in the AgentContainer.
pos	The position of the agents in the AgentContainer.

__init__(model: ModelDF) → None

Initialize a new AgentsDF.

Parameters:

model (ModelDF) – The model associated with the AgentsDF.

add(agents: AgentSetDF | Iterable[AgentSetDF], inplace: bool = True) → Self

Add an AgentSetDF to the AgentsDF.

Parameters:

• agents (AgentSetDF | Iterable[AgentSetDF]) – The AgentSetDF to add.

• inplace (bool, optional) – Whether to add the AgentSetDF in place.

Returns:

The updated AgentsDF.

Return type:

Self

Raises:

ValueError – If some agentsets are already present in the AgentsDF or if the IDs are not unique.

contains(agents: int | Collection[int] | Series | AgentSetDF | Iterable[AgentSetDF]) → bool | Series

Check if agents with the specified IDs are in the AgentContainer.

Parameters:

agents (IdsLike) – The ID(s) to check for.

Returns:

True if the agent is in the AgentContainer, False otherwise.

Return type:

bool | BoolSeries

do(method_name: str, *args, mask: Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame] = None, return_results: bool = False, inplace: bool = True, **kwargs) → Self | Any

Invoke a method on the AgentContainer.

Parameters:

• method_name (str) – The name of the method to invoke.

• *args (Any) – Positional arguments to pass to the method

• mask (AgentMask | None, optional) – The subset of agents on which to apply the method

• return_results (bool, optional) – Whether to return the result of the method, by default False

• inplace (bool, optional) – Whether the operation should be done inplace, by default False

• **kwargs (Any) – Keyword arguments to pass to the method

Returns:

The updated AgentContainer or the result of the method.

Return type:

Self | Any | dict[AgentSetDF, Any]

get(attr_names: str | Collection[str] | None = None, mask: Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame] = None) → dict[AgentSetDF, Series] | dict[AgentSetDF, DataFrame]

Retrieve the value of a specified attribute for each agent in the AgentContainer.

Parameters:

• attr_names (str | Collection[str] | None, optional) – The attributes to retrieve. If None, all attributes are retrieved. Defaults to None.

• mask (AgentMask | None, optional) – The AgentMask of agents to retrieve the attribute for. If None, attributes of all agents are returned. Defaults to None.

Returns:

The attribute values.

Return type:

Series | dict[str, Series] | DataFrame | dict[str, DataFrame]

remove(agents: AgentSetDF | Iterable[AgentSetDF] | int | Collection[int] | Series, inplace: bool = True) → Self

Remove the agents from the AgentContainer.

Parameters:

• agents (IdsLike | AgentSetDF | Collection[AgentSetDF]) – The agents to remove.

• inplace (bool, optional) – Whether to remove the agent in place.

Returns:

The updated AgentContainer.

Return type:

Self

select(mask: Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame] = None, filter_func: Callable[[AgentSetDF], Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame] | None = None, n: int | None = None, inplace: bool = True, negate: bool = False) → Self

Select agents in the AgentContainer based on the given criteria.

Parameters:

• mask (AgentMask | None, optional) – The AgentMask of agents to be selected, by default None

• filter_func (Callable[[Self], AgentMask] | None, optional) – A function which takes as input the AgentContainer and returns a AgentMask, by default None

• n (int | None, optional) – The maximum number of agents to be selected, by default None

• negate (bool, optional) – If the selection should be negated, by default False

• inplace (bool, optional) – If the operation should be performed on the same object, by default True

Returns:

A new or updated AgentContainer.

Return type:

Self

set(attr_names: str | dict[AgentSetDF, Any] | Collection[str], values: Any | None = None, mask: Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame] = None, inplace: bool = True) → Self

Set the value of a specified attribute or attributes for each agent in the mask in AgentContainer.

Parameters:

• attr_names (DataFrameInput | str | Collection[str]) – The key can be: - A string: sets the specified column of the agents in the AgentContainer. - A collection of strings: sets the specified columns of the agents in the AgentContainer. - A dictionary: keys should be attributes and values should be the values to set. Value should be None.

• values (Any | None) – The value to set the attribute to. If None, attr_names must be a dictionary.

• mask (AgentMask | None) – The AgentMask of agents to set the attribute for.

• inplace (bool) – Whether to set the attribute in place.

Returns:

The updated agent set.

Return type:

Self

shuffle(inplace: bool = True) → Self

Shuffles the order of agents in the AgentContainer.

Parameters:

inplace (bool) – Whether to shuffle the agents in place.

Returns:

A new or updated AgentContainer.

Return type:

Self

sort(by: str | Sequence[str], ascending: bool | Sequence[bool] = True, inplace: bool = True, **kwargs) → Self

Sorts the agents in the agent set based on the given criteria.

Parameters:

• by (str | Sequence[str]) – The attribute(s) to sort by.

• ascending (bool | Sequence[bool]) – Whether to sort in ascending order.

• inplace (bool) – Whether to sort the agents in place.

• **kwargs – Keyword arguments to pass to the sort

Returns:

A new or updated AgentContainer.

Return type:

Self

step(inplace: bool = True) → Self

Advance the state of the agents in the AgentsDF by one step.

Parameters:

inplace (bool, optional) – Whether to update the AgentsDF in place, by default True

Return type:

Self

__add__(other: AgentSetDF | Iterable[AgentSetDF]) → Self

Add AgentSetDFs to a new AgentsDF through the + operator.

Parameters:

other (AgentSetDF | Iterable[AgentSetDF]) – The AgentSetDFs to add.

Returns:

A new AgentsDF with the added AgentSetDFs.

Return type:

Self

__getattr__(name: str) → dict[AgentSetDF, Any]

Fallback for retrieving attributes of the AgentContainer. Retrieve an attribute of the underlying DataFrame(s).

Parameters:

name (str) – The name of the attribute to retrieve.

Returns:

The attribute value

Return type:

Any | dict[str, Any]

__getitem__(key: str | Collection[str] | Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | tuple[dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], str] | tuple[dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], Collection[str]]) → dict[str, Series] | dict[str, DataFrame]

Implement the [] operator for the AgentContainer.

The key can be: - An attribute or collection of attributes (eg. AgentContainer[“str”], AgentContainer[[“str1”, “str2”]]): returns the specified column(s) of the agents in the AgentContainer. - An AgentMask (eg. AgentContainer[AgentMask]): returns the agents in the AgentContainer that satisfy the AgentMask. - A tuple (eg. AgentContainer[AgentMask, “str”]): returns the specified column of the agents in the AgentContainer that satisfy the AgentMask.

Parameters:

key (str| Collection[str] | AgentMask | tuple[AgentMask, str] | tuple[AgentMask, Collection[str]]) – The key to retrieve.

Returns:

The attribute values.

Return type:

Series | DataFrame | dict[str, Series] | dict[str, DataFrame]

__iadd__(agents: AgentSetDF | Iterable[AgentSetDF]) → Self

Add AgentSetDFs to the AgentsDF through the += operator.

Parameters:

agents (AgentSetDF | Iterable[AgentSetDF]) – The AgentSetDFs to add.

Returns:

The updated AgentsDF.

Return type:

Self

__iter__() → Iterator[dict[str, Any]]

Iterate over the agents in the AgentContainer.

Returns:

An iterator over the agents.

Return type:

Iterator[dict[str, Any]]

__isub__(agents: AgentSetDF | Iterable[AgentSetDF] | int | Collection[int] | Series) → Self

Remove AgentSetDFs from the AgentsDF through the -= operator.

Parameters:

agents (AgentSetDF | Iterable[AgentSetDF] | IdsLike) – The AgentSetDFs to remove.

Returns:

The updated AgentsDF.

Return type:

Self

__len__() → int

Get the number of agents in the AgentContainer.

Returns:

The number of agents in the AgentContainer.

Return type:

int

__repr__() → str

Get a string representation of the DataFrame in the AgentContainer.

Returns:

A string representation of the DataFrame in the AgentContainer.

Return type:

str

__reversed__() → Iterator

Iterate over the agents in the AgentContainer in reverse order.

Returns:

An iterator over the agents in reverse order.

Return type:

Iterator

__setitem__(key: str | Collection[str] | Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | tuple[dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], str] | tuple[dict[AgentSetDF, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], Collection[str]], values: Any) → None

Implement the [] operator for setting values in the AgentContainer.

The key can be: - A string (eg. AgentContainer[“str”]): sets the specified column of the agents in the AgentContainer. - A list of strings(eg. AgentContainer[[“str1”, “str2”]]): sets the specified columns of the agents in the AgentContainer. - A tuple (eg. AgentContainer[AgentMask, “str”]): sets the specified column of the agents in the AgentContainer that satisfy the AgentMask. - A AgentMask (eg. AgentContainer[AgentMask]): sets the attributes of the agents in the AgentContainer that satisfy the AgentMask.

Parameters:

• key (str | Collection[str] | AgentMask | tuple[AgentMask, str | Collection[str]]) – The key to set.

• values (Any) – The values to set for the specified key.

__contains__(agents: int | AgentSetDF) → bool

Check if an agent is in the AgentContainer.

Parameters:

agents (int | AgentSetDF) – The ID(s) or AgentSetDF to check for.

Returns:

True if the agent is in the AgentContainer, False otherwise.

Return type:

bool

__copy__() → Self

Create a shallow copy of the AgentContainer.

Returns:

A shallow copy of the AgentContainer.

Return type:

Self

__deepcopy__(memo: dict) → Self

Create a deep copy of the AgentContainer.

Parameters:

memo (dict) – A dictionary to store the copied objects.

Returns:

A deep copy of the AgentContainer.

Return type:

Self

__str__() → str

Get a string representation of the agents in the AgentContainer.

Returns:

A string representation of the agents in the AgentContainer.

Return type:

str

copy(deep: bool = False, memo: dict | None = None, skip: list[str] | None = None) → Self

Create a copy of the Class.

Parameters:

• deep (bool, optional) – Flag indicating whether to perform a deep copy of the AgentContainer. If True, all attributes of the AgentContainer will be recursively copied (except attributes in self._copy_reference_only). If False, only the top-level attributes will be copied. Defaults to False.

• memo (dict | None, optional) – A dictionary used to track already copied objects during deep copy. Defaults to None.

• skip (list[str] | None, optional) – A list of attribute names to skip during the copy process. Defaults to None.

Returns:

A new instance of the AgentContainer class that is a copy of the original instance.

Return type:

Self

discard(agents: int | Collection[int] | Series | AgentSetDF | Collection[AgentSetDF], inplace: bool = True) → Self

Remove agents from the AgentContainer. Does not raise an error if the agent is not found.

Parameters:

• agents (IdsLike | 'AgentSetDF' | Collection['AgentSetDF']) – The agents to remove

• inplace (bool) – Whether to remove the agent in place. Defaults to True.

Return type:

Self

property model: ModelDF

The model that the AgentContainer belongs to.

Return type:

ModelDF

property random: Generator

The random number generator of the model.

Return type:

Generator

property space: SpaceDF

The space of the model.

Return type:

SpaceDF

__sub__(agents: int | Collection[int] | Series | AgentSetDF | Iterable[AgentSetDF]) → Self

Remove AgentSetDFs from a new AgentsDF through the - operator.

Parameters:

agents (IdsLike | AgentSetDF | Iterable[AgentSetDF]) – The AgentSetDFs to remove.

Returns:

A new AgentsDF with the removed AgentSetDFs.

Return type:

Self

property agents: dict[AgentSetDF, DataFrame]

The agents in the AgentContainer.

Return type:

DataFrame | dict[str, DataFrame]

property active_agents: dict[AgentSetDF, DataFrame]

The active agents in the AgentContainer.

Return type:

DataFrame | dict[str, DataFrame]

property agentsets_by_type: dict[type[AgentSetDF], Self]

Get the agent sets in the AgentsDF grouped by type.

Returns:

A dictionary mapping agent set types to the corresponding AgentsDF.

Return type:

dict[type[AgentSetDF], Self]

property inactive_agents: dict[AgentSetDF, DataFrame]

The inactive agents in the AgentContainer.

Return type:

DataFrame | dict[AgentSetDF, DataFrame]

property index: dict[AgentSetDF, Series]

The ids in the AgentContainer.

Return type:

Index | dict[AgentSetDF, Index]

property pos: dict[AgentSetDF, DataFrame]

The position of the agents in the AgentContainer.

Return type:

DataFrame | dict[str, DataFrame]