Documentation/datacollector (#173)

* api reference

* classes data collector

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

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

* added dc in class and introductory tutorial

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

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

* doc error

* added ipynb doc

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

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

* edit usability

* better doc

* import datacollector from mesa_frames

---------

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

Author: 3 people

docs/api/index.rst

@@ -24,4 +24,11 @@ This page provides a high-level overview of all public mesa-frames objects, func
         .. toctree::
             :maxdepth: 2
 
-            reference/space/index
+            reference/space/index
+
+    .. grid-item-card::
+
+        .. toctree::
+            :maxdepth: 2
+
+            reference/datacollector

docs/api/reference/datacollector.rst

@@ -0,0 +1,10 @@
+Data Collection
+=====
+
+.. currentmodule:: mesa_frames
+
+.. autoclass:: DataCollector
+    :members:
+    :inherited-members:
+    :autosummary:
+    :autosummary-nosignatures:

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

@@ -64,3 +64,30 @@ class GridWorld(ModelDF):
 ```
 
 A continuous GeoSpace, NetworkSpace, and a collection to have multiple spaces in the models are in the works! 🚧
+
+## DataCollector 🗂️
+
+`DataCollector` records model- and agent-level data during simulation.
+You configure what to collect, how to store it, and when to trigger collection.
+
+Example:
+
+```python
+class ExampleModel(ModelDF):
+    def __init__(self):
+        super().__init__()
+        self.agents = MoneyAgent(self)
+        self.datacollector = DataCollector(
+            model=self,
+            model_reporters={"total_wealth": lambda m: m.agents["wealth"].sum()},
+            agent_reporters={"wealth": "wealth"},
+            storage="csv",
+            storage_uri="./data",
+            trigger=lambda m: m.schedule.steps % 2 == 0
+        )
+
+    def step(self):
+        self.agents.step()
+        self.datacollector.conditional_collect()
+        self.datacollector.flush()
+```

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

@@ -49,22 +49,32 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from mesa_frames import ModelDF, AgentSetPolars\n",
+    "from mesa_frames import ModelDF, AgentSetPolars, DataCollector\n",
     "\n",
     "\n",
     "class MoneyModelDF(ModelDF):\n",
     "    def __init__(self, N: int, agents_cls):\n",
     "        super().__init__()\n",
     "        self.n_agents = N\n",
     "        self.agents += agents_cls(N, self)\n",
+    "        self.datacollector = DataCollector(\n",
+    "            model=self,\n",
+    "            model_reporters={\"total_wealth\": lambda m: m.agents[\"wealth\"].sum()},\n",
+    "            agent_reporters={\"wealth\": \"wealth\"},\n",
+    "            storage=\"csv\",\n",
+    "            storage_uri=\"./data\",\n",
+    "            trigger=lambda m: m.schedule.steps % 2 == 0,\n",
+    "        )\n",
     "\n",
     "    def step(self):\n",
     "        # Executes the step method for every agentset in self.agents\n",
     "        self.agents.do(\"step\")\n",
     "\n",
     "    def run_model(self, n):\n",
     "        for _ in range(n):\n",
-    "            self.step()"
+    "            self.step()\n",
+    "            self.datacollector.conditional_collect\n",
+    "        self.datacollector.flush()"
    ]
   },
   {