Agents

class mesa_frames.AgentSet(model: mesa_frames.concrete.model.Model)

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

Parameters:

• model (mesa_frames.concrete.model.Model) – The model that the agent set belongs to.

• AgentSet. (Polars-based implementation of)

Methods:

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

Attributes:

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

__init__(model: mesa_frames.concrete.model.Model) → None

Initialize a new AgentSet.

Parameters:

model ("mesa_frames.concrete.model.Model") – The model that the agent set belongs to.

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

Add agents to the AgentSet.

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 AgentSet.

Return type:

Self

contains(agents: int) → bool

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

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

Parameters:

agents (mesa_frames.abstract.agentset.AbstractAgentSet | IdsLike) – The ID(s) to check for.

Returns:

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

Return type:

bool | BoolSeries

get(attr_names: int | float | date | time | datetime | timedelta | str | bool | bytes | list[Any] | Expr | Series | None | Iterable[int | float | 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 AbstractAgentSetRegistry.

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 AbstractAgentSetRegistry.

Parameters:

• attr_names (DataFrameInput | str | Collection[str]) – The key can be: - A string: sets the specified column of the agents in the AbstractAgentSetRegistry. - A collection of strings: sets the specified columns of the agents in the AbstractAgentSetRegistry. - 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 AbstractAgentSetRegistry 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 AbstractAgentSetRegistry 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 AbstractAgentSetRegistry.

Return type:

Self

shuffle(inplace: bool = True) → Self

Shuffles the order of agents in the AbstractAgentSetRegistry.

Parameters:

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

Returns:

A new or updated AbstractAgentSetRegistry.

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 AbstractAgentSetRegistry.

Return type:

Self

__getattr__(key: str) → Series

Fallback for retrieving attributes of the AbstractAgentSetRegistry. 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 | tuple[Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame, str]) → Series

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

Implement the [] operator for the AbstractAgentSetRegistry.

The key can be: - An attribute or collection of attributes (eg. AbstractAgentSetRegistry[“str”], AbstractAgentSetRegistry[[“str1”, “str2”]]): returns the specified column(s) of the agents in the AbstractAgentSetRegistry. - An AgentMask (eg. AbstractAgentSetRegistry[AgentMask]): returns the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A tuple (eg. AbstractAgentSetRegistry[AgentMask, “str”]): returns the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, “str”]): returns the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, Collection[str]]): returns the specified columns of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary.

Parameters:

key (str | Collection[str] | AgentMask | tuple[AgentMask, str] | tuple[AgentMask, Collection[str]] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], str] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], Collection[str]]) – The key to retrieve.

Returns:

The attribute values.

Return type:

Series | DataFrame | dict[mesa_frames.abstract.agentset.AbstractAgentSet, Series] | dict[mesa_frames.abstract.agentset.AbstractAgentSet, DataFrame]

__add__(other: DataFrame | Mapping[str, Sequence[object] | Mapping[str, Sequence[object]] | Series | Any] | Sequence[Any] | ndarray | Table | DataFrame) → Self

Add agents to a new AbstractAgentSet through the + operator.

Other can be: - A DataFrame: adds the agents from the DataFrame. - A DataFrameInput: passes the input to the DataFrame constructor.

Parameters:

other (DataFrame | DataFrameInput) – The agents to add.

Returns:

A new AbstractAgentSetRegistry with the added agents.

Return type:

Self

__contains__(agents: int | mesa_frames.abstract.agentset.AbstractAgentSet) → bool

Check if an agent is in the AbstractAgentSetRegistry.

Parameters:

agents (int | mesa_frames.abstract.agentset.AbstractAgentSet) – The ID(s) or AbstractAgentSet to check for.

Returns:

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

Return type:

bool

__copy__() → Self

Create a shallow copy of the AbstractAgentSetRegistry.

Returns:

A shallow copy of the AbstractAgentSetRegistry.

Return type:

Self

__deepcopy__(memo: dict) → Self

Create a deep copy of the AbstractAgentSetRegistry.

Parameters:

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

Returns:

A deep copy of the AbstractAgentSetRegistry.

Return type:

Self

__iadd__(other: DataFrame | Mapping[str, Sequence[object] | Mapping[str, Sequence[object]] | Series | Any] | Sequence[Any] | ndarray | Table | DataFrame) → Self

Add agents to the AbstractAgentSet through the += operator.

Other can be: - A DataFrame: adds the agents from the DataFrame. - A DataFrameInput: passes the input to the DataFrame constructor.

Parameters:

other (DataFrame | DataFrameInput) – The agents to add.

Returns:

