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:
Initialize a new AgentSetPandas.
Add agents to the AgentSetDF.
Check if agents with the specified IDs are in the AgentContainer.
Retrieve the value of a specified attribute for each agent in the AgentContainer.
Set the value of a specified attribute or attributes for each agent in the mask in AgentContainer.
Select agents in the AgentContainer based on the given criteria.
Shuffles the order of agents in the AgentContainer.
Sorts the agents in the agent set based on the given criteria.
Convert the AgentSetPandas to an AgentSetPolars.
Fallback for retrieving attributes of the AgentContainer.
Iterate over the agents in the AgentContainer.
Add agents to a new AgentSetDF through the + operator.
Check if an agent is in the AgentContainer.
Create a shallow copy of the AgentContainer.
Create a deep copy of the AgentContainer.
Implement the [] operator for the AgentContainer.
Add agents to the AgentSetDF through the += operator.
Remove agents from the AgentContainer through the -= operator.
Get the number of agents in the AgentContainer.
Get a string representation of the DataFrame in the AgentContainer.
Implement the [] operator for setting values in the AgentContainer.
Get a string representation of the agents in the AgentContainer.
Remove agents from a new AgentContainer through the - operator.
Create a copy of the Class.
Remove an agent from the AgentSetDF.
Invoke a method on the AgentContainer.
Remove the agents from the AgentContainer.
Run a single step of the AgentSetDF.
Iterate over the agents in the AgentContainer in reverse order.
Attributes:
The model that the AgentContainer belongs to.
The random number generator of the model.
The space of the model.
The agents in the AgentContainer.
The active agents in the AgentContainer.
The inactive agents in the AgentContainer.
The ids in the AgentContainer.
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.
- 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:
- 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:
- __getattr__(name: str) Any [source]#
Fallback for retrieving attributes of the AgentContainer. Retrieve an attribute of the underlying DataFrame(s).
- __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.
- __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.
- __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.
- __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:
- __repr__() str #
Get a string representation of the DataFrame in the AgentContainer.
- Returns:
A string representation of the DataFrame in the AgentContainer.
- Return type:
- __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.
- __str__() str #
Get a string representation of the agents in the AgentContainer.
- Returns:
A string representation of the agents in the AgentContainer.
- Return type:
- __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]
- 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
- 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:
Initialize a new AgentSetPolars.
Add agents to the AgentSetPolars.
Check if agents with the specified IDs are in the AgentContainer.
Retrieve the value of a specified attribute for each agent in the AgentContainer.
Set the value of a specified attribute or attributes for each agent in the mask in AgentContainer.
Select agents in the AgentContainer based on the given criteria.
Shuffles the order of agents in the AgentContainer.
Sorts the agents in the agent set based on the given criteria.
Fallback for retrieving attributes of the AgentContainer.
Implement the [] operator for the AgentContainer.
Add agents to a new AgentSetDF through the + operator.
Check if an agent is in the AgentContainer.
Create a shallow copy of the AgentContainer.
Create a deep copy of the AgentContainer.
Add agents to the AgentSetDF through the += operator.
Remove agents from the AgentContainer through the -= operator.
Iterate over the agents in the AgentContainer.
Get a string representation of the DataFrame in the AgentContainer.
Implement the [] operator for setting values in the AgentContainer.
Get a string representation of the agents in the AgentContainer.
Remove agents from a new AgentContainer through the - operator.
Create a copy of the Class.
Remove an agent from the AgentSetDF.
Invoke a method on the AgentContainer.
Remove the agents from the AgentContainer.
Run a single step of the AgentSetDF.
Get the number of agents in the AgentContainer.
Iterate over the agents in the AgentContainer in reverse order.
Attributes:
The model that the AgentContainer belongs to.
The random number generator of the model.
The space of the model.
The agents in the AgentContainer.
The active agents in the AgentContainer.
The inactive agents in the AgentContainer.
The ids in the AgentContainer.
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.
- 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.
- 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:
- 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).
- __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.
- __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.
- __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.
- __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
- __repr__() str #
Get a string representation of the DataFrame in the AgentContainer.
- Returns:
A string representation of the DataFrame in the AgentContainer.
- Return type:
- __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.
- __str__() str #
Get a string representation of the agents in the AgentContainer.
- Returns:
A string representation of the agents in the AgentContainer.
- Return type:
- __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]
- 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:
- __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.
- property active_agents: DataFrame#
The active agents in the AgentContainer.