Update module 2 example for clearer instructions

Author: mfisher87

examples/module-2/example-2.ipynb

@@ -76,6 +76,15 @@
     "explore(gdf)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "33ca87e0-cd33-474c-aabb-88655d333b82",
+   "metadata": {},
+   "source": [
+    "* **Zoom in on the data points in boulder using your scroll wheel**.\n",
+    "* **Once you're done exploring, close the JupyterGIS explorer tab**."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "3a19593b-9112-4dfc-8015-0fb4ee210fb6",
@@ -85,7 +94,7 @@
     "\n",
     "JupyterGIS introduces a new file format for projects.\n",
     "\n",
-    "We've prepared a JupyterGIS project, i.e. a `.jGIS` file, with a basemap:"
+    "We've prepared a JupyterGIS project, i.e. a `.jGIS` file, with a basemap. Let's load it and call it `doc`:"
    ]
   },
   {
@@ -108,7 +117,9 @@
    "id": "eeac2318-9a05-4f6e-a235-f2230e46177a",
    "metadata": {},
    "source": [
-    "Let's add our example data:"
+    "No data is present in this document yet, it's just a basemap.\n",
+    "\n",
+    "* **Add our example data**:"
    ]
   },
   {
@@ -126,31 +137,34 @@
    "id": "0c2a1a42-b21f-447b-be26-9c61a3dd3bc6",
    "metadata": {},
    "source": [
-    "## The map has been updated!\n",
+    "#### The map has been updated!\n",
     "\n",
-    "But you have to scroll up to see the change in the widget.\n",
-    "Let's open that map in a new panel view instead of as an embedded widget.\n",
+    "But you have to scroll up in the Notebook to see the change in the widget.\n",
+    "We're going to make many more changes, so let's open up the project file we just built.\n",
     "\n",
-    "In the blank space to the left of the map, right-click, then select \"create new view for cell output\".\n",
-    "We'll keep the map open in a panel from now on."
+    "* **In the file browser, double-click `example.jGIS` to open the project file as a full tab**.\n",
+    "* **Click and drag that tab to move it to a split view**.\n",
+    "    * Experiment with dragging it to different places to find a comfortable layout.\n",
+    "    * Try resizing the split view by clicking and draging on the divider!"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "4851bdac-8e48-45d0-9c36-f14271c85792",
    "metadata": {},
    "source": [
-    "## The layers panel\n",
+    "#### The layers panel\n",
     "\n",
     "Let's view the layers currently on the map.\n",
     "\n",
-    "On the far left panel, click the globe icon.\n",
+    "On the left panel, you should see the JupyterGIS layers panel. You may need to expand it!\n",
     "\n",
-    "Then expand the \"Layers\" view within the new panel.\n",
+    "* If you don't see the layers panel, click the globe icon on the **far** left column of icons.\n",
+    "* If the layers view is collapsed, expand it.\n",
+    "* **Right click on \"SEEC and NSIDC\" and select \"Zoom to Layer\"**.\n",
     "\n",
-    "Right click on \"SEEC and NSIDC\" and select \"Zoom to Layer\".\n",
-    "You should see your data points on the furthest edges of the map, but the basemap has likely become unusable.\n",
-    "Zoom out a little bit by scrolling."
+    "    You should see your data points on the furthest edges of the map.\n",
+    "    Zoom out a little bit to see the data points more clearly."
    ]
   },
   {
@@ -160,11 +174,17 @@
    "source": [
     "## Challenge\n",
     "\n",
-    "### Add the other dataset you created in the previous module\n",
+    "### Add the \"final\" dataset you created in Module 1\n",
+    "\n",
+    "`example.jGIS` should already be open in a separate window.\n",
     "\n",
-    "You created a dataset with a location that's meaningful to you in the previous module. Load that dataset in the cell below, and check that the map updated!\n",
+    "* **Add the final dataset from the previous module as a layer in the cell below**, and check that the map updated!\n",
     "\n",
-    "Don't forget to give your new layer a name. Also, consider that you may need to specify a relative path, e.g. `../module-1/final.geojson`."
+    "    Hint: Don't forget to give your new layer a meaningful name.\n",
+    "\n",
+    "    Hint: Reference the code cells above to see how to add a geojson layer to the map.\n",
+    "\n",
+    "    Hint: The dataset you created was named `final.geojson`, but it's in a different directory than this notebook. The path to the layer you should use is `\"../module-1/final.geojson\"`."
    ]
   },
   {
@@ -174,47 +194,68 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Add your GeoJSON layer in this cell."
+    "# Add your GeoJSON layer to the doc in this cell."
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "b5c0736c-0b6c-4930-9bdf-0b256028b400",
+   "id": "b9b1faad-ea7a-4a5e-ae86-74dea098c82e",
+   "metadata": {},
+   "source": [
+    ":::{hint} Solution\n",
+    ":class: dropdown\n",
+    "\n",
+    "Here is a solution you can copy/paste:\n",
+    "\n",
+    "```python\n",
+    "doc.add_geojson_layer(\"../module-1/final.geojson\", name=\"My module-1 dataset\")\n",
+    "```\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3365876f-d5cb-4c74-924e-6c5df91ee324",
    "metadata": {
     "jp-MarkdownHeadingCollapsed": true
    },
    "source": [
-    "### Identify points\n",
+    "### Let's play with a different data source\n",
     "\n",
-    "In the toolbar at the top of the map, select the \"i\" icon to toggle on identify mode.\n",
+    "* In the map panel, **click the ➕ icon in the toolbar at the top of the map**.\n",
+    "* **Select \"Add Vector Layer\"**, then **\"New GeoJSON Layer\"**.\n",
+    "* In the dialog's \"Path\" field, **select \"Browse Server Files\"**.\n",
+    "* **Navigate to the `workshop-csdms2025-exercises/examples/module-2` directory**.\n",
+    "* **Select `us_cities.geojson`**.\n",
+    "* **Click the \"Select\" button**.\n",
+    "* **Click \"OK\"**.\n",
     "\n",
-    "Select the layer in the layers panel you want to identify features from.\n",
-    "Click a point to see its attributes.\n",
-    "They'll be visible in the \"identify\" section of the right panel.\n",
+    "You may notice that the added layer is titled \"Custom GeoJSON Layer\". Let's fix that!\n",
     "\n",
-    "If the right panel isn't open, click the globe icon in the far right of JupyterLab.\n",
-    "If the \"identify\" section isn't visible, you may need to expand it (the triangle to the left of the word \"identify\" should be pointing **down**).\n",
-    "If it's still not visible, you may need to shrink the other open panels by clicking and dragging at the edge, or by collapsing it entirely."
+    "* **Right-click the layer and select \"Rename Layer\"**.\n",
+    "* **Title it \"US Cities\"**."
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "3365876f-d5cb-4c74-924e-6c5df91ee324",
-   "metadata": {},
+   "id": "b5c0736c-0b6c-4930-9bdf-0b256028b400",
+   "metadata": {
+    "jp-MarkdownHeadingCollapsed": true
+   },
    "source": [
-    "### Let's play with other data sources.\n",
+    "### Identify points\n",
     "\n",
-    "The JupyterGIS Python API doesn't yet support adding remote GeoJSON layers, so we'll use the JupyterGIS GUI for this.\n",
+    "Sometimes you want to learn more about features than what you can see on the map. For example, the population of a city.\n",
     "\n",
-    "In the map panel, click the ➕ icon in the toolbar at the top of the map.\n",
-    "Select \"Add Vector Layer\", then \"New GeoJSON Layer\".\n",
-    "In the dialog's \"Path\" field, select \"Browse Server Files\".\n",
-    "Navigate to the `workshop-csdms2025-exercises/examples/module-2` directory, then select `us_cities.geojson`.\n",
+    "* **In the toolbar at the top of the map, select the \"i\" icon to toggle on identify mode**.\n",
+    "* **Select the US Cities layer you added in the previous step**.\n",
+    "* **Click a point to see its attributes**.\n",
     "\n",
-    "Click the \"Select\" button, then click \"OK\".\n",
+    "    They'll be visible in the \"identify\" section of the right panel.\n",
     "\n",
-    "You may notice that the added layer is titled \"Custom GeoJSON Layer\". Right-click the layer and select \"Rename Layer\".\n",
-    "Title it \"US Cities\"."
+    "* If the right panel isn't open, click the globe icon in the far right of JupyterLab.\n",
+    "* If the \"identify\" section isn't visible, you may need to expand it (the triangle to the left of the word \"identify\" should be pointing **down**).\n",
+    "* If it's still not visible, you may need to shrink the other open panels by clicking and dragging at the edge, or by collapsing it entirely."
    ]
   },
   {
@@ -224,25 +265,37 @@
    "source": [
     "### Add symbology\n",
     "\n",
+    "Viewing points one-by-one isn't always what we need; sometimes we need to be able to see patterns on the map visually.\n",
+    "\n",
     "**⚠️ There's a bug here, watch out! ⚠️**\n",
     "\n",
     "Don't forget, **JupyterGIS is in early stages. It will get much better!**\n",
     "\n",
     "#### Work around the bug\n",
     "\n",
-    "Before we can apply symbology, we need to set the vector type to \"circle\" in the right panel.\n",
-    "Under \"Objects properties\", select \"Circle\" in the Type dropdown, then click OK.\n",
+    "Before we can apply symbology, we need to work around a bug.\n",
+    "\n",
+    "* **Set the vector type to \"circle\" in the right panel.**\n",
+    "* **Under \"Objects properties\", select \"Circle\" in the \"Type\" dropdown, then click OK.**\n",
     "You may need to scroll down, resize, or collapse sections of the right sidebar to see the OK button.\n",
     "\n",
     "#### Now, we can set symbology!\n",
     "\n",
-    "Right click on the \"US Cities\" layer in the left panel.\n",
-    "Select \"Edit symbology\".\n",
-    "Select \"Render type: Graduated\", \"Value: ELEV_IN_FT\", \"Method: Color\".\n",
-    "Select your favorite colormap (**please, don't select \"Rainbow\" - it is not an effective colormap**).\n",
-    "Click \"Classify\", then click \"OK\".\n",
+    "* **Right click on the \"US Cities\" layer in the left panel**.\n",
+    "* **Select \"Edit symbology\"**.\n",
+    "* **Input the following settings**\n",
+    "\n",
+    "    You may want to view these settings in a separate window; SHIFT+right-click the image and select \"Open in new window\"\n",
+    "\n",
+    "    ![JupyterGIS symbology settings](jgis-symbology-menu.png)\n",
+    "  \n",
+    "    * Render type: Graduated\n",
+    "    * Value: ELEV_IN_FT\n",
+    "    * Method: Color\n",
+    "    * Select your favorite colormap (**please, don't select \"Rainbow\" - it is not an effective colormap**).\n",
+    "* **Click \"Classify\", then click \"OK\".**\n",
     "\n",
-    "What's the highest-elevation city you can see?\n",
+    "What's the highest elevation value you can see?\n",
     "What would you do differently to make it easier to find?\n",
     "Do you see any flaws in this dataset when you use \"Identify\" on the points?"
    ]