From 72ef2b4473cace762af5e970e11b02d42a627563 Mon Sep 17 00:00:00 2001 From: "Brett M. Morris" Date: Mon, 24 Oct 2022 11:47:37 -0400 Subject: [PATCH] cleaning up docstrings, fixing broken internal docs refs --- docs/cubeviz/displayspectra.rst | 4 ++-- docs/cubeviz/import_data.rst | 10 +++++----- docs/mosviz/displayspectra.rst | 2 +- docs/mosviz/import_data.rst | 2 +- docs/mosviz/notebook.rst | 8 ++++---- docs/mosviz/redshift.rst | 4 ++-- docs/specviz/displaying.rst | 14 +++++++------- docs/specviz/export_data.rst | 28 +++++++++++++++++++++------- docs/specviz/import_data.rst | 8 ++++---- docs/specviz/plugins.rst | 4 ++-- docs/specviz2d/plugins.rst | 22 +++++++++++----------- jdaviz/configs/cubeviz/helper.py | 2 +- jdaviz/configs/mosviz/helper.py | 4 ++-- 13 files changed, 63 insertions(+), 49 deletions(-) diff --git a/docs/cubeviz/displayspectra.rst b/docs/cubeviz/displayspectra.rst index 62d8265918..aac94509f5 100644 --- a/docs/cubeviz/displayspectra.rst +++ b/docs/cubeviz/displayspectra.rst @@ -15,5 +15,5 @@ below. Documentation on displaying spectra in a 1D spectrum viewer. There is one important difference when using the API to access Specviz from within Cubeviz. -The functionality of the `~jdaviz.configs.specviz.helper.Specviz` API can be accessed in Cubeviz via -the `jdaviz.configs.cubeviz.helper.Cubeviz.specviz` attribute, e.g. ``cubeviz.specviz.get_spectra()``. +The functionality of the :class:`jdaviz.configs.specviz.helper.Specviz` API can be accessed in Cubeviz via +the :py:meth:`~jdaviz.configs.cubeviz.helper.Cubeviz.specviz` attribute, e.g. ``cubeviz.specviz.get_spectra()``. diff --git a/docs/cubeviz/import_data.rst b/docs/cubeviz/import_data.rst index e0de999c89..8c3ab2d7da 100644 --- a/docs/cubeviz/import_data.rst +++ b/docs/cubeviz/import_data.rst @@ -70,7 +70,7 @@ Importing data via the API Alternatively, users who work in a coding environment like a Jupyter notebook can access the Cubeviz helper class API. Using this API, users can -load data into the application through code with the :meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` +load data into the application through code with the :py:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` method, which takes as input a :class:`~specutils.Spectrum1D` object. FITS Files @@ -88,7 +88,7 @@ Spectrum1D (from file) For cases where the built-in parser is unable to understand your file format, you can try the `~specutils.Spectrum1D` parser directly and then pass the object to the -:meth:`~jdaviz.core.helpers.ConfigHelper.load_data` method:: +:py:meth:`~jdaviz.core.helpers.ConfigHelper.load_data` method:: from specutils import Spectrum1D from jdaviz import Cubeviz @@ -100,7 +100,7 @@ you can try the `~specutils.Spectrum1D` parser directly and then pass the object Spectrum1D (from array) ----------------------- -You can create your own `~specutils.Spectrum1D` object by hand to load into Cubeviz:: +You can create your own :class:`~specutils.Spectrum1D` object by hand to load into Cubeviz:: import numpy as np from astropy import units as u @@ -175,6 +175,6 @@ form ``(region, reason)``:: .. note:: Sky regions are currently unsupported in Cubeviz, unlike Imviz. For more details on the API, please see -:meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions_from_file` -and :meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions` methods +:py:meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions_from_file` +and :py:meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions` methods in Cubeviz. diff --git a/docs/mosviz/displayspectra.rst b/docs/mosviz/displayspectra.rst index b1e1ee6a1a..06655c1a36 100644 --- a/docs/mosviz/displayspectra.rst +++ b/docs/mosviz/displayspectra.rst @@ -11,7 +11,7 @@ with 2d spectra populating the top right viewer, and 1d spectra populating the v Specviz documentation on displaying spectra. The functionality of the Specviz API can be accessed in Mosviz via -the `jdaviz.configs.mosviz.helper.Mosviz.specviz` attribute, e.g., +the :py:meth:`~jdaviz.configs.mosviz.helper.Mosviz.specviz` attribute, e.g., ``mosviz.specviz.get_spectra()``. Pan/Zoom diff --git a/docs/mosviz/import_data.rst b/docs/mosviz/import_data.rst index f3e33c4f57..ffc84ea134 100644 --- a/docs/mosviz/import_data.rst +++ b/docs/mosviz/import_data.rst @@ -59,7 +59,7 @@ If an automatic parser is not provided yet for your data, Mosviz provides manual 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 -by :meth:`~jdaviz.configs.mosviz.helper.Mosviz.load_data`. The association between files is +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). diff --git a/docs/mosviz/notebook.rst b/docs/mosviz/notebook.rst index bed866b262..66e2c11630 100644 --- a/docs/mosviz/notebook.rst +++ b/docs/mosviz/notebook.rst @@ -15,7 +15,7 @@ the following code in a cell of the notebook: After running the code above, you can interact with the Mosviz application from subsequent notebook cells via the API methods attached to the -`~jdaviz.configs.mosviz.helper.Mosviz` object, +:class:`~jdaviz.configs.mosviz.helper.Mosviz` object, for example loading data into the app as described in :ref:`mosviz-import-api`. .. seealso:: @@ -23,8 +23,8 @@ for example loading data into the app as described in :ref:`mosviz-import-api`. :ref:`Cubeviz data export ` Cubeviz documentation on data exporting. -The `~jdaviz.configs.mosviz.helper.Mosviz` helper class can be used similarly to how -`~jdaviz.configs.cubeviz.helper.Cubeviz` is used in :ref:`cubeviz-notebook`. +The :class:`~jdaviz.configs.mosviz.helper.Mosviz` helper class can be used similarly to how +:class:`~jdaviz.configs.cubeviz.helper.Cubeviz` is used in :ref:`cubeviz-notebook`. The viewers in Mosviz that can be used that way are ``image-viewer``, ``spectrum-viewer``, and ``spectrum-2d-viewer``. @@ -40,7 +40,7 @@ If the ``selected`` keyword is set to `True`, only the checked rows in the table will be output. A previous CSV file of the same name can be overwritten by setting the ``overwrite`` keyword to `True`. The contents of ``table-viewer`` can also be extracted to a notebook cell by -running `~jdaviz.configs.mosviz.helper.Mosviz.to_table`: +running :py:meth:`~jdaviz.configs.mosviz.helper.Mosviz.to_table`: .. code-block:: python diff --git a/docs/mosviz/redshift.rst b/docs/mosviz/redshift.rst index db1df42903..dd8987249a 100644 --- a/docs/mosviz/redshift.rst +++ b/docs/mosviz/redshift.rst @@ -14,10 +14,10 @@ From the notebook ================= In the notebook, the value of the Redshift column can be changed for all rows or a single row -using :meth:`~jdaviz.configs.mosviz.helper.Mosviz.update_column`. +using :py:meth:`~jdaviz.configs.mosviz.helper.Mosviz.update_column`. The 1D and 2D spectrum objects can be retrieved (with redshift optionally applied) using -:meth:`~jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_1d` and :meth:`~jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_2d`, +:py:meth:`~jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_1d` and :py:meth:`~jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_2d`, respectively. See the ``notebooks/MosvizNIRISSExample.ipynb`` notebook in the diff --git a/docs/specviz/displaying.rst b/docs/specviz/displaying.rst index eb8c5e9c27..e973532df1 100644 --- a/docs/specviz/displaying.rst +++ b/docs/specviz/displaying.rst @@ -110,8 +110,8 @@ The Specviz helper contains a set of convenience methods to programmatically def Limit methods ^^^^^^^^^^^^^ -You can use the methods :meth:`jdaviz.configs.specviz.helper.Specviz.x_limits` and -:meth:`jdaviz.configs.specviz.helper.Specviz.y_limits` to modify the field of +You can use the methods :py:meth:`~jdaviz.configs.specviz.helper.Specviz.x_limits` and +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.y_limits` to modify the field of view of Specviz. You can provide a scalar (which assumes the units of the loaded spectra), a `~astropy.units.Quantity`, or ``'auto'`` to automatically scale:: @@ -129,14 +129,14 @@ Additionally, you can provide the limit methods with a `~specutils.SpectralRegio Autoscale methods ^^^^^^^^^^^^^^^^^ You can also quickly return to the default zoom using -:meth:`jdaviz.configs.specviz.helper.Specviz.autoscale_x` and -:meth:`jdaviz.configs.specviz.helper.Specviz.autoscale_y`. +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.autoscale_x` and +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.autoscale_y`. Axis Orientation methods ^^^^^^^^^^^^^^^^^^^^^^^^ To quickly flip an axis to change to and from ascending/descending, use -:meth:`jdaviz.configs.specviz.helper.Specviz.flip_x` and -:meth:`jdaviz.configs.specviz.helper.Specviz.flip_y`. +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.flip_x` and +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.flip_y`. .. _spectral-regions: @@ -153,7 +153,7 @@ and the spectral trace in color, coded to subset number and listed under the sub Clicking on that selector, you can add more regions by selecting the "create new" entry. -From the API, you can use the :meth:`~jdaviz.configs.specviz.helper.Specviz.get_spectral_regions` method: +From the API, you can use the :py:meth:`~jdaviz.configs.specviz.helper.Specviz.get_spectral_regions` method: .. image:: img/spectral_region_5.png diff --git a/docs/specviz/export_data.rst b/docs/specviz/export_data.rst index 062f05a4a8..cc080b356e 100644 --- a/docs/specviz/export_data.rst +++ b/docs/specviz/export_data.rst @@ -19,11 +19,15 @@ the API described in :ref:`specviz-import-api`. Alternatively, if you want more control over Specviz, you can access it the via the lower-level application interface that connects to the ``glue-jupyter`` application level. This is accessed via the ``.app`` attribute of the -`~jdaviz.configs.specviz.helper.Specviz` helper class. For example:: +:py:class:`~jdaviz.configs.specviz.helper.Specviz` helper class. For example: + +.. code-block:: python specviz.app.get_data_from_viewer('spectrum-viewer') -To extract a specific spectral subset:: +To extract a specific spectral subset: + +.. code-block:: python specviz.app.get_data_from_viewer('spectrum-viewer', 'Subset 1') @@ -41,12 +45,16 @@ Spectral Regions If you have spectral region subsets, you can extract the parameters of these subsets as a `specutils spectral region `_. -For a list of available spectral regions to extract, you can type:: +For a list of available spectral regions to extract, you can type: + +.. code-block:: python regions = specviz.get_spectral_regions() regions -To extract the spectral region you want:: +To extract the spectral region you want: + +.. code-block:: python myregion = regions["Subset 2"] @@ -55,16 +63,22 @@ To extract the spectral region you want:: Model Fits ========== -For a list of model labels:: +For a list of model labels: + +.. code-block:: python models = specviz.get_models() models -Once you know the model labels, to get a specific model:: +Once you know the model labels, to get a specific model: + +.. code-block:: python mymodel = specviz.get_models(model_label="ModelLabel") -To extract all of the model parameters:: +To extract all of the model parameters: + +.. code-block:: python myparams = specviz.get_model_parameters(model_label="ModelLabel") myparams diff --git a/docs/specviz/import_data.rst b/docs/specviz/import_data.rst index 68733d604a..89fb566347 100644 --- a/docs/specviz/import_data.rst +++ b/docs/specviz/import_data.rst @@ -49,7 +49,7 @@ Importing data via the API Alternatively, users who work in a coding environment like a Jupyter notebook can access the Specviz helper class API. Using this API, users can load data into the application through code with the -:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` method, which takes as input a :class:`~specutils.Spectrum1D` object. FITS Files @@ -66,7 +66,7 @@ The example below loads a FITS file into Specviz: specviz.show() You can also pass the path to a file that `~specutils.Spectrum1D` understands directly to the -:meth:`jdaviz.configs.specviz.helper.Specviz.load_spectrum` method:: +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` method:: specviz.load_spectrum("path/to/data/file") @@ -118,7 +118,7 @@ is separated from the ``jwst`` pipeline package. Importing a SpectrumList ------------------------ -The :meth:`jdaviz.configs.specviz.helper.Specviz.load_spectrum` also accepts +The :py:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` also accepts a `~specutils.SpectrumList` object, in which case it will both load the individual `~specutils.Spectrum1D` objects in the list and additionally attempt to stitch together the spectra into a single data object so that @@ -141,7 +141,7 @@ end of the red region in the screenshot below: .. image:: img/spectrumlist_combined.png This functionality is also available in limited instances by providing a directory path -to the :meth:`jdaviz.configs.specviz.helper.Specviz.load_spectrum` method. Note +to the :py:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum` method. Note that the ``read`` method of :class:`~specutils.SpectrumList` is only set up to handle directory input in limited cases, for example JWST MIRI MRS data, and will throw an error in other cases. In cases that it does work, only files in the directory level specified diff --git a/docs/specviz/plugins.rst b/docs/specviz/plugins.rst index 91ffaf1e67..eeee469334 100644 --- a/docs/specviz/plugins.rst +++ b/docs/specviz/plugins.rst @@ -198,7 +198,7 @@ From the API ^^^^^^^^^^^^ The range and step size of the slider can be set from a notebook cell using the -:meth:`~jdaviz.configs.default.plugins.line_lists.line_list_mixin.LineListMixin.set_redshift_slider_bounds` +:py:meth:`~jdaviz.configs.default.plugins.line_lists.line_list_mixin.LineListMixin.set_redshift_slider_bounds` method in Specviz by specifying the ``range`` or ``step`` keywords, respectively. Setting either keyword to ``'auto'`` means its value will be calculated automatically based on the x-limits of the spectrum plot. @@ -206,7 +206,7 @@ automatically based on the x-limits of the spectrum plot. The redshift itself can be set from the notebook using the ``set_redshift`` method. Any set redshift values are applied to spectra output using the -:meth:`jdaviz.configs.specviz.helper.Specviz.get_spectra` helper method. +:py:meth:`~jdaviz.configs.specviz.helper.Specviz.get_spectra` helper method. Note that using the lower-level app data retrieval (e.g., ``specviz.app.get_data_from_viewer()``) will return the data as originally loaded, with the redshift unchanged. diff --git a/docs/specviz2d/plugins.rst b/docs/specviz2d/plugins.rst index 68e60e28c4..688b17c6d3 100644 --- a/docs/specviz2d/plugins.rst +++ b/docs/specviz2d/plugins.rst @@ -69,7 +69,7 @@ adjust plotting options), open the "Export Trace" panel, choose a label for the and click "Create". Note that this step is not required to create an extraction with simple workflows. -Trace objects created outside of jdaviz can be loaded into the app via :meth:`~jdaviz.configs.specviz2d.helper.Specviz2d.load_trace`: +Trace objects created outside of jdaviz can be loaded into the app via :py:meth:`~jdaviz.configs.specviz2d.helper.Specviz2d.load_trace`: viz.load_trace(my_trace, data_label="my trace") @@ -79,11 +79,11 @@ Once trace objects are loaded into the app, they can be offset (in the cross-dis by selecting the trace label, entering an offset, and overwriting the existing data entry (or creating a new one) with the modified trace. -To export and access the specreduce Trace object defined in the plugin, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_trace`:: +To export and access the specreduce Trace object defined in the plugin, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_trace`:: trace = sp_ext.export_trace() -To import the parameters from a specreduce Trace object, whether it's new or was exported and modified in the notebook, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_trace`:: +To import the parameters from a specreduce Trace object, whether it's new or was exported and modified in the notebook, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_trace`:: sp_ext.import_trace(trace) @@ -107,16 +107,16 @@ menu in the 2D spectrum viewer, and can be :ref:`exported into the notebook via To refine the trace based on the background-subtracted image, return to the Trace step and select the exported background-subtracted image as input. -To export and access the specreduce Background object defined in the plugin, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg`:: +To export and access the specreduce Background object defined in the plugin, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg`:: bg = sp_ext.export_bg() To access the background image, background spectrum, or background-subtracted image as a :class:`~specutils.Spectrum1D` object, -call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_img`, -:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_spectrum`, -or :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_sub`, respectively. +call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_img`, +:py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_spectrum`, +or :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_bg_sub`, respectively. -To import the parameters from a specreduce Background object into the plugin, whether it's new or was exported and modified in the notebook, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_bg`:: +To import the parameters from a specreduce Background object into the plugin, whether it's new or was exported and modified in the notebook, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_bg`:: sp_ext.import_bg(bg) @@ -140,13 +140,13 @@ To visualize or export the resulting 2D spectrum, provide a data label and click resulting spectrum object can be :ref:`accessed from the API ` in the same way as any other data product in the spectrum viewer. -To export and access the specreduce extraction object defined in the plugin, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_extract`:: +To export and access the specreduce extraction object defined in the plugin, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_extract`:: ext = sp_ext.export_extract() -To access the extracted spectrum as a :class:`~specutils.Spectrum1D` object, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_extract_spectrum`. +To access the extracted spectrum as a :class:`~specutils.Spectrum1D` object, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.export_extract_spectrum`. -To import the parameters from a specreduce extraction object (either a new object, or an exported one modified in the notebook) into the plugin, call :meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_extract`:: +To import the parameters from a specreduce extraction object (either a new object, or an exported one modified in the notebook) into the plugin, call :py:meth:`~jdaviz.configs.specviz2d.plugins.spectral_extraction.spectral_extraction.SpectralExtraction.import_extract`:: sp_ext.import_extract(ext) diff --git a/jdaviz/configs/cubeviz/helper.py b/jdaviz/configs/cubeviz/helper.py index c9654ae41e..2c731bf823 100644 --- a/jdaviz/configs/cubeviz/helper.py +++ b/jdaviz/configs/cubeviz/helper.py @@ -98,7 +98,7 @@ def select_wavelength(self, wavelength): @property def specviz(self): """ - A Specviz helper (`~jdaviz.configs.specviz.helper.Specviz`) for the Jdaviz + A Specviz helper (:class:`~jdaviz.configs.specviz.helper.Specviz`) for the Jdaviz application that is wrapped by Cubeviz. """ if not hasattr(self, '_specviz'): diff --git a/jdaviz/configs/mosviz/helper.py b/jdaviz/configs/mosviz/helper.py index 4116349a87..90ad21c978 100644 --- a/jdaviz/configs/mosviz/helper.py +++ b/jdaviz/configs/mosviz/helper.py @@ -907,7 +907,7 @@ def to_csv(self, filename="MOS_data.csv", selected=False, overwrite=False): @property def specviz(self): """ - A Specviz helper (`~jdaviz.configs.specviz.helper.Specviz`) for the Jdaviz + A Specviz helper (:class:`~jdaviz.configs.specviz.helper.Specviz`) for the Jdaviz application that is wrapped by Mosviz. """ if not hasattr(self, '_specviz'): @@ -917,7 +917,7 @@ def specviz(self): @property def specviz2d(self): """ - A specviz2d helper (`~jdaviz.configs.specviz2d.helper.Specviz2d`) for the Jdaviz + A specviz2d helper (:class:`~jdaviz.configs.specviz2d.helper.Specviz2d`) for the Jdaviz application that is wrapped by mosviz """ if not hasattr(self, '_specviz2d'):