Update reproject example (#491)

* Allow specifying the figure to `TiledDataset.plot`

* Update the reproject example

* Add howto guide on sample data download

* Fix doc build

* More words

* Much changelog many wow

* Fix ref link

* Apply suggestions from code review

Co-authored-by: Drew Leonard <andy.j.leonard@gmail.com>

---------

Co-authored-by: Drew Leonard <andy.j.leonard@gmail.com>

changelog/491.doc.2.rst

@@ -0,0 +1 @@
+Add a how-to guide on redownloading the sample data with Fido / Globus.

changelog/491.doc.3.rst

@@ -0,0 +1 @@
+Add an examples section for tutorial style self-contained examples.

changelog/491.doc.rst

@@ -0,0 +1 @@
+Update the :ref:`dkist:examples:vbi-reproject` example for improvements in ``TiledDataset``.

changelog/491.feature.rst

@@ -0,0 +1 @@
+Add a ``fig=`` keyword argument to `TiledDataset.plot` and make it default to the current figure.

dkist/dataset/tiled_dataset.py

@@ -167,7 +167,7 @@ def _get_axislabels(ax):
                 ylabel = coord.get_axislabel() or coord._get_default_axislabel()
         return (xlabel, ylabel)
 
-    def plot(self, slice_index, share_zscale=False, **kwargs):
+    def plot(self, slice_index, share_zscale=False, fig=None, **kwargs):
         """
         Plot a slice of each tile in the TiledDataset
 
@@ -181,11 +181,17 @@ def plot(self, slice_index, share_zscale=False, **kwargs):
             Determines whether the color scale of the plots should be calculated
             independently (``False``) or shared across all plots (``True``).
             Defaults to False
+        fig : `matplotlib.figure.Figure`
+            A figure to use for the plot. If not specified the current pyplot
+            figure will be used, or a new one created.
         """
         if isinstance(slice_index, int):
             slice_index = (slice_index,)
         vmin, vmax = np.inf, 0
-        fig = plt.figure()
+
+        if fig is None:
+            fig = plt.gcf()
+
         tiles = self.slice_tiles[slice_index].flat
         for i, tile in enumerate(tiles):
             ax = fig.add_subplot(self.shape[0], self.shape[1], i+1, projection=tile.wcs)

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,13 +5,14 @@ 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
   name: python3
 ---
 
+(dkist:examples:vbi-reproject)=
 # Stitching a VBI Mosaic with `reproject`
 
 ```{note}
@@ -26,64 +27,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 +68,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 +95,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:
+.. _dkist:howto-guide: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,43 @@
+.. _dkist:howto-guide:sample-data:
+
+Downloading the Sample Data with Globus
+=======================================
+
+The Python tools provide a few different partial datasets as sample data, these are used in documentation and examples.
+This how to guide will show you how to download the complete data for these datasets, or let you change the dataset for a different one.
+
+
+Searching for and downloading the ASDF file
+-------------------------------------------
+
+Using the `BKPLX <https://dkist.data.nso.edu/datasetview/BKPLX>`__ dataset from the VISP we download the ASDF file and create a `dkist.Dataset` object.
+
+.. code-block:: python
+
+    from sunpy.net import Fido, attrs as a
+
+    import dkist
+    import dkist.net
+
+    results = Fido.search(a.dkist.Dataset("BKPLX"))
+    asdf_file = Fido.fetch(results)
+
+    ds = dkist.load_dataset(asdf_file)
+
+
+Downloading the FITS files with Globus
+--------------------------------------
+
+Having loaded the ASDF file into a `dkist.Dataset` as this is a VISP dataset with polarimetry, we can download the Stokes I profile by indexing the first element of the first dimension:
+
+.. code-block:: python
+
+    ds[0].files.download()  # doctest: +SKIP
+
+This will download the Stokes I FITS files into the same directory as the ASDF file.
+
+To download the whole dataset do:
+
+.. code-block:: python
+
+    ds.files.download()  # doctest: +SKIP

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-guide: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