Rename 'agents' property to 'df' for AgentContainer for issue # 68 (#148)

* moved agents to df

chnages done in AgentContainer to move agents to df and  change done as rquied in agents/agentset in abstract/concrete.

Note: i have depreciated agents to use df instead to keep it compatible with others and will remove once all looks good

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* emoving agents property completely to use df property

removing agents property completely, instead use df property, also replacing agents with df in tests and boltzmann_wealth example

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* refactor: remove deprecated 'agents' property and its setter in AgentSetDF

* refactor: remove unnecessary blank line in AgentSetDF class

* refactor: rename 'agents' setter to 'df' in AgentContainer class

* refactor: update agentset property access from 'agents' to 'df' in AgentsDF class

* refactor: update agent access from 'agents' to 'df' in AntPolarsBase and subclasses

* refactor: update agent access from 'agents' to 'df' in AgentSetPolars class

* refactor: update model access from 'df' to 'agents' in fixture functions

* refactor: update agent access from 'agents' to 'df' in get_unique_ids function

* refactor: update agent access from '_agents' to '_df' across AgentSetDF, AgentsDF, and AgentSetPolars classes

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* refactor: update agent access from 'agents' to 'df' in multiple classes and tests

* refactor: update agent access from 'agents' to 'df' in README and tutorial notebook

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Adam Amer <136176500+adamamer20@users.noreply.github.com>

Author: 3 people

README.md

@@ -110,7 +110,7 @@ class MoneyAgentPolars(AgentSetPolars):
         self.select(self.wealth > 0)
 
         # Receiving agents are sampled (only native expressions currently supported)