The updated AbstractAgentSetRegistry.

Return type:

Self

__isub__(other: IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) → Self

Remove agents from the AbstractAgentSetRegistry through the -= operator.

Parameters:

other (IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) – The agents to remove.

Returns:

The updated AbstractAgentSetRegistry.

Return type:

Self

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

Iterate over the agents in the AbstractAgentSetRegistry.

Returns:

An iterator over the agents.

Return type:

Iterator[dict[str, Any]]

__repr__() → str

Get a string representation of the DataFrame in the AbstractAgentSetRegistry.

Returns:

A string representation of the DataFrame in the AbstractAgentSetRegistry.

Return type:

str

__setitem__(key: str | Collection[str] | AgentMask | tuple[AgentMask, str | Collection[str]] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], str] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], Collection[str]], values: Any) → None

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

The key can be: - A string (eg. AbstractAgentSetRegistry[“str”]): sets the specified column of the agents in the AbstractAgentSetRegistry. - A list of strings(eg. AbstractAgentSetRegistry[[“str1”, “str2”]]): sets the specified columns of the agents in the AbstractAgentSetRegistry. - A tuple (eg. AbstractAgentSetRegistry[AgentMask, “str”]): sets the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A AgentMask (eg. AbstractAgentSetRegistry[AgentMask]): sets the attributes of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, “str”]): sets the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, Collection[str]]): sets the specified columns of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary.

Parameters:

• key (str | Collection[str] | AgentMask | tuple[AgentMask, str | Collection[str]] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], str] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], 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 AbstractAgentSetRegistry.

Returns:

A string representation of the agents in the AbstractAgentSetRegistry.

Return type:

str

__sub__(other: IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) → Self

Remove agents from a new AbstractAgentSetRegistry through the - operator.

Parameters:

other (IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) – The agents to remove.

Returns:

A new AbstractAgentSetRegistry 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 AbstractAgentSetRegistry. If True, all attributes of the AbstractAgentSetRegistry 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 AbstractAgentSetRegistry class that is a copy of the original instance.

Return type:

Self

discard(agents: int | Collection[int] | Series | DataFrame | Sequence[int] | Literal['all', 'active'] | None | Expr, inplace: bool = True) → Self

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

Parameters:

• agents (IdsLike | AgentMask) – The ids to remove

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

Returns:

The updated AbstractAgentSet.

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 AbstractAgentSetRegistry.

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 AbstractAgentSetRegistry or the result of the method.

Return type:

Self | Any | dict[mesa_frames.abstract.agentset.AbstractAgentSet, Any]

property model: mesa_frames.concrete.model.Model

The model that the AbstractAgentSetRegistry belongs to.

Return type:

mesa_frames.concrete.model.Model

property random: Generator

The random number generator of the model.

Return type:

Generator

remove(agents: int | Collection[int] | Series | DataFrame | Sequence[int] | Literal['all', 'active'] | None | Expr, inplace: bool = True) → Self

Remove the agents from the AbstractAgentSetRegistry.

Parameters:

• agents (IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) – The agents to remove.

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

Returns:

The updated AbstractAgentSetRegistry.

Return type:

Self

property space: mesa_frames.abstract.space.Space | None

The space of the model.

Return type:

mesa_frames.abstract.space.Space | None

abstractmethod step() → None

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

__len__() → int

Get the number of agents in the AbstractAgentSetRegistry.

Returns:

The number of agents in the AbstractAgentSetRegistry.

Return type:

int

__reversed__() → Iterator

Iterate over the agents in the AbstractAgentSetRegistry in reverse order.

Returns:

An iterator over the agents in reverse order.

Return type:

Iterator

property df: DataFrame

The agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[str, DataFrame]

property active_agents: DataFrame

The active agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[str, DataFrame]

property inactive_agents: DataFrame

The inactive agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[mesa_frames.abstract.agentset.AbstractAgentSet, DataFrame]

property index: Series

The ids in the AbstractAgentSetRegistry.

Return type:

Index | dict[mesa_frames.abstract.agentset.AbstractAgentSet, Index]

property pos: DataFrame

The position of the agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[mesa_frames.abstract.agentset.AbstractAgentSet, DataFrame]

class mesa_frames.AgentSetRegistry(model: mesa_frames.concrete.model.Model)

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

Methods:

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

Attributes:

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

__init__(model: mesa_frames.concrete.model.Model) → None

Initialize a new AgentSetRegistry.

Parameters:

model (mesa_frames.concrete.model.Model) – The model associated with the AgentSetRegistry.

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

