Add documentation for group keys in visualization configuration

ChangeLog.md

@@ -4,6 +4,7 @@ Starting with v1.31.6, this file will contain a record of major features and upd
 
 ## Upcoming
 
+- Add documentation for group keys in `%%graph_notebook_vis_options` ([Link to PR](https://github.com/aws/graph-notebook/pull/703))
 - Enabled `--query-timeout` on `%%oc explain` for Neptune Analytics ([Link to PR](https://github.com/aws/graph-notebook/pull/701))
 
 ## Release 4.6.0 (September 19, 2024)

src/graph_notebook/notebooks/01-Neptune-Database/02-Visualization/Grouping-and-Appearance-Customization-Gremlin.ipynb

@@ -683,11 +683,65 @@
     "\n",
     "To customize the appearance of node groups, we want to use the [groups](https://visjs.github.io/vis-network/docs/network/groups.html#) options. There is a nearly endless amount of customization you can make to the groups using the options provided, but we will demonstrate some of the most common ones in the next few sections.\n",
     "\n",
+    "<div class=\"alert alert-block alert-info\"> \n",
+    "<details>\n",
+    "    <summary><b><i>Note on valueMap vs elementMap for group keys</i></b></summary>\n",
+    "    \n",
+    "The exact value of the group keys that you use may vary, depending on the format specified inside the `by()` step.\n",
+    "    \n",
+    "For the queries in the sections that follow, note that `by(valueMap())` is used. `valueMap` will return the property keys in the path in list form, for example:\n",
+    "    \n",
+    "```\n",
+    "path[{'country': ['MX'], 'code': ['CZM'], 'longest': [10165], ...\n",
+    "```\n",
+    "\\\n",
+    "To match, the group keys in `%%graph_notebook_vis_options` must also follow the list format.\n",
+    "    \n",
+    "```\n",
+    "{\n",
+    "  \"groups\": {\n",
+    "      \"['CA']\": {\"color\": \"red\"},\n",
+    "      \"['MX']\": {\"color\": \"rgba(9, 104, 178, 1)\"},      \n",
+    "      ...\n",
+    "  }\n",
+    "}\n",
+    "```\n",
+    "\\\n",
+    "On the other hand, we may elect to use `elementMap` instead of `valueMap` in the `by` modulator. `elementMap` differs in that it always returns property keys alone, as their original type. It will also return the `label` and `id` token properties automatically; for `valueMap`, tokens have to be explicitly requests. \n",
+    "    \n",
+    "For example, the same path generated with `elementMap` would look look like:\n",
+    "\n",
+    "```\n",
+    "path[{<T.id: 1>: '365', <T.label: 4>: 'airport', 'code': 'CZM', 'country': 'MX', ...\n",
+    "```\n",
+    "\\\n",
+    "Subsequently, we need to specify the group keys in `%%graph_notebook_vis_options` only as the base string value.\n",
+    "    \n",
+    "```\n",
+    "{\n",
+    "  \"groups\": {\n",
+    "      \"CA\": {\"color\": \"red\"},\n",
+    "      \"MX\": {\"color\": \"rgba(9, 104, 178, 1)\"},      \n",
+    "      ...\n",
+    "  }\n",
+    "}\n",
+    "```\n",
+    "\\\n",
+    "For more information on usage of `valueMap` and `elementMap`, please refer to Kelvin Lawrence's Practical Gremlin tutorials below.\n",
+    "\n",
+    "https://kelvinlawrence.net/book/Gremlin-Graph-Guide.html#vm\n",
+    "\\\n",
+    "https://kelvinlawrence.net/book/Gremlin-Graph-Guide.html#element-map\n",
+    "\n",
+    "</details>\n",
+    "</div>\n",
+    "\n",
+    "\n",
     "### Specifying Group Colors\n",
     "\n",
-    "Specifying the colors of groups is probably one of the most common customizations performed.  To accomplish this we specify the options using the `%%graph_notebook_vis_options` magic as shown below.  For each of the associated group names we use the exact property value followed by the options you would like to use for that group.\n",
+    "Specifying the colors of groups is probably one of the most common customizations performed.  To accomplish this we specify the options using the `%%graph_notebook_vis_options` magic as shown below. \n",
     "\n",
-    "**Note** Finding the exact property value for the group name can be accomplished by looking at the data returned in the Console tab.\n",
+    "For each of the associated group names, we use the exact property value followed by the options you would like to use for that group. Finding the exact property value for the group name can be accomplished by looking at the data returned in the Console tab.\n",
     "\n",
     "Run the next two cells to set the colors for our three groups to red for the airports in Canada, green for the airports in the US, and blue for the airports in Mexico.  In the case of color, the values can be specified by name, RGBA value, or Hex value."
    ]