GEOPY-2654: DOCS: Add example on assigning parent to entities

docs/content/user_guide/groups.ipynb

@@ -26,7 +26,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -47,9 +47,14 @@
    "source": [
     "At creation, `\"myGroup\"` is written to the project ``geoh5`` file and visible in the Analyst project tree.\n",
     "\n",
-    "![Groups](./images/groups.png)\n",
-    "\n",
-    "Any entity can be accessed by its `name` or `uid` (unique identifier):"
+    "![Groups](./images/groups.png)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once added to the workspace, an entity can be accessed by its `name` or `uid` (unique identifier):"
    ]
   },
   {
@@ -61,6 +66,108 @@
     "print(group.uid)\n",
     "print(workspace.get_entity(\"myGroup\")[0] == workspace.get_entity(group.uid)[0])"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Parent/child relationship\n",
+    "\n",
+    "Any object or group can be added to another group to form a tree structure. This relationship can be established from either the parent or the child entity.\n",
+    "\n",
+    "We can create a new group and assign the parent at the onset."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The parent entity is: myGroup\n",
+      "The 'group' now has a 1 child.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Would default to the Root otherwise\n",
+    "new_group = ContainerGroup.create(workspace, parent=group)\n",
+    "\n",
+    "print(f\"The parent entity is: {new_group.parent.name}\")\n",
+    "print(f\"The 'group' now has {len(group.children)} child.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The relationship can always be changed afterwards."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "<geoh5py.groups.root.RootGroup object at 0x000001E713FEF340>\n",
+      "The 'group' now has a 0 child.\n"
+     ]
+    }
+   ],
+   "source": [
+    "new_group.parent = workspace.root\n",
+    "\n",
+    "print(new_group.parent)\n",
+    "print(f\"The 'group' now has {len(group.children)} children.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Alternatively, a child can be added from the parent."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The parent entity is: myGroup\n",
+      "The group now has 1 children.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Defaults to the root\n",
+    "another_group = ContainerGroup.create(workspace)\n",
+    "\n",
+    "# Transfer the custody to another group\n",
+    "group.add_children([another_group])\n",
+    "\n",
+    "print(f\"The parent entity is: {another_group.parent.name}\")\n",
+    "print(f\"The group now has {len(group.children)} child.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "workspace.close()"
+   ]
   }
  ],
  "metadata": {
@@ -79,7 +186,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.16"
+   "version": "3.10.17"
   }
  },
  "nbformat": 4,