Agents#

class mesa_frames.AgentSet(model: mesa_frames.concrete.model.Model)[source]#

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

Parameters:

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[source]#

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[source]#

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[source]#
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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#
__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]][source]#

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[source]#

Get the number of agents in the AbstractAgentSetRegistry.

Returns:

The number of agents in the AbstractAgentSetRegistry.

Return type:

int

__reversed__() Iterator[source]#

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)[source]#

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[source]#

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[source]#

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[source]#
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[source]#
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][source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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][source]#

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][source]#
__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[source]#

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]][source]#

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[source]#

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[source]#

Get the number of agents in the AbstractAgentSetRegistry.

Returns:

The number of agents in the AbstractAgentSetRegistry.

Return type:

int

__repr__() str[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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]