-        other_agents = self.agents.sample(
+        other_agents = self.df.sample(
             n=len(self.active_agents), with_replacement=True
         )
 

docs/general/user-guide/1_classes.md

@@ -24,13 +24,13 @@ class MoneyAgent(AgentSetPolars):
         self["wealth"] = self["wealth"] + self.random.integers(n)
 ```
 
-You can access the underlying DataFrame where agents are stored with `self.agents`. This allows you to use DataFrame methods like `self.agents.sample` or `self.agents.group_by("wealth")` and more.
+You can access the underlying DataFrame where agents are stored with `self.df`. This allows you to use DataFrame methods like `self.df.sample` or `self.df.group_by("wealth")` and more.
 
 ## ModelDF 🏗️
 
 To add your AgentSetDF to your ModelDF, you should also add it to the agents with `+=` or `add`.
 
-NOTE: ModelDF.agents are stored in a class which is entirely similar to AgentSetDF called AgentsDF. The API of the two are the same. If you try accessing AgentsDF.agents, you will get a dictionary of `[AgentSetDF, DataFrame]`.
+NOTE: ModelDF.agents are stored in a class which is entirely similar to AgentSetDF called AgentsDF. The API of the two are the same. If you try accessing AgentsDF.df, you will get a dictionary of `[AgentSetDF, DataFrame]`.
 
 Example:
 

docs/general/user-guide/2_introductory-tutorial.ipynb

@@ -79,7 +79,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "2bac0126",
    "metadata": {},
    "outputs": [],
@@ -99,9 +99,7 @@
     "\n",
     "    def give_money(self):\n",
     "        self.select(self.wealth > 0)\n",
-    "        other_agents = self.agents.sample(\n",
-    "            n=len(self.active_agents), with_replacement=True\n",
-    "        )\n",
+    "        other_agents = self.df.sample(n=len(self.active_agents), with_replacement=True)\n",
     "        self[\"active\", \"wealth\"] -= 1\n",
     "        new_wealth = other_agents.group_by(\"unique_id\").len()\n",
     "        self[new_wealth[\"unique_id\"], \"wealth\"] += new_wealth[\"len\"]"
@@ -120,33 +118,10 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "65da4e6f",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "shape: (9, 2)\n",
-      "┌────────────┬──────────┐\n",
-      "│ statistic  ┆ wealth   │\n",
-      "│ ---        ┆ ---      │\n",
-      "│ str        ┆ f64      │\n",
-      "╞════════════╪══════════╡\n",
-      "│ count      ┆ 1000.0   │\n",
-      "│ null_count ┆ 0.0      │\n",
-      "│ mean       ┆ 1.0      │\n",
-      "│ std        ┆ 1.171056 │\n",
-      "│ min        ┆ 0.0      │\n",
-      "│ 25%        ┆ 0.0      │\n",
-      "│ 50%        ┆ 1.0      │\n",
-      "│ 75%        ┆ 2.0      │\n",
-      "│ max        ┆ 9.0      │\n",
-      "└────────────┴──────────┘\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Choose either MoneyAgentPandas or MoneyAgentPolars\n",
     "agent_class = MoneyAgentPolars\n",
@@ -155,7 +130,7 @@
     "model = MoneyModelDF(1000, agent_class)\n",
     "model.run_model(100)\n",
     "\n",
-    "wealth_dist = list(model.agents.agents.values())[0]\n",
+    "wealth_dist = list(model.agents.df.values())[0]\n",
     "# Print the final wealth distribution\n",
     "print(wealth_dist.select(pl.col(\"wealth\")).describe())"
    ]
@@ -175,7 +150,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "fbdb540810924de8",
    "metadata": {},
    "outputs": [],
@@ -184,8 +159,8 @@
     "    def __init__(self, n: int, model: ModelDF):\n",
     "        super().__init__(model)\n",
     "        ## Adding the agents to the agent set\n",
-    "        # 1. Changing the agents attribute directly (not recommended, if other agents were added before, they will be lost)\n",
-    "        \"\"\"self.agents = pl.DataFrame(\n",
+    "        # 1. Changing the df attribute directly (not recommended, if other agents were added before, they will be lost)\n",
+    "        \"\"\"self.df = pl.DataFrame(\n",
     "            {\"unique_id\": pl.arange(n, eager=True), \"wealth\": pl.ones(n, eager=True)}\n",
     "        )\"\"\"\n",
     "        # 2. Adding the dataframe with add\n",
@@ -215,9 +190,7 @@
     "        self.select(self.wealth > 0)\n",
     "\n",
     "        # Receiving agents are sampled (only native expressions currently supported)\n",
-    "        other_agents = self.agents.sample(\n",
-    "            n=len(self.active_agents), with_replacement=True\n",
-    "        )\n",
+    "        other_agents = self.df.sample(n=len(self.active_agents), with_replacement=True)\n",
     "\n",
     "        # Wealth of wealthy is decreased by 1\n",
     "        # 1. Using the __setitem__ method with self.active_agents mask\n",
@@ -254,12 +227,10 @@
     "        ## Active agents are changed to wealthy agents\n",
     "        self.select(pl.col(\"wealth\") > 0)\n",
     "\n",
-    "        other_agents = self.agents.sample(\n",
-    "            n=len(self.active_agents), with_replacement=True\n",
-    "        )\n",
+    "        other_agents = self.df.sample(n=len(self.active_agents), with_replacement=True)\n",
     "\n",
     "        # Wealth of wealthy is decreased by 1\n",
-    "        self.agents = self.agents.with_columns(\n",
+    "        self.df = self.df.with_columns(\n",
     "            wealth=pl.when(pl.col(\"unique_id\").is_in(self.active_agents[\"unique_id\"]))\n",
     "            .then(pl.col(\"wealth\") - 1)\n",
     "            .otherwise(pl.col(\"wealth\"))\n",
@@ -268,8 +239,8 @@
     "        new_wealth = other_agents.group_by(\"unique_id\").len()\n",
     "\n",
     "        # Add the income to the other agents\n",
-    "        self.agents = (\n",
-    "            self.agents.join(new_wealth, on=\"unique_id\", how=\"left\")\n",
+    "        self.df = (\n",
+    "            self.df.join(new_wealth, on=\"unique_id\", how=\"left\")\n",
     "            .fill_null(0)\n",
     "            .with_columns(wealth=pl.col(\"wealth\") + pl.col(\"len\"))\n",
     "            .drop(\"len\")\n",
@@ -438,4 +409,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/boltzmann_wealth/performance_plot.py

@@ -101,9 +101,7 @@ def give_money(self):
         self.select(self.wealth > 0)
 
         # Receiving agents are sampled (only native expressions currently supported)
-        other_agents = self.agents.sample(
-            n=len(self.active_agents), with_replacement=True
-        )
+        other_agents = self.df.sample(n=len(self.active_agents), with_replacement=True)
 
         # Wealth of wealthy is decreased by 1
         # 1. Using the __setitem__ method with self.active_agents mask
@@ -140,12 +138,10 @@ def give_money(self):
         ## Active agents are changed to wealthy agents
         self.select(pl.col("wealth") > 0)
 
-        other_agents = self.agents.sample(
-            n=len(self.active_agents), with_replacement=True
-        )
+        other_agents = self.df.sample(n=len(self.active_agents), with_replacement=True)
 
         # Wealth of wealthy is decreased by 1
-        self.agents = self.agents.with_columns(
+        self.df = self.df.with_columns(
             wealth=pl.when(pl.col("unique_id").is_in(self.active_agents["unique_id"]))
             .then(pl.col("wealth") - 1)
             .otherwise(pl.col("wealth"))
@@ -154,8 +150,8 @@ def give_money(self):
         new_wealth = other_agents.group_by("unique_id").len()
 
         # Add the income to the other agents
-        self.agents = (
-            self.agents.join(new_wealth, on="unique_id", how="left")
+        self.df = (
+            self.df.join(new_wealth, on="unique_id", how="left")
             .fill_null(0)
             .with_columns(wealth=pl.col("wealth") + pl.col("len"))
             .drop("len")

examples/sugarscape_ig/ss_polars/agents.py

@@ -45,7 +45,7 @@ def eat(self):
 
     def step(self):
         self.shuffle().do("move").do("eat")
-        self.discard(self.agents.filter(pl.col("sugar") <= 0))
+        self.discard(self.df.filter(pl.col("sugar") <= 0))
 
     def move(self):
         neighborhood = self._get_neighborhood()
@@ -175,7 +175,7 @@ def get_best_moves(self, neighborhood: pl.DataFrame):
         best_moves = pl.DataFrame()
 
         # While there are agents that do not have a best move, keep looking for one
-        while len(best_moves) < len(self.agents):
+        while len(best_moves) < len(self.df):
             # Check if there are previous agents that might make the same move (priority for the given move is > 1)
             neighborhood = neighborhood.with_columns(
                 priority=pl.col("agent_order").cum_count().over(["dim_0", "dim_1"])
@@ -232,7 +232,7 @@ def get_best_moves(self, neighborhood: pl.DataFrame):
         occupied_cells, free_cells, target_cells = self._prepare_cells(neighborhood)
         best_moves_func = self._get_best_moves()
 
-        processed_agents = np.zeros(len(self.agents), dtype=np.bool_)
+        processed_agents = np.zeros(len(self.df), dtype=np.bool_)
 
         if self.numba_target is None:
             # Non-vectorized case: we need to create and pass the best_moves array
@@ -243,7 +243,7 @@ def get_best_moves(self, neighborhood: pl.DataFrame):
                 df.struct.field("agent_order"),
                 df.struct.field("blocking_agent_order"),
                 processed_agents,
-                best_moves=np.full(len(self.agents), -1, dtype=np.int32),
+                best_moves=np.full(len(self.df), -1, dtype=np.int32),
             )
         else:
             # Vectorized case: Polars will create the output array (best_moves) automatically

mesa_frames/abstract/agents.py

@@ -695,17 +695,17 @@ def space(self) -> mesa_frames.abstract.space.SpaceDF | None:
 
     @property
     @abstractmethod
-    def agents(self) -> DataFrame | dict[str, DataFrame]:
+    def df(self) -> DataFrame | dict[str, DataFrame]:
         """The agents in the AgentContainer.
 
         Returns
         -------
         DataFrame | dict[str, DataFrame]
         """
 
-    @agents.setter
+    @df.setter
     @abstractmethod
-    def agents(
+    def df(
         self, agents: DataFrame | list[mesa_frames.concrete.agents.AgentSetDF]
     ) -> None:
         """Set the agents in the AgentContainer.
@@ -788,7 +788,7 @@ class AgentSetDF(AgentContainer, DataFrameMixin):
         The model that the agent set belongs to.
     """
 
-    _agents: DataFrame  # The agents in the AgentSetDF
+    _df: DataFrame  # The agents in the AgentSetDF
     _mask: (
         AgentMask  # The underlying mask used for the active agents in the AgentSetDF.
     )
@@ -875,13 +875,13 @@ def do(
     ) -> Self | Any:
         masked_df = self._get_masked_df(mask)
         # If the mask is empty, we can use the object as is
-        if len(masked_df) == len(self._agents):
+        if len(masked_df) == len(self._df):
             obj = self._get_obj(inplace)
             method = getattr(obj, method_name)
             result = method(*args, **kwargs)
         else:  # If the mask is not empty, we need to create a new masked AgentSetDF and concatenate the AgentSetDFs at the end
             obj = self._get_obj(inplace=False)
-            obj._agents = masked_df
+            obj._df = masked_df
             original_masked_index = obj._get_obj_copy(obj.index)
             method = getattr(obj, method_name)
             result = method(*args, **kwargs)
@@ -937,7 +937,7 @@ def remove(self, agents: IdsLike | AgentMask, inplace: bool = True) -> Self:
         agentsdf = self.model.agents.remove(agents, inplace=inplace)
         # TODO: Refactor AgentsDF to return dict[str, AgentSetDF] instead of dict[AgentSetDF, DataFrame]
         # And assign a name to AgentSetDF? This has to be replaced by a nicer API of AgentsDF
-        for agentset in agentsdf.agents.keys():
+        for agentset in agentsdf.df.keys():
             if isinstance(agentset, self.__class__):
                 return agentset
         return self
@@ -1058,9 +1058,9 @@ def __iadd__(self, other: DataFrame | DataFrameInput) -> Self:
     @abstractmethod
     def __getattr__(self, name: str) -> Any:
         if __debug__:  # Only execute in non-optimized mode
-            if name == "_agents":
+            if name == "_df":
                 raise AttributeError(
-                    "The _agents attribute is not set. You probably forgot to call super().__init__ in the __init__ method."
+                    "The _df attribute is not set. You probably forgot to call super().__init__ in the __init__ method."
                 )
 
     @overload
@@ -1087,31 +1087,31 @@ def __getitem__(
         return attr
 
     def __len__(self) -> int:
-        return len(self._agents)
+        return len(self._df)
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}\n {str(self._agents)}"
+        return f"{self.__class__.__name__}\n {str(self._df)}"
 
     def __str__(self) -> str:
-        return f"{self.__class__.__name__}\n {str(self._agents)}"
+        return f"{self.__class__.__name__}\n {str(self._df)}"
 
     def __reversed__(self) -> Iterator:
-        return reversed(self._agents)
+        return reversed(self._df)
 
     @property
-    def agents(self) -> DataFrame:
-        return self._agents
+    def df(self) -> DataFrame:
+        return self._df
 
-    @agents.setter
-    def agents(self, agents: DataFrame) -> None:
+    @df.setter
+    def df(self, agents: DataFrame) -> None:
         """Set the agents in the AgentSetDF.
 
         Parameters
         ----------
         agents : DataFrame
             The agents to set.
         """
-        self._agents = agents
+        self._df = agents
 
     @property
     @abstractmethod

mesa_frames/abstract/space.py

@@ -439,7 +439,7 @@ def _get_ids_srs(
             return self._srs_constructor([], name="agent_id", dtype="uint64")
         if isinstance(agents, AgentSetDF):
             return self._srs_constructor(
-                self._df_index(agents.agents, "unique_id"),
+                self._df_index(agents.df, "unique_id"),
                 name="agent_id",
                 dtype="uint64",
             )
@@ -451,7 +451,7 @@ def _get_ids_srs(
                 if isinstance(a, AgentSetDF):
                     ids.append(
                         self._srs_constructor(
-                            self._df_index(a.agents, "unique_id"),
+                            self._df_index(a.df, "unique_id"),
                             name="agent_id",
                             dtype="uint64",
                         )

mesa_frames/concrete/agents.py

@@ -220,7 +220,7 @@ def get(
 
         for agentset, mask in agentsets_masks.items():
             # Fast column existence check - no data processing, just property access
-            agentset_columns = agentset.agents.columns
+            agentset_columns = agentset.df.columns
 
             # Check if all required columns exist in this agent set
             if not required_columns or all(
@@ -532,7 +532,7 @@ def __isub__(self, agents: AgentSetDF | Iterable[AgentSetDF] | IdsLike) -> Self:
         return super().__isub__(agents)
 
     def __len__(self) -> int:
-        return sum(len(agentset._agents) for agentset in self._agentsets)
+        return sum(len(agentset._df) for agentset in self._agentsets)
 
     def __repr__(self) -> str:
         return "\n".join([repr(agentset) for agentset in self._agentsets])
@@ -577,11 +577,11 @@ def __sub__(self, agents: AgentSetDF | Iterable[AgentSetDF] | IdsLike) -> Self:
         return super().__sub__(agents)
 
     @property
-    def agents(self) -> dict[AgentSetDF, DataFrame]:
-        return {agentset: agentset.agents for agentset in self._agentsets}
+    def df(self) -> dict[AgentSetDF, DataFrame]:
+        return {agentset: agentset.df for agentset in self._agentsets}
 
-    @agents.setter
-    def agents(self, other: Iterable[AgentSetDF]) -> None:
+    @df.setter
+    def df(self, other: Iterable[AgentSetDF]) -> None:
         """Set the agents in the AgentsDF.
 
         Parameters