Updated subsetting notebook

docs/user-guide/subset.ipynb

@@ -131,6 +131,7 @@
    "cell_type": "markdown",
    "metadata": {
     "collapsed": false,
+    "jp-MarkdownHeadingCollapsed": true,
     "jupyter": {
      "outputs_hidden": false
     }
@@ -553,6 +554,98 @@
     "print(\"Bounding Box Mean:      \", bbox_subset_nodes.values.mean())\n",
     "print(\"Bounding Circle Mean:   \", bcircle_subset.values.mean())"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Retrieving Orignal Grid Indices"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Sometimes having the original grids' indices is useful. These indices can be stored within the subset with the `inverse_indices` variable. This can be used to store the indices of the original face centers, edge centers, and node indices. This variable can be used within the subset as follows:\n",
+    "\n",
+    "* Passing in `True`, which will store the face center indices\n",
+    "* Passing in a list of which indices to store, along with `True`, to indicate what kind of original grid indices to store.\n",
+    "    * Options for which indices to select include: `face`, `node`, and `edge`\n",
+    "\n",
+    "This currently only works when the element is `face centers`. Elements `nodes` and `edge centers` will be supported in the future."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "subset_indices = uxds[\"relhum_200hPa\"][0].subset.bounding_circle(center_coord, r, element=\"face centers\", \n",
+    "                                                                 inverse_indices=(['face', 'node', 'edge'], True))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "These indices can be retrieve through the grid:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "subset_indices.uxgrid.inverse_indices"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Determining if a Grid is a Subset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To check if a Grid (or dataset using `.uxgrid`) is a subset, we can use `Grid.is_subset`, which will return either `True` or `False`, depending on whether the `Grid` is a subset. Since `subset_indices` is a subset, using this feature we will return `True`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "subset_indices.uxgrid.is_subset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The file we have been using to create these subsets, `uxds`, is not a subset, so using the same call we will return `False:`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "uxds.uxgrid.is_subset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -571,7 +664,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.9"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

test/test_subset.py

@@ -142,9 +142,10 @@ def test_inverse_indices():
 
     assert subset.inverse_indices is not None
 
-    # Ensure code raises exceptions when the element is edges or nodes
+    # Ensure code raises exceptions when the element is edges or nodes or inverse_indices is incorrect
     assert pytest.raises(Exception, grid.subset.bounding_circle, center_coord, r=10, element="edge centers", inverse_indices=True)
     assert pytest.raises(Exception, grid.subset.bounding_circle, center_coord, r=10, element="nodes", inverse_indices=True)
+    assert pytest.raises(ValueError, grid.subset.bounding_circle, center_coord, r=10, element="face center", inverse_indices=(['not right'], True))
 
     # Test isel directly
     subset = grid.isel(n_face=[1], inverse_indices=True)

uxarray/grid/slice.py

@@ -161,6 +161,9 @@ def _slice_face_indices(
             for index_type in inverse_indices[0]:
                 if index_type in index_types:
                     inverse_indices_ds[index_type] = index_types[index_type]
+                else:
+                    raise ValueError("Incorrect type of index for `inverse_indices`. Try passing one of the following "
+                                     "instead: 'face', 'edge', 'node'")
 
         return Grid.from_dataset(
             ds,