Update documentation to clarify usage of AgentSetRegistry and improve DataCollector examples

Author: adamamer20

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

@@ -27,9 +27,9 @@ You can access the underlying DataFrame where agents are stored with `self.df`.
 
 ## Model 🏗️
 
-To add your AgentSet to your Model, you should also add it to the sets with `+=` or `add`.
+To add your AgentSet to your Model, use the registry `self.sets` with `+=` or `add`.
 
-NOTE: Model.sets are stored in a class which is entirely similar to AgentSet called AgentSetRegistry. The API of the two are the same. If you try accessing AgentSetRegistry.df, you will get a dictionary of `[AgentSet, DataFrame]`.
+Note: All agent sets live inside `AgentSetRegistry` (available as `model.sets`). Access sets through the registry, and access DataFrames from the set itself. For example: `self.sets["Preys"].df`.
 
 Example:
 
@@ -43,7 +43,8 @@ class EcosystemModel(Model):
     def step(self):
         self.sets.do("move")
         self.sets.do("hunt")
-        self.prey.do("reproduce")
+        # Access specific sets via the registry
+        self.sets["Preys"].do("reproduce")
 ```
 
 ## Space: Grid 🌐
@@ -76,18 +77,23 @@ Example:
 class ExampleModel(Model):
     def __init__(self):
         super().__init__()
-        self.sets = MoneyAgent(self)
+        # Add the set to the registry
+        self.sets.add(MoneyAgents(100, self))
+        # Configure reporters: use the registry to locate sets; get df from the set
         self.datacollector = DataCollector(
             model=self,
-            model_reporters={"total_wealth": lambda m: lambda m: list(m.sets.df.values())[0]["wealth"].sum()},
+            model_reporters={
+                "total_wealth": lambda m: m.sets["MoneyAgents"].df["wealth"].sum(),
+            },
             agent_reporters={"wealth": "wealth"},
             storage="csv",
             storage_uri="./data",
-            trigger=lambda m: m.schedule.steps % 2 == 0
+            trigger=lambda m: m.steps % 2 == 0,
         )
 
     def step(self):
-        self.sets.step()
+        # Step all sets via the registry
+        self.sets.do("step")
         self.datacollector.conditional_collect()
         self.datacollector.flush()
 ```

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

@@ -74,7 +74,9 @@
     "        self.sets += agents_cls(N, self)\n",
     "        self.datacollector = DataCollector(\n",
     "            model=self,\n",
-    "            model_reporters={\"total_wealth\": lambda m: m.agents[\"wealth\"].sum()},\n",
+    "            model_reporters={\n",
+    "                \"total_wealth\": lambda m: m.sets[\"MoneyAgents\"].df[\"wealth\"].sum()\n",
+    "            },\n",
     "            agent_reporters={\"wealth\": \"wealth\"},\n",
     "            storage=\"csv\",\n",
     "            storage_uri=\"./data\",\n",

docs/general/user-guide/4_datacollector.ipynb

@@ -120,8 +120,8 @@
     "        self.dc = DataCollector(\n",
     "            model=self,\n",
     "            model_reporters={\n",
-    "                \"total_wealth\": lambda m: list(m.sets.df.values())[0][\"wealth\"].sum(),\n",
-    "                \"n_agents\": lambda m: len(list(m.sets.df.values())[0]),\n",
+    "                \"total_wealth\": lambda m: m.sets[\"MoneyAgents\"].df[\"wealth\"].sum(),\n",
+    "                \"n_agents\": lambda m: len(m.sets[\"MoneyAgents\"]),\n",
     "            },\n",
     "            agent_reporters={\n",
     "                \"wealth\": \"wealth\",  # pull existing column\n",
@@ -175,7 +175,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "id": "5f14f38c",
    "metadata": {},
    "outputs": [
@@ -198,10 +198,8 @@
     "model_csv.dc = DataCollector(\n",
     "    model=model_csv,\n",
     "    model_reporters={\n",
-    "        \"total_wealth\": lambda m: sum(\n",
-    "            s[\"wealth\"].sum() for s in m.sets if \"wealth\" in s.df.columns\n",
-    "        ),\n",
-    "        \"n_agents\": lambda m: len(m.sets.ids),\n",
+    "        \"total_wealth\": lambda m: m.sets[\"MoneyAgents\"].df[\"wealth\"].sum(),\n",
+    "        \"n_agents\": lambda m: len(m.sets[\"MoneyAgents\"]),\n",
     "    },\n",
     "    agent_reporters={\n",
     "        \"wealth\": \"wealth\",\n",
@@ -228,7 +226,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
    "id": "8763a12b2bbd4a93a75aff182afb95dc",
    "metadata": {
     "editable": true
@@ -251,10 +249,8 @@
     "model_parq.dc = DataCollector(\n",
     "    model=model_parq,\n",
     "    model_reporters={\n",
-    "        \"total_wealth\": lambda m: sum(\n",
-    "            s[\"wealth\"].sum() for s in m.sets if \"wealth\" in s.df.columns\n",
-    "        ),\n",
-    "        \"n_agents\": lambda m: len(m.sets.ids),\n",
+    "        \"total_wealth\": lambda m: m.sets[\"MoneyAgents\"].df[\"wealth\"].sum(),\n",
+    "        \"n_agents\": lambda m: len(m.sets[\"MoneyAgents\"]),\n",
     "    },\n",
     "    agent_reporters={\n",
     "        \"wealth\": \"wealth\",\n",
@@ -283,7 +279,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": null,
    "id": "7cdc8c89c7104fffa095e18ddfef8986",
    "metadata": {
     "editable": true
@@ -294,10 +290,8 @@
     "model_s3.dc = DataCollector(\n",
     "    model=model_s3,\n",
     "    model_reporters={\n",
-    "        \"total_wealth\": lambda m: sum(\n",
-    "            s[\"wealth\"].sum() for s in m.sets if \"wealth\" in s.df.columns\n",
-    "        ),\n",
-    "        \"n_agents\": lambda m: len(m.sets.ids),\n",
+    "        \"total_wealth\": lambda m: m.sets[\"MoneyAgents\"].df[\"wealth\"].sum(),\n",
+    "        \"n_agents\": lambda m: len(m.sets[\"MoneyAgents\"]),\n",
     "    },\n",
     "    agent_reporters={\n",
     "        \"wealth\": \"wealth\",\n",