Add docs page to explain how to create jdaviz-readable products (#2228)

* Add page for data products

* Update index

* Fix title

* Capital letters

* Address first review comments

* Edit format

* Apply suggestions from code review

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

* Including reference in import_data

* Update docs/create_products.rst

* Update docs/create_products.rst

---------

Co-authored-by: Camilla Pacifici <cpacifici@stsci.edu>
Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>
Co-authored-by: Ricky O'Steen <39831871+rosteen@users.noreply.github.com>

docs/create_products.rst

@@ -0,0 +1,71 @@
+.. _create_products:
+
+Creating Jdaviz-readable Products
+=================================
+
+Spectroscopic data products (1D, 2D, and 3D) can be loaded
+in the different ``jdaviz`` configurations using
+essentially two methods, i.e., loading :class:`~specutils.Spectrum1D` objects or
+from FITS files. Here, we list a few ways in which data can be packaged to be easily loaded
+into a ``jdaviz`` configuration.
+
+Data in a database
+------------------
+
+If the data are stored in a database, we recommend storing a :class:`~specutils.Spectrum1D` object
+per entry. This would allow the user to query the data and visualize it in
+``jdaviz`` with few lines of code; also see :ref:`create_product_spectrum1d_obj`.
+
+Data in FITS files
+------------------
+
+If the data are stored as FITS files, we propose three options:
+
+* :ref:`create_product_specutils_loader`
+* :ref:`create_product_dedicated_loader`
+* :ref:`create_product_spectrum1d_obj`
+
+.. _create_product_specutils_loader:
+
+Using an available specutils loader
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Available loaders can be listed with the following commands:
+
+.. code-block:: python
+
+    from specutils import Spectrum1D
+    Spectrum1D.read.list_formats()
+
+The majority are fairly specific to missions and instruments. Four formats
+are more generic and adaptable: ``ASCII``, ``ECSV``, ``tabular-fits``, and
+``wcs1d-fits``. More information on how to create files that are readable by
+these loaders can be found on the `specutils GitHub repository
+<https://github.com/astropy/specutils/tree/main/specutils/io/default_loaders>`_.
+
+.. _create_product_dedicated_loader:
+
+Creating a dedicated loader
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `specutils documentation on how to create a custom loader
+<https://specutils.readthedocs.io/en/stable/custom_loading.html#creating-a-custom-loader>`_
+is available. We are working on the necessary documentation to prompt
+``jdaviz`` to recognize a custom loader developed in ``specutils``.
+
+.. _create_product_spectrum1d_obj:
+
+Providing scripts to load the data as Spectrum1D objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If none of the above is an acceptable option, the user can create the data
+products with their custom format and provide scripts or Jupyter Notebooks
+that show how to read the products and create :class:`~specutils.Spectrum1D` objects
+that can be read into ``jdaviz``. More about
+how to create :class:`~specutils.Spectrum1D` objects for the 1D, 2D, and 3D cases can be
+found in the corresponding "Importing data" sections of the various configurations:
+
+* :ref:`specviz-import-data`
+* :ref:`cubeviz-import-data`
+* :ref:`specviz2d-import-data`
+* :ref:`mosviz-import-api`

docs/cubeviz/import_data.rst

@@ -10,6 +10,7 @@ now supports 3D cubes and allows the Python-level interface and parsing tools to
 be defined in ``specutils`` instead of being duplicated in Jdaviz.
 :class:`~specutils.Spectrum1D` objects are very flexible in their capabilities, however,
 and hence should address most astronomical spectrum use cases.
+If you are creating your own data products, please read the page :ref:`create_products`.
 
 Cubeviz will automatically parse the data into the multiple viewers as described in
 :ref:`cubeviz-display-cubes`. For the best experience, data loaded into Cubeviz should contain valid WCS

docs/index.rst

@@ -192,6 +192,7 @@ Using Jdaviz
   save_state.rst
   display.rst
   sample_notebooks.rst
+  create_products.rst
 
 Reference/API
 =============

docs/mosviz/import_data.rst

@@ -100,7 +100,9 @@ Manual Loading
 If an automatic parser is not provided yet for your data, Mosviz provides manual loading by
 specifying which files are which, and the associations between them. This is done by
 generating three lists containing the filenames for the 1D spectra,
-2D spectra, and images in your dataset. These three lists are taken as arguments
+2D spectra, and images in your dataset (if you are creating your own data products,
+please read the page :ref:`create_products`). 
+These three lists are taken as arguments
 by :py:meth:`~jdaviz.configs.mosviz.helper.Mosviz.load_data`. The association between files is
 assumed to be the order of each list (e.g., the first object consists of the first filename
 specified in each list, the second target is the second in each list, and so forth).

docs/specviz/import_data.rst

@@ -9,6 +9,7 @@ as that allows the Python-level interface and parsing tools to be defined in ``s
 instead of being duplicated in Jdaviz.
 :class:`~specutils.Spectrum1D` objects are very flexible in their capabilities, however,
 and hence should address most astronomical spectrum use cases.
+If you are creating your own data products, please read the page :ref:`create_products`.
 
 .. seealso::
 

docs/specviz2d/import_data.rst

@@ -9,6 +9,7 @@ as that allows the Python-level interface and parsing tools to be defined in ``s
 instead of being duplicated in Jdaviz.
 :class:`~specutils.Spectrum1D` objects are very flexible in their capabilities, however,
 and hence should address most astronomical spectrum use cases.
+If you are creating your own data products, please read the page :ref:`create_products`.
 
 .. seealso::
 
@@ -56,7 +57,7 @@ notebook can access the Specviz2D helper class API. Using this API, users can
 load data into the application through code with the
 :meth:`~jdaviz.configs.specviz2d.helper.Specviz2d.load_data`
 method, which takes as input a :class:`~specutils.Spectrum1D` object or filename for the
-2D spectrum and (optionally) the 1D spectrum. 
+2D spectrum and (optionally) the 1D spectrum.
 
 By default, extension 1 of the 2D
 file is loaded, but you can specify another extension by providing an integer
@@ -66,4 +67,4 @@ the spectrum to be horizontal:
 
 .. code-block:: python
 
-    specviz2d.load_data(fn, ext=7, transpose=True)
+    specviz2d.load_data(fn, ext=7, transpose=True)