AgentSetDF#

class mesa_frames.AgentSetPandas(model: ModelDF)[source]#

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

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

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

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

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

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

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

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[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 AgentContainer.

Return type:

Self

to_polars() AgentSetPolars[source]#

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

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

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

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

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

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

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

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

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

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

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

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

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[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 AgentContainer.

Return type:

Self

__getattr__(key: str) Series[source]#

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

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

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

Get the number of agents in the AgentContainer.

Returns:

The number of agents in the AgentContainer.

Return type:

int

__reversed__() Iterator[source]#

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]