Add an AgentSet to the AgentSetRegistry.

Parameters:

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

• inplace (bool, optional) – Whether to add the AgentSets in place. Defaults to True.

Returns:

The updated AgentSetRegistry.

Return type:

Self

Raises:

ValueError – If any AgentSets are already present or if IDs are not unique.

contains(agents: int | AgentSet) → bool

contains(agents: int | Collection[int] | Series | DataFrame | Iterable[AgentSet]) → Series

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

Parameters:

agents (mesa_frames.abstract.agentset.AbstractAgentSet | IdsLike) – The ID(s) to check for.

Returns:

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

Return type:

bool | BoolSeries

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

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

Invoke a method on the AbstractAgentSetRegistry.

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 AbstractAgentSetRegistry or the result of the method.

Return type:

Self | Any | dict[mesa_frames.abstract.agentset.AbstractAgentSet, Any]

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

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

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: AgentSet | Iterable[AgentSet] | int | Collection[int] | Series | DataFrame, inplace: bool = True) → Self

Remove the agents from the AbstractAgentSetRegistry.

Parameters:

• agents (IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) – The agents to remove.

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

Returns:

The updated AbstractAgentSetRegistry.

Return type:

Self

select(mask: Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | DataFrame | dict[AgentSet, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame] = None, filter_func: Callable[[AgentSet], 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 AbstractAgentSetRegistry 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 AbstractAgentSetRegistry 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 AbstractAgentSetRegistry.

Return type:

Self

set(attr_names: str | dict[AgentSet, Any] | Collection[str], values: Any | None = None, mask: Sequence[int] | int | Literal['all', 'active'] | None | Collection[int] | Series | DataFrame | dict[AgentSet, 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 AbstractAgentSetRegistry.

Parameters:

• attr_names (DataFrameInput | str | Collection[str]) – The key can be: - A string: sets the specified column of the agents in the AbstractAgentSetRegistry. - A collection of strings: sets the specified columns of the agents in the AbstractAgentSetRegistry. - 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 AbstractAgentSetRegistry.

Parameters:

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

Returns:

A new or updated AbstractAgentSetRegistry.

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 AbstractAgentSetRegistry.

Return type:

Self

step(inplace: bool = True) → Self

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

Parameters:

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

Return type:

Self

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

Add AgentSets to a new AgentSetRegistry through the + operator.

Parameters:

other (AgentSet | Iterable[AgentSet]) – The AgentSets to add.

Returns:

A new AgentSetRegistry with the added AgentSets.

Return type:

Self

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

Fallback for retrieving attributes of the AbstractAgentSetRegistry. 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 | tuple[dict[AgentSet, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], str]) → dict[AgentSet, Series | Expr]

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

Implement the [] operator for the AbstractAgentSetRegistry.

The key can be: - An attribute or collection of attributes (eg. AbstractAgentSetRegistry[“str”], AbstractAgentSetRegistry[[“str1”, “str2”]]): returns the specified column(s) of the agents in the AbstractAgentSetRegistry. - An AgentMask (eg. AbstractAgentSetRegistry[AgentMask]): returns the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A tuple (eg. AbstractAgentSetRegistry[AgentMask, “str”]): returns the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, “str”]): returns the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, Collection[str]]): returns the specified columns of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary.

Parameters:

key (str | Collection[str] | AgentMask | tuple[AgentMask, str] | tuple[AgentMask, Collection[str]] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], str] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], Collection[str]]) – The key to retrieve.

Returns:

The attribute values.

Return type:

Series | DataFrame | dict[mesa_frames.abstract.agentset.AbstractAgentSet, Series] | dict[mesa_frames.abstract.agentset.AbstractAgentSet, DataFrame]

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

Add AgentSets to the AgentSetRegistry through the += operator.

Parameters:

agents (AgentSet | Iterable[AgentSet]) – The AgentSets to add.

Returns:

The updated AgentSetRegistry.

Return type:

Self

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

Iterate over the agents in the AbstractAgentSetRegistry.

Returns:

An iterator over the agents.

Return type:

Iterator[dict[str, Any]]

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

Remove AgentSets from the AgentSetRegistry through the -= operator.

Parameters:

agents (AgentSet | Iterable[AgentSet] | IdsLike) – The AgentSets or agent IDs to remove.

Returns:

The updated AgentSetRegistry.

Return type:

Self

__len__() → int

Get the number of agents in the AbstractAgentSetRegistry.

Returns:

The number of agents in the AbstractAgentSetRegistry.

Return type:

int

__repr__() → str

Get a string representation of the DataFrame in the AbstractAgentSetRegistry.

