Update the reproject example

docs/examples/index.rst

@@ -0,0 +1,11 @@
+.. _dkist:examples:index:
+
+Examples
+========
+
+Each example is a self-contained tutorial working through one task.
+
+.. toctree::
+  :maxdepth: 1
+
+  reproject_vbi_mosaic

docs/howto_guides/reproject_vbi_mosaic.md → docs/examples/reproject_vbi_mosaic.md

@@ -5,7 +5,7 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.16.1
+    jupytext_version: 1.16.6
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
@@ -26,64 +26,36 @@ Reprojecting a single spatial image such as an AIA image is well supported and d
 
 We are going to use the example of using reproject's {obj}`reproject.mosaicking.reproject_and_coadd` function to stitch a mosaic of VBI frames.
 
-
-## Obtaining some data
-
-First, we must obtain the VBI data needed for the rest of the guide.
-
 ```{code-cell} ipython3
 import numpy as np
 import matplotlib.pyplot as plt
 import astropy.units as u
 
-from sunpy.net import Fido, attrs as a
-
 import dkist
-import dkist.net
+from dkist.data.sample import VBI_AJQWW
 ```
 
-```{code-cell} ipython3
-res = Fido.search(a.dkist.Dataset("AJQWW"), )
-res
-```
+## Obtaining some data
 
-```{code-cell} ipython3
-asdf_file = Fido.fetch(res, path="~/dkist_data/{dataset_id}")
-asdf_file
-```
+In this example we will use the VBI sample dataset [AJQWW](https://dkist.data.nso.edu/datasetview/AJQWW).
+If you want to replace this dataset with your own dataset, see {ref}`dkist:howto-guide:sample-data`.
 
-This gives us a {obj}`dkist.TiledDataset` object, which is an array of {obj}`dkist.Dataset` objects.
+Let's load the data with {obj}`dkist.load_dataset`:
 
 ```{code-cell} ipython3
-ds = dkist.load_dataset(asdf_file)
+ds = dkist.load_dataset(VBI_AJQWW / "VBI_L1_20231016T184519_AJQWW.asdf")
 ds
 ```
 
-To start off, let's just download the first frame of each tile.
+This gives us a {obj}`dkist.TiledDataset` object, which is an array of {obj}`dkist.Dataset` objects, as this VBI dataset is tiled in space (or mosaiced).
 
-```{code-cell} ipython3
-first_tiles = [tile[0] for tile in ds.flat]
-```
+The sample data includes the ASDF file along with the FITS files for the first frame in each mosaic position.
 
-```{code-cell} ipython3
-:tags: [skip-execution]
-
-for i, tile in enumerate(first_tiles):
-    # Wait for only the last download to finish
-    tile.files.download(wait=i == len(first_tiles) - 1)
-```
-
-We can now make a composite plot of all the tiles.
+We can now make a composite plot of all the tiles, at the first timestep.
 
 ```{code-cell} ipython3
 fig = plt.figure(figsize=(12, 12))
-
-for i, tile in enumerate(first_tiles):
-    ax = fig.add_subplot(ds.shape[0], ds.shape[1], i+1, projection=tile.wcs)
-    ax.set_title(f"MINDEX1={tile.headers[0]['MINDEX1']}, MINDEX2={tile.headers[0]['MINDEX2']}")
-    ax.imshow(tile.data)
-
-fig.tight_layout()
+fig = ds.plot(slice_index=0, share_zscale=True)
 ```
 
 ## Regridding with Reproject
@@ -95,17 +67,18 @@ from reproject import reproject_interp
 from ndcube import NDCube
 ```
 
-First, let us crop off the edges of all our tiles to remove some artifacts.
+First, let us crop off the edges of all our tiles to remove some artifacts, and only select the first time step.
+To do this we use the {obj}`.TiledDataset.slice_tiles` helper which applies an array slice to each tile of the {obj}`.TiledDataset` object.
 
 ```{code-cell} ipython3
-first_tiles = [d[0, 100:-100, 100:-100] for d in ds.flat]
+first_tiles = ds.slice_tiles[0, 100:-100, 100:-100]
 ```
 
 Next we need to calculate the optimal WCS for the output:
 
 ```{code-cell} ipython3
 reference_wcs, shape_out = find_optimal_celestial_wcs(
-    [f.wcs for f in first_tiles],
+    [f.wcs for f in first_tiles.flat],
     auto_rotate=True,
     # We drop the output resolution by a factor of 10 to reduce memory
     # remove this line to run at the native resolution of the input data
@@ -121,7 +94,7 @@ Now we can do the actual reprojection
 
 ```{code-cell} ipython3
 arr, footprint = reproject_and_coadd(
-    first_tiles,
+    first_tiles.flat,
     reference_wcs,
     reproject_function=reproject_interp,
     shape_out=shape_out,

docs/howto_guides/index.rst

@@ -1,11 +1,13 @@
 .. _dkist:howto-guides:index:
 
-How-To Guides
+How To Guides
 =============
 
-These How-To Guides will guide you through a specific task.
+These how-to guides provide examples of how to perform specific tasks with the DKIST Python Tools and DKIST data.
+They are recipes that do not provide much in-depth explanation and assume you have some background knowledge.
+If you're starting fresh you might want to check out the :ref:`dkist:tutorial:index` first.
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  reproject_vbi_mosaic
+   sample_data

docs/howto_guides/sample_data.rst

@@ -0,0 +1,4 @@
+.. dkist:howto-guides:sample-data
+
+Downloading the Sample Data with Globus
+=======================================

docs/index.rst

@@ -13,6 +13,7 @@ The `dkist` package is a `SunPy Affiliated Package <https://sunpy.org/affiliated
   self
   installation
   tutorial/index
+  examples/index
   howto_guides/index
   topic_guides/index
   reference
@@ -31,14 +32,14 @@ The `dkist` package is a `SunPy Affiliated Package <https://sunpy.org/affiliated
 
         This tutorial walks you through how to search for, download and load DKIST Level one data.
 
-    .. grid-item-card:: How To Guides
-        :link: dkist:howto-guides:index
+    .. grid-item-card:: Examples
+        :link: dkist:examples:index
         :link-type: ref
         :text-align: center
 
         :octicon:`question;8em;sd-text-secondary`
 
-        Walkthroughs on how to achieve a specific task.
+        Tutorials on how to achieve a specific task.
 
     .. grid-item-card:: Topic Guides
         :link: dkist:topic-guides:index
@@ -50,6 +51,15 @@ The `dkist` package is a `SunPy Affiliated Package <https://sunpy.org/affiliated
         In-depth explanations of concepts and key topics.
         Most useful for answering "why" questions.
 
+    .. grid-item-card:: How-to Guides
+        :link: dkist:howto-guides:index
+        :link-type: ref
+        :text-align: center
+
+        :material-outlined:`school;8em;sd-text-secondary`
+
+        Snippets of code for accomplishing specific tasks.
+
     .. grid-item-card:: Reference
         :link: dkist:api
         :link-type: ref