Update: added more documentation options for database handling

Author: JohnGrigoriadis

docs/index.md

@@ -41,7 +41,7 @@ Installation Guide <source/installation_guide>
 Evolutionary Computing Course Documentation <source/ec_course_docs>
 GUI <source/GUI>
 Your first EA with ARIEL <source/ea_intro/ea_example>
-ARIEL Database Handling <source/Db_examples/db_with_pandas>
+ARIEL Database Handling <source/Db_examples/index>
 MuJoCo Data Variables Documentation <source/Mujoco_docs/mujoco_docs>
 ```
 ---

docs/source/Db_examples/db_with_pandas.ipynb

@@ -18,11 +18,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "id": "08c2e5da",
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Import the libraries\n",
     "import pandas as pd\n",
     "import matplotlib.pyplot as plt\n",
     "import sqlite3\n",
@@ -34,7 +35,7 @@
    "id": "5f210e72",
    "metadata": {},
    "source": [
-    "## How to get data about the experiment\n",
+    "## 1. How to get data about the experiment\n",
     "\n",
     "As explained above, ARIEL uses an SQL database to store the data for the individuals. This means that we have a complete file of every individual that existed during the evolution process whether they died or continued to live until the final generation.  "
    ]
@@ -44,7 +45,7 @@
    "id": "8d93181b",
    "metadata": {},
    "source": [
-    "## Database to pandas dataframe\n",
+    "## 1.1 Database to pandas dataframe\n",
     "\n",
     "All data about the individuals is stored in the `individual` table. The following line shows you how to turn the database into a pandas DataFrame, which then allows you to manipulate and use the data however you want."
    ]
@@ -313,7 +314,7 @@
    "id": "ed5d7ad0",
    "metadata": {},
    "source": [
-    "### Get population per generation\n",
+    "### 2. Get population per generation\n",
     "\n",
     "The way ARIEL keeps track of individuals is not in the form of a list for each generation like it is more usually used in EAs. Normally in EAs, the population is represented as a list holding the \"current alive population\". This means that if you want more detailed data on individuals that did not survive to the end of the evolution loop you do not have that data.\n",
     "\n",
@@ -477,7 +478,12 @@
    "id": "1ec9d1fa",
    "metadata": {},
    "source": [
-    "Now that we have the list of the ids of each individual per generation, we can start querying information from the data to get deeper insights. For this example we will extract the mean and best (min) fitness and standard deviation of the fitness per generation. "
+    "## 2. Computing fitness statistics per generation\n",
+    "\n",
+    "Now that we know which individuals were alive in each generation, we can compute:\n",
+    "- Mean fitness\n",
+    "- Standard deviation\n",
+    "- Best (minimum) fitness"
    ]
   },
   {
@@ -703,14 +709,14 @@
    "id": "8dba6c51",
    "metadata": {},
    "source": [
-    "### Plotting\n",
+    "## 3. Plotting\n",
     "\n",
     "Now that we have the mean and best fitness and standard deviation per generation, we can use them to plot the fitness progression "
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "id": "49ab868e",
    "metadata": {},
    "outputs": [
@@ -729,9 +735,9 @@
     "# Create a copy of dataframe\n",
     "df = pop_df.copy()\n",
     "\n",
-    "# Create mast to avoid missing data \n",
+    "# Create mask to avoid missing data \n",
     "# if the evolution process was done correctly this should not change anything.\n",
-    "# This mask cold be used to get custom data out of the dataframe\n",
+    "# This mask could be used to get custom data out of the dataframe\n",
     "mask = df['fitness_mean'].notna()\n",
     "\n",
     "# Get data according to the mask\n",

docs/source/Db_examples/db_with_polars.ipynb

@@ -0,0 +1,11 @@
+# ARIEL Database Handling
+
+This section discusses methods for storing, loading, and processing ARIEL experiment data using different backends.
+
+```{toctree}
+:maxdepth: 2
+
+db_with_pandas
+db_with_polars
+db_with_sqlite
+```

docs/source/Db_examples/db_with_sqlite3.ipynb

@@ -22,6 +22,7 @@ dependencies = [
   "numpy-quaternion>=2023.0.3",
   "opencv-python>=4.11.0.86",
   "pillow>=11.3.0",
+  "polars>=1.35.2",
   "pydantic>=2.11.9",
   "pydantic-settings>=2.10.1",
   "rich>=14.1.0",