Returns:

A string representation of the DataFrame in the AbstractAgentSetRegistry.

Return type:

str

__reversed__() → Iterator

Iterate over the agents in the AbstractAgentSetRegistry 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 | DataFrame | tuple[dict[AgentSet, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], str] | tuple[dict[AgentSet, Sequence[int] | int | Literal['all', 'active'] | None | Expr | Series | DataFrame], Collection[str]], values: Any) → None

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

The key can be: - A string (eg. AbstractAgentSetRegistry[“str”]): sets the specified column of the agents in the AbstractAgentSetRegistry. - A list of strings(eg. AbstractAgentSetRegistry[[“str1”, “str2”]]): sets the specified columns of the agents in the AbstractAgentSetRegistry. - A tuple (eg. AbstractAgentSetRegistry[AgentMask, “str”]): sets the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A AgentMask (eg. AbstractAgentSetRegistry[AgentMask]): sets the attributes of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, “str”]): sets the specified column of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary. - A tuple with a dictionary (eg. AbstractAgentSetRegistry[{AbstractAgentSet: AgentMask}, Collection[str]]): sets the specified columns of the agents in the AbstractAgentSetRegistry that satisfy the AgentMask from the dictionary.

Parameters:

• key (str | Collection[str] | AgentMask | tuple[AgentMask, str | Collection[str]] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], str] | tuple[dict[mesa_frames.abstract.agentset.AbstractAgentSet, AgentMask], Collection[str]]) – The key to set.

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

__contains__(agents: int | mesa_frames.abstract.agentset.AbstractAgentSet) → bool

Check if an agent is in the AbstractAgentSetRegistry.

Parameters:

agents (int | mesa_frames.abstract.agentset.AbstractAgentSet) – The ID(s) or AbstractAgentSet to check for.

Returns:

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

Return type:

bool

__copy__() → Self

Create a shallow copy of the AbstractAgentSetRegistry.

Returns:

A shallow copy of the AbstractAgentSetRegistry.

Return type:

Self

__deepcopy__(memo: dict) → Self

Create a deep copy of the AbstractAgentSetRegistry.

Parameters:

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

Returns:

A deep copy of the AbstractAgentSetRegistry.

Return type:

Self

__str__() → str

Get a string representation of the agents in the AbstractAgentSetRegistry.

Returns:

A string representation of the agents in the AbstractAgentSetRegistry.

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 AbstractAgentSetRegistry. If True, all attributes of the AbstractAgentSetRegistry 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 AbstractAgentSetRegistry class that is a copy of the original instance.

Return type:

Self

discard(agents: IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet], inplace: bool = True) → Self

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

Parameters:

• agents (IdsLike | AgentMask | mesa_frames.abstract.agentset.AbstractAgentSet | Collection[mesa_frames.abstract.agentset.AbstractAgentSet]) – The agents to remove

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

Returns:

The updated AbstractAgentSetRegistry.

Return type:

Self

property model: mesa_frames.concrete.model.Model

The model that the AbstractAgentSetRegistry belongs to.

Return type:

mesa_frames.concrete.model.Model

property random: Generator

The random number generator of the model.

Return type:

Generator

property space: mesa_frames.abstract.space.Space | None

The space of the model.

Return type:

mesa_frames.abstract.space.Space | None

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

Remove AgentSets from a new AgentSetRegistry through the - operator.

Parameters:

agents (AgentSet | Iterable[AgentSet] | IdsLike) – The AgentSets or agent IDs to remove. Supports NumPy integer types.

Returns:

A new AgentSetRegistry with the removed AgentSets.

Return type:

Self

property df: dict[AgentSet, DataFrame]

The agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[str, DataFrame]

property active_agents: dict[AgentSet, DataFrame]

The active agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[str, DataFrame]

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

Get the agent sets in the AgentSetRegistry grouped by type.

Returns:

A dictionary mapping agent set types to the corresponding AgentSetRegistry.

Return type:

dict[type[AgentSet], Self]

property inactive_agents: dict[AgentSet, DataFrame]

The inactive agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[mesa_frames.abstract.agentset.AbstractAgentSet, DataFrame]

property index: dict[AgentSet, Series | DataFrame]

The ids in the AbstractAgentSetRegistry.

Return type:

Index | dict[mesa_frames.abstract.agentset.AbstractAgentSet, Index]

property pos: dict[AgentSet, DataFrame]

The position of the agents in the AbstractAgentSetRegistry.

Return type:

DataFrame | dict[mesa_frames.abstract.agentset.AbstractAgentSet, DataFrame]