AgentSetDF

class mesa_frames.AgentSetPandas(model: ModelDF)

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

Parameters:

modelModelDF

The model that the agent set belongs to.

pandas-based implementation of AgentSetDF.

Methods:

__init__	Initialize a new AgentSetPandas.
add	Add agents to the AgentSetDF.
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.
to_polars	Convert the AgentSetPandas to an AgentSetPolars.
__getattr__	Fallback for retrieving attributes of the AgentContainer.
__iter__	Iterate over the agents in 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.
__getitem__	Implement the [] operator for the AgentContainer.
__iadd__	Add agents to the AgentSetDF through the += operator.
__isub__	Remove agents from the AgentContainer through the -= operator.
__len__	Get the number of 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.
__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 AgentSetPandas.

Overload this method to add custom initialization logic but make sure to call super().__init__(model).

Parameters:

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

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

Add agents to the AgentSetDF.

Agents can be the input to the DataFrame constructor. So, the input can be: - A DataFrame: adds the agents from the DataFrame. - A dictionary: keys should be attributes and values should be the values to add. - A Sequence[Sequence]: each inner sequence should be one single agent to add.

Parameters:

• agents (DataFrameInput) – The agents to add.

• inplace (bool, optional) – If True, perform the operation in place, by default True

Returns:

A new AgentContainer with the added agents.

Return type:

Self

contains(agents: int | Collection[int] | Series | Index) → 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: str | Collection[str] | None = None, mask: Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame = None) → Index | 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 | dict[str, Any] | Collection[str] | None = None, values: Any | None = None, mask: Sequence[int] | int | Literal['all', 'active'] | None | 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 | Series | DataFrame = None, filter_func: Callable[[Self], Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame] | 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

to_polars() → AgentSetPolars

Convert the AgentSetPandas to an AgentSetPolars.

NOTE: If a methods is not backend-agnostic (i.e., it uses pandas-specific functionality), when the method is called on the Polars version of the object, it will raise an error.

Returns:

An AgentSetPolars object with the same agents and active agents as the AgentSetPandas.

Return type:

AgentSetPolars

__getattr__(name: str) → 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]

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

Iterate over the agents in the AgentContainer.

Returns:

An iterator over the agents.

Return type:

Iterator[dict[str, Any]]

__add__(other: DataFrame | 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

__getitem__(key: str | Collection[str] | Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame | Expr | Series | DataFrame | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame | Expr | Series | DataFrame, str] | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame | Expr | Series | DataFrame, Collection[str]]) → Series | Series | DataFrame | 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__(other: DataFrame | 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 | Index | 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

__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

__setitem__(key: str | Collection[str] | Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame | Expr | Series | DataFrame | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame | 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 | Index | 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 | Index | 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 | Series | DataFrame | 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 | Index | 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

abstract step() → None

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

__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: Index

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.AgentSetPolars(model: ModelDF)

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

Parameters:

modelModelDF

The model that the agent set belongs to.

Polars-based implementation of AgentSetDF.

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 | 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 | 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 | Index | 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 | Series | DataFrame | Expr | Series | DataFrame | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Series | DataFrame | 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 | Index | 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 | Index | 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 | Series | DataFrame | 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 | Index | 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

abstract 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]