DONT_MERGE: GSOC26: Add beginner-friendly examples for nesting and .eval()

docs/tutorials/data_manipulation.ipynb

@@ -383,6 +383,48 @@
     "list_nf = list_nf.drop(columns=[\"c\", \"d\"])  # drop the original columns\n",
     "list_nf"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Advanced Manipulation with `.eval()`\n",
+    "\n",
+    "Nested-pandas allows you to perform fast calculations on nested columns using the `.eval()` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "import nested_pandas as npd\n",
+    "\n",
+    "# Example 1: Convert a flat DataFrame into a NestedFrame\n",
+    "data = {\"star_id\": [\"Star_A\", \"Star_A\", \"Star_B\", \"Star_B\"], \"mag\": [15.3, 15.4, 12.5, 12.6]}\n",
+    "df = pd.DataFrame(data)\n",
+    "\n",
+    "nested_stars = npd.NestedFrame.from_flat(\n",
+    "    df, base_columns=[\"star_id\"], nested_columns=[\"mag\"], name=\"light_curve\"\n",
+    ")\n",
+    "print(\"--- Packed NestedFrame ---\")\n",
+    "print(nested_stars)\n",
+    "\n",
+    "# Example 2: Adding a calibration constant to a nested magnitude column\n",
+    "# Evaluate the expression and assign it to a new nested column directly inside the string\n",
+    "nf2 = nested_stars.eval(\"light_curve.calibrated_mag = light_curve.mag + 25.5\")\n",
+    "print(\"\\n--- After calibrated_mag ---\")\n",
+    "print(nf2)\n",
+    "\n",
+    "# Example 3: Combining flat variables with nested aggregations\n",
+    "# We use an f-string to inject the local variable 'a' directly into the evaluation\n",
+    "a = 10.0\n",
+    "nf3 = nested_stars.eval(f\"result = {a} + light_curve.mag.median()\")\n",
+    "print(\"\\n--- After median aggregation ---\")\n",
+    "print(nf3)"
+   ]
   }
  ],
  "metadata": {