From d4369bd09ebaeb8488d4adbfb1c666b047404a19 Mon Sep 17 00:00:00 2001 From: Pey Lian Lim <2090236+pllim@users.noreply.github.com> Date: Thu, 26 Aug 2021 12:09:15 -0400 Subject: [PATCH 1/3] DOC: Enable nitpicky [ci skip] --- docs/conf.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index b2c2589758..10e5c16af4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,7 +28,7 @@ import os import sys import datetime -from pkg_resources import get_distribution +import importlib.metadata as importlib_metadata try: from sphinx_astropy.conf.v1 import * # noqa @@ -76,10 +76,8 @@ # |version| and |release|, also used in various other places throughout the # built documents. -package = get_distribution(project) - # The full version, including alpha/beta/rc tags. -release = package.version +release = importlib_metadata.version(project) # The short X.Y version. version = '.'.join(release.split('.')[:2]) @@ -160,10 +158,11 @@ github_issues_url = 'https://github.com/{0}/issues/'.format(setup_cfg['github_project']) # -- Turn on nitpicky mode for sphinx (to warn about references not found) ---- -# -# nitpicky = True -# nitpick_ignore = [] -# +nitpicky = True + +# Do not populate this if you use nitpick-exceptions below. +nitpick_ignore = [] + # Some warnings are impossible to suppress, and you can list specific references # that should be ignored in a nitpick-exceptions file which should be inside # the docs/ directory. The format of the file should be: @@ -183,6 +182,7 @@ # continue # dtype, target = line.split(None, 1) # target = target.strip() -# nitpick_ignore.append((dtype, six.u(target))) +# nitpick_ignore.append((dtype, target)) +# Extra intersphinx in addition to what is already in sphinx-astropy intersphinx_mapping['glue'] = ('http://docs.glueviz.org/en/stable/', None) From 14e295f792119e179c978c400e9d97020e5b3f88 Mon Sep 17 00:00:00 2001 From: Pey Lian Lim <2090236+pllim@users.noreply.github.com> Date: Tue, 14 Sep 2021 13:18:09 -0400 Subject: [PATCH 2/3] Fix doc nitpicky warnings --- docs/conf.py | 15 +++++--- docs/cubeviz/displaycubes.rst | 24 ++++++------ docs/cubeviz/displayspectra.rst | 4 +- docs/cubeviz/import_data.rst | 6 +-- docs/cubeviz/notebook.rst | 14 ++++--- docs/cubeviz/plugins.rst | 21 +++++----- docs/imviz/index.rst | 2 +- docs/imviz/notebook.rst | 6 +++ docs/known_bugs.rst | 8 ++-- docs/mosviz/displayspectra.rst | 5 ++- docs/mosviz/import_data.rst | 22 ++++++----- docs/mosviz/notebook.rst | 27 ++++++------- docs/mosviz/plugins.rst | 6 +-- docs/nitpick-exceptions | 5 +++ docs/notebook/export_data.rst | 8 ++-- docs/notebook/import_data.rst | 38 +++++++++++-------- docs/quickstart.rst | 6 +-- docs/reference/api.rst | 20 +++++++++- docs/specviz/displaying.rst | 21 ++++++---- docs/specviz/import_data.rst | 12 +++--- docs/specviz/index.rst | 2 +- docs/specviz/plugins.rst | 16 +++++--- docs/specviz/redshift.rst | 13 ++++--- jdaviz/app.py | 32 +++++----------- .../unit_conversion/unit_conversion.py | 16 ++++---- jdaviz/configs/specviz/plugins/viewers.py | 13 ++++--- jdaviz/core/helpers.py | 19 ++++++---- jdaviz/core/registries.py | 5 ++- jdaviz/core/template_mixin.py | 6 +-- 29 files changed, 221 insertions(+), 171 deletions(-) create mode 100644 docs/nitpick-exceptions diff --git a/docs/conf.py b/docs/conf.py index 10e5c16af4..5539a28490 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -177,12 +177,15 @@ # # Uncomment the following lines to enable the exceptions: # -# for line in open('nitpick-exceptions'): -# if line.strip() == "" or line.startswith("#"): -# continue -# dtype, target = line.split(None, 1) -# target = target.strip() -# nitpick_ignore.append((dtype, target)) +for line in open('nitpick-exceptions'): + if line.strip() == "" or line.startswith("#"): + continue + dtype, target = line.split(None, 1) + target = target.strip() + nitpick_ignore.append((dtype, target)) # Extra intersphinx in addition to what is already in sphinx-astropy intersphinx_mapping['glue'] = ('http://docs.glueviz.org/en/stable/', None) +intersphinx_mapping['glue_jupyter'] = ('https://glue-jupyter.readthedocs.io/en/stable/', None) +intersphinx_mapping['specutils'] = ('https://specutils.readthedocs.io/en/stable/', None) +intersphinx_mapping['spectral_cube'] = ('https://spectral-cube.readthedocs.io/en/stable/', None) diff --git a/docs/cubeviz/displaycubes.rst b/docs/cubeviz/displaycubes.rst index 708b5effa4..63a450006f 100644 --- a/docs/cubeviz/displaycubes.rst +++ b/docs/cubeviz/displaycubes.rst @@ -14,11 +14,11 @@ function. The indicators that the load machinery looks for in each HDU to populate the viewers are below (note that in all cases, header values are converted to lower case): - - Flux viewer: `hdu.name` is in the set `['flux', 'sci']` - - Uncertainty viewer: `hdu.header.keys()` includes "errtype" or `hdu.name` - is in the set `['ivar', 'err', 'var', 'uncert']` - - Mask viewer: `hdu.data.dtype` is `np.int`, `np.uint` or `np.uint32`, or - `hdu.name` is in the set `['mask', 'dq']` + - Flux viewer: ``hdu.name`` is in the set ``['flux', 'sci']`` + - Uncertainty viewer: ``hdu.header.keys()`` includes "errtype" or ``hdu.name`` + is in the set ``['ivar', 'err', 'var', 'uncert']`` + - Mask viewer: ``hdu.data.dtype`` is `int`, `numpy.uint` or `numpy.uint32`, or + ``hdu.name`` is in the set ``['mask', 'dq']`` If any viewer fails to populate automatically, or if displaying different data is desired, the user can manually select data for each viewer @@ -72,12 +72,14 @@ and the resulting spectrum will be displayed in the 1d spectrum viewer at the bo There are other options available for region of interest. At the top of the User Interface, there is a section that says either "+ No selection (create new)" or "Subset n" where n is an integer that tells you which Subset is currently selected. To the right of this area, are red circles that allow -you to change the method of region selection. The options are `replace`, `add`, `and`, `xor`, and `remove`. -`replace` will remove the previously created selection and place the newly created subset. -`add` allows you to create another subset that extends the existing subset. -`and` only leaves behind the overlapping region between the existing subset and any additional subsets. -`xor` only leaves behind the non-overlapping region between the existing subset and any additional subsets. -`remove` will de-select any parts of the existing subset that overlaps with any additional subsets. +you to change the method of region selection. The options are: + +* ``replace``: will remove the previously created selection and place the newly created subset. +* ``add``: allows you to create another subset that extends the existing subset. +* ``and``: only leaves behind the overlapping region between the existing subset and any additional subsets. +* ``xor``: only leaves behind the non-overlapping region between the existing subset and any additional subsets. +* ``remove``: will de-select any parts of the existing subset that overlaps with any additional subsets. + You can use these options to further adjust the region of interest and adapt it to your use case. .. seealso:: diff --git a/docs/cubeviz/displayspectra.rst b/docs/cubeviz/displayspectra.rst index 903156a2dd..0c23bbec78 100644 --- a/docs/cubeviz/displayspectra.rst +++ b/docs/cubeviz/displayspectra.rst @@ -14,5 +14,5 @@ below. `Displaying Spectra (Specviz) `_ Documentation on displaying spectra in a 1D spectrum viewer. -The functionality of the `Specviz` API can be accessed in Cubeviz via -the `specviz` attribute of the `Cubeviz` class, e.g. `cubeviz.specviz.get_spectra()`. +The functionality of the `~jdaviz.configs.specviz.Specviz` API can be accessed in Cubeviz via +the `jdaviz.configs.cubeviz.Cubeviz.specviz` attribute, e.g. ``cubeviz.specviz.get_spectra()``. diff --git a/docs/cubeviz/import_data.rst b/docs/cubeviz/import_data.rst index a9e3cf7ab7..f759fc05b0 100644 --- a/docs/cubeviz/import_data.rst +++ b/docs/cubeviz/import_data.rst @@ -36,11 +36,11 @@ Importing data via the API Alternatively, if you are working in a coding environment like a Jupyter notebook, you have access to the Cubeviz helper class API. Using this API, -you can load data into the application through code using the `load_data` +you can load data into the application through code using the +:meth:`~jdaviz.core.helpers.ConfigHelper.load_data` method, which takes as input either the name of a local file or a :class:`~spectral_cube.SpectralCube` or :class:`~specutils.Spectrum1D` object. >>> from jdaviz import Cubeviz >>> cubeviz = Cubeviz() - >>> cubeviz.load_data("/Users/demouser/data/cube_file.fits") #doctest: +SKIP - + >>> cubeviz.load_data("/Users/demouser/data/cube_file.fits") # doctest: +SKIP diff --git a/docs/cubeviz/notebook.rst b/docs/cubeviz/notebook.rst index cd91671409..71c8cef7b3 100644 --- a/docs/cubeviz/notebook.rst +++ b/docs/cubeviz/notebook.rst @@ -9,10 +9,11 @@ the following code in a cell of the notebook:: >>> from jdaviz import Cubeviz >>> cubeviz = Cubeviz() - >>> cubeviz.app #doctest: +SKIP + >>> cubeviz.app # doctest: +SKIP After running the code above, you can interact with the Cubeviz application from -subsequent notebook cells via the API methods attached to the `cubeviz` object, +subsequent notebook cells via the API methods attached to the +`~jdaviz.configs.cubeviz.helper.Cubeviz` object, for example loading data into the app as described in :ref:`cubeviz-import-data`. Data can also be accessed via the lower-level application interface that @@ -23,8 +24,8 @@ attribute of the `~jdaviz.configs.cubeviz.helper.Cubeviz` helper class. For exam cubeviz.app.get_data_from_viewer('flux-viewer') This code can be used to access data from the different viewers, which is returned as a dictionary. -The viewer options in the `cubeviz` configuration are `spectrum-viewer`, `flux-viewer`, -`uncert-viewer`, and `mask-viewer`. +The viewer options in the Cubeviz configuration are ``spectrum-viewer``, ``flux-viewer``, +``uncert-viewer``, and ``mask-viewer``. Using the appropriate data label, the data in its native type can be returned from this dictionary like so:: @@ -35,6 +36,7 @@ Data can also be accessed directly from ``data_collection`` using the following cubeviz.app.data_collection[0] -Which is returned as a `~glue.core.data.Data` object. The `data_collection` object -can be indexed to return all available data (i.e. not just using `0` like in the +Which is returned as a `~glue.core.data.Data` object. The +`~glue.core.data_collection.DataCollection` object +can be indexed to return all available data (i.e., not just using 0 like in the previous example). diff --git a/docs/cubeviz/plugins.rst b/docs/cubeviz/plugins.rst index fa94f740dd..ddb398c9e2 100644 --- a/docs/cubeviz/plugins.rst +++ b/docs/cubeviz/plugins.rst @@ -67,20 +67,21 @@ also saved to a dataset with the label specified in the :guilabel:`Model Label` `Model Fitting `_ Specviz documentation on fitting spectral models. -As mentioned in the `specviz` documentation on model fitting, models can be accessed -in a jupyter notebook by using the following code:: +As mentioned in the :ref:`specviz-model-fitting` section for Specviz, models can be accessed +in a Jupyter notebook by using the following code:: cubeviz.get_models(model_label="Model", x=10) -Where the `model_label` parameter identifies which model should be returned and the `x` and -`y` parameters identify specifically which spaxel fits are to be returned, for models -applied to every spaxel using the :guilabel:`Apply to Cube` button. Leaving `x` or -`y` as `None` will mean that the models fit to every spaxel across that axis will be +Where the ``model_label`` keyword identifies which model should be returned and the ``x`` and +``y`` keywords identify specifically which spaxel fits are to be returned, for models +applied to every spaxel using the :guilabel:`Apply to Cube` button. Leaving ``x`` or +``y`` as `None` will mean that the models fit to every spaxel across that axis will be returned. Model parameters can also be accessed using the following code:: cubeviz.get_model_parameters(model_label="Model", y=52) -With the parameters following the same pattern as the `get_models()` method. +With the parameters following the same pattern as the +:meth:`~jdaviz.core.helpers.ConfigHelper.get_models` method. Contours ======== @@ -135,7 +136,7 @@ Line Analysis .. _moment-maps: Moment Maps -============= +=========== .. image:: ../img/moment1_map.png @@ -147,7 +148,7 @@ a moment map. The order of the moment map (0, 1, 2, ...) indicates the power-law index to which the spectral axis is raised. A 'moment 0' map gives the integrated flux over a spectral region. Similarly, 'moment 1' is the flux-weighted centroid (e.g. line center) and a 'moment 2' -is the dispersion (e.g. wavelength or velocity dispersion) +is the dispersion (e.g., wavelength or velocity dispersion) along the spectral axis. Moments 3 and 4 are less commonly utilized, but correspond to the skewness and kurtosis of a spectral feature. @@ -174,7 +175,7 @@ converted to velocity units before running the plugin if those units are desired for the output moment maps. Line or Continuum Maps -=================================== +====================== .. image:: ../img/moment0_line_map.png diff --git a/docs/imviz/index.rst b/docs/imviz/index.rst index 304e02157b..dc8422e8f3 100644 --- a/docs/imviz/index.rst +++ b/docs/imviz/index.rst @@ -8,7 +8,7 @@ Imviz ##### Imviz is a tool for visualization and quick-look analysis for 2D astronomical -images. Like the rest of `jdaviz`, it is written in the Python programming +images. Like the rest of Jdaviz, it is written in the Python programming language, and therefore can be run anywhere Python is supported (see :doc:`../installation`). Imviz is built on top of the `Glupyter `_ backend, providing a visual, diff --git a/docs/imviz/notebook.rst b/docs/imviz/notebook.rst index 1c9ffda363..085a41c904 100644 --- a/docs/imviz/notebook.rst +++ b/docs/imviz/notebook.rst @@ -10,3 +10,9 @@ To run Imviz in a notebook:: imviz = Imviz() imviz.app +Imviz also provides programmatic access to its viewers using +`Astrowidgets `_ API. +For example:: + + viewer = imviz.get_viewer('viewer-1') + viewer.center_on((100, 100)) diff --git a/docs/known_bugs.rst b/docs/known_bugs.rst index 52603d3147..c72350ca26 100644 --- a/docs/known_bugs.rst +++ b/docs/known_bugs.rst @@ -26,10 +26,10 @@ This can be fixed by reinstalling scikit-image:: pip uninstall scikit-image conda install scikit-image -The reason for this issue is that prebuilt binaries for `scikit-image` don't +The reason for this issue is that prebuilt binaries for scikit-image don't work on Mac versions of 10.13 or older and conda installs an older version of scikit-image that works with those versions. -Another way to get the up-to-date `scikit-image` version is:: +Another way to get the up-to-date scikit-image version is:: pip install -U --no-binary scikit-image scikit-image. @@ -39,8 +39,8 @@ first solution. On some platforms, install fails due to vispy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The 0.6.4 version of `vispy` fails to build for some combinations of -platform/OS and Python versions. `vispy` 0.6.5 has resolved this, but a +The 0.6.4 version of vispy fails to build for some combinations of +platform/OS and Python versions. vispy 0.6.5 has resolved this, but a workaround if you have an older version of vispy is to ensure you have a compatible version:: diff --git a/docs/mosviz/displayspectra.rst b/docs/mosviz/displayspectra.rst index aa336c7901..a8a3c7b8f1 100644 --- a/docs/mosviz/displayspectra.rst +++ b/docs/mosviz/displayspectra.rst @@ -10,8 +10,9 @@ with 2d spectra populating the top right viewer, and 1d spectra populating the v `Display Spectra `_ Specviz documentation on displaying spectra. -The functionality of the `Specviz` API can be accessed in Moseviz via -the `specviz` attribute of the `Mosviz` class, e.g. `mosviz.specviz.get_spectra()`.` +The functionality of the Specviz API can be accessed in Mosviz via +the `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 d67c064dca..b19f67a834 100644 --- a/docs/mosviz/import_data.rst +++ b/docs/mosviz/import_data.rst @@ -8,23 +8,25 @@ Currently, data must be imported into Mosviz using the API in the Jupyter notebo After initializing the app as explained in :ref:`mosviz-notebook`, you must generate three lists containing the filenames for the 1D spectra, 2D spectra, and images in your dataset. These three lists are taken as arguments -to the Mosviz `load_data` method. An example is given below, where `file_dir` is a +to the :meth:`~jdaviz.configs.mosviz.helper.Mosviz.load_data` method. +An example is given below, where ``file_dir`` is a directory that contains all the files for the dataset to be loaded:: + >>> import glob >>> from jdaviz import Mosviz >>> mosviz = Mosviz() - >>> mosviz.app #doctest: +SKIP + >>> mosviz.app # doctest: +SKIP >>> spectra_1d = [] >>> spectra_2d = [] >>> images = [] - >>> for filename in glob("{}/*".format(file_dir)): #doctest: +SKIP - >>> if "x1d" in filename: #doctest: +SKIP - >>> spectra_1d.append(filename) #doctest: +SKIP - >>> elif "s2d" in filename: #doctest: +SKIP - >>> spectra_2d.append(filename) #doctest: +SKIP - >>> elif "fits" in filename: #doctest: +SKIP - >>> images.append(filename) #doctest: +SKIP - >>> mosviz.load_data(spectra_1d, spectra_2d, images) #doctest: +SKIP + >>> for filename in glob.iglob(f"{file_dir}/*"): # doctest: +SKIP + >>> if "x1d" in filename: # doctest: +SKIP + >>> spectra_1d.append(filename) # doctest: +SKIP + >>> elif "s2d" in filename: # doctest: +SKIP + >>> spectra_2d.append(filename) # doctest: +SKIP + >>> elif "fits" in filename: # doctest: +SKIP + >>> images.append(filename) # doctest: +SKIP + >>> mosviz.load_data(spectra_1d, spectra_2d, images) # doctest: +SKIP This example assumes that all 1D spectra have "x1d" in the filename, all 2D spectra have "s2d" in the filename, and any other FITS files in the directory are the diff --git a/docs/mosviz/notebook.rst b/docs/mosviz/notebook.rst index 94300d4694..3777db3033 100644 --- a/docs/mosviz/notebook.rst +++ b/docs/mosviz/notebook.rst @@ -9,10 +9,11 @@ the following code in a cell of the notebook:: >>> from jdaviz import Mosviz >>> mosviz = Mosviz() - >>> mosviz.app #doctest: +SKIP + >>> mosviz.app # doctest: +SKIP After running the code above, you can interact with the Mosviz application from -subsequent notebook cells via the API methods attached to the `mosviz` object, +subsequent notebook cells via the API methods attached to the +`~jdaviz.configs.mosviz.helper.Mosviz` object, for example loading data into the app as described in :ref:`mosviz-import-data`. .. seealso:: @@ -21,20 +22,20 @@ for example loading data into the app as described in :ref:`mosviz-import-data`. Cubeviz documentation on data exporting. The `~jdaviz.configs.mosviz.helper.Mosviz` helper class can be used similarly to how -`cubeviz` is used in the previous link. -The viewers in `mosviz` that can be used that way are `image-viewer`, `spectrum-viewer`, -and `spectrum-2d-viewer`. +`~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``. -It is also possible to extract the contents of the table viewer via:: +It is also possible to extract the contents of the table viewer using +`~jdaviz.configs.mosviz.helper.Mosviz.to_csv`:: mosviz.to_csv(filename="MOS_data.csv", selected=False) -Which will save the data from the `mosviz` table into a csv file named -`filename`. If the `selected` parameter 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` parameter to `True`. -The contents of `table-viewer` can also be extracted to a notebook cell by -running the following:: +Which will save the data from the Mosviz table into the given CSV filename. +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`:: mosviz.to_table() - diff --git a/docs/mosviz/plugins.rst b/docs/mosviz/plugins.rst index 7337a1a980..65df7ff373 100644 --- a/docs/mosviz/plugins.rst +++ b/docs/mosviz/plugins.rst @@ -67,6 +67,6 @@ A slit can be added to the image viewer by opening the Slit Overlay plugin and c The :guilabel:`Remove` button can be used to remove a slit once it has been applied to the image viewer. In order to plot a slit onto the image viewer, we need WCS information from an image and slit position from a 2D spectrum. -WCS information is taken from the `meta` attribute of the :class:`~astropy.nddata.CCDData` object representing the data in the -image viewer. The slit position is calculated using the `S_REGION` header extension value, located in the `meta` attribute of -the :class:`~specutils.Spectrum1D` object that is active in the 2D spectrum viewer. +The slit position is calculated using the ``S_REGION`` header extension value, located in the +`~spectral_cube.SpectralCube.meta` attribute of the :class:`~specutils.Spectrum1D` object +that is active in the 2D spectrum viewer. diff --git a/docs/nitpick-exceptions b/docs/nitpick-exceptions new file mode 100644 index 0000000000..3447c12df2 --- /dev/null +++ b/docs/nitpick-exceptions @@ -0,0 +1,5 @@ +# https://github.com/mariobuikhuizen/ipyvuetify/issues/180 +py:class ipyvuetify.VuetifyTemplate.VuetifyTemplate + +# https://github.com/glue-viz/glue-jupyter/issues/258 +py:class glue_jupyter.table.viewer.TableViewer diff --git a/docs/notebook/export_data.rst b/docs/notebook/export_data.rst index f8234ea71a..19030d3dc8 100644 --- a/docs/notebook/export_data.rst +++ b/docs/notebook/export_data.rst @@ -9,7 +9,7 @@ Specific instructions on exporting data from Jdaviz to your notebook vary slight Export Position Regions (Imviz) ------------------------------- -In `Imviz`, you can extract positional regions:: +In `~jdaviz.configs.imviz.helper.Imviz`, you can extract positional regions:: regions = myviz.get_interactive_regions() regions @@ -58,9 +58,9 @@ Export Data from Image Viewer In Cubeviz, three image viewers display your data: - | Top Left: `flux-viewer` - | Center: `uncert-viewer` - | Top Right: `mask-viewer` + | Top Left: ``flux-viewer`` + | Center: ``uncert-viewer`` + | Top Right: ``mask-viewer`` If you have modified your data cube and have new data in one of your image viewers, you can extract it. To list the data avaialable in a particular viewer:: diff --git a/docs/notebook/import_data.rst b/docs/notebook/import_data.rst index 7e8577e58f..429227b010 100644 --- a/docs/notebook/import_data.rst +++ b/docs/notebook/import_data.rst @@ -8,7 +8,7 @@ Import Data From Notebook to Jdaviz Specific instructions on exporting data from Jdaviz to your notebook vary slightly for each instance of Jdaviz, including :ref:`api-import`, :ref:`api-import-cubeviz`, :ref:`mosviz-import-data`, and Imviz. These instructions all provide the ability to import data with the GUI or the API via the Jupyter notebook. -If using the Jupyter notebook, users can load data into the application through code using the `load_data` +If using the Jupyter notebook, users can load data into the application through code using the ``load_data`` method, which takes as input either the name of a local file or a :class:`~spectral_cube.SpectralCube` or :class:`~specutils.Spectrum1D` object. @@ -16,29 +16,35 @@ For Specviz:: from jdaviz import Specviz from specutils import Spectrum1D - myviz = Specviz() - myviz.app - spec1d = Spectrum1D.read("/path/to/data/file") - myviz.load_data(spec1d) + specviz = Specviz() + specviz.app + spec1d = Spectrum1D.read("/path/to/data/spectrum_file.fits") + specviz.load_data(spec1d) -If you need to create your own Spectrum1D file:: +If you need to create your own `~specutils.Spectrum1D` file:: from specutils import Spectrum1D - flux = np.random.randn(200)*u.Jy - wavelength = np.arange(5100, 5300)*u.AA + flux = np.random.randn(200) * u.Jy + wavelength = np.arange(5100, 5300) * u.AA spec1d = Spectrum1D(spectral_axis=wavelength, flux=flux) For Cubeviz:: from jdaviz import Cubeviz - myviz = Cubeviz() - myviz.app - myviz.load_data("/Users/demouser/data/cube_file.fits") - + cubeviz = Cubeviz() + cubeviz.app + cubeviz.load_data("/path/to/data/cube_file.fits") For Mosviz:: - from jdaviz.configs.mosviz.helper import Mosviz - myviz = Mosviz() - myviz.app - mosviz.load_data(directory="/path/to/data/file", instrument="nirspec") # Or niriss + from jdaviz import Mosviz + mosviz = Mosviz() + mosviz.app + mosviz.load_data(directory="/path/to/data", instrument="nirspec") # Or "niriss" + +For Imviz:: + + from jdaviz import Imviz + imviz = Imviz() + imviz.app + imviz.load_data("/path/to/data/image.fits") diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 3350b71e15..f03a81b55c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -7,7 +7,7 @@ Quickstart Once installed, ``jdaviz`` can be run either as a standalone web application or in a Jupyter notebook. As a Web Application ------------------------- +-------------------- ``jdaviz`` provides a command-line tool to start the web application. To see the syntax and usage, from a terminal, type:: @@ -26,8 +26,8 @@ For example, to load a SDSS MaNGA IFU data cube into ``Cubeviz``, you would run In a Jupyter Notebook --------------------- -``jdaviz`` provides a directory of sample notebooks to test the application, located in the `notebooks` sub-directory -of the git repository. `Example.ipynb` is provided as an example that loads a SDSS MaNGA IFU data cube with the +``jdaviz`` provides a directory of sample notebooks to test the application, located in the ``notebooks`` sub-directory +of the git repository. ``Example.ipynb`` is provided as an example that loads a SDSS MaNGA IFU data cube with the ``Cubeviz`` configuration. To run the provided example, start the jupyter kernel with the notebook path:: jupyter notebook /path/to/jdaviz/notebooks/Example.ipynb diff --git a/docs/reference/api.rst b/docs/reference/api.rst index d61d2e0ab2..42aa528167 100644 --- a/docs/reference/api.rst +++ b/docs/reference/api.rst @@ -8,6 +8,9 @@ Core .. automodapi:: jdaviz.core.events :no-inheritance-diagram: +.. automodapi:: jdaviz.core.helpers + :no-inheritance-diagram: + .. automodapi:: jdaviz.core.registries :no-inheritance-diagram: @@ -20,16 +23,29 @@ Application .. automodapi:: jdaviz.app :no-inheritance-diagram: + :no-inherited-members: Configurations ============== -.. automodapi:: jdaviz.configs.default.plugins +.. automodapi:: jdaviz.configs.default :no-inheritance-diagram: -.. automodapi:: jdaviz.configs.cubeviz.plugins +.. automodapi:: jdaviz.configs.default.plugins.line_lists.line_list_mixin + :no-inheritance-diagram: + +.. automodapi:: jdaviz.configs.cubeviz :no-inheritance-diagram: .. automodapi:: jdaviz.configs.imviz :no-inheritance-diagram: + +.. automodapi:: jdaviz.configs.mosviz + :no-inheritance-diagram: + +.. automodapi:: jdaviz.configs.specviz + :no-inheritance-diagram: + +.. automodapi:: jdaviz.configs.specviz2d + :no-inheritance-diagram: diff --git a/docs/specviz/displaying.rst b/docs/specviz/displaying.rst index c817363010..d12041d99c 100644 --- a/docs/specviz/displaying.rst +++ b/docs/specviz/displaying.rst @@ -14,10 +14,10 @@ if they exceed the bounds of the plotted area, which are set based on the first displayed spectrum. The bounds can be changed via the :ref:`Pan/Zoom ` tool or by deselecting the current spectra and selecting a different spectrum for display. Spectra generated by plugins -(e.g a spectrum generated by the Gaussian Smooth plugin) will generally be +(e.g., a spectrum generated by the Gaussian Smooth plugin) will generally be automatically displayed as well, and one can always see the spectra available and toggle their visibility in the data selection dropdown menu -(see :ref:`Selecting Data Set` for more detail). If you are +(see :ref:`Selecting Data Set ` for more detail). If you are working in the notebook, you can also enable more reproducible analysis by using the Python API. Both are detailed further below. @@ -69,8 +69,10 @@ The Specviz helper contains a set of convenience methods to programmatically def Limit methods ^^^^^^^^^^^^^ -You can use the methods :py:func:`specviz.x_limits()` and :py:func:`specviz.y_limits()` to modify the field of view of Specviz. You can provide a scalar (which assumes the units of the loaded spectra), an Astropy Quantity, or 'auto' to automatically scale -:: +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 +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:: >>> specviz.x_limits() #doctest: +SKIP >>> specviz.x_limits(650*u.nm,750*u.nm) #doctest: +SKIP @@ -85,11 +87,15 @@ Additionally, you can provide the limit methods with a `~specutils.SpectralRegio Autoscale methods ^^^^^^^^^^^^^^^^^ -You can also quickly return to the default zoom using :py:func:`specviz.autoscale_x()` and :py:func:`specviz.autoscale_y()` +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`. Axis Orientation methods ^^^^^^^^^^^^^^^^^^^^^^^^ -To quickly flip an axis to change to and from ascending/descending, use :py:func:`specviz.flip_x()` and :py:func:`specviz.flip_y()` +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`. .. _spectral-regions: @@ -117,7 +123,8 @@ Now just select the end points of the new region as before. It will be added to .. image:: img/spectral_region_4.png -In a notebook cell, you can access the regions using the `get_spectral_regions()` function: +In a notebook cell, you can access the regions using the +:meth:`~jdaviz.configs.specviz.helper.Specviz.get_spectral_regions` method: .. image:: img/spectral_region_5.png diff --git a/docs/specviz/import_data.rst b/docs/specviz/import_data.rst index 577773e40b..cd6d757f70 100644 --- a/docs/specviz/import_data.rst +++ b/docs/specviz/import_data.rst @@ -2,7 +2,7 @@ Loading Data into Specviz ************************* -By design, Specviz only supports data that can be parsed as :class:`~specutils.Spectrum1D` objects, as that 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. +By design, Specviz only supports data that can be parsed as :class:`~specutils.Spectrum1D` objects, as that 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. .. seealso:: @@ -40,16 +40,16 @@ Here, users can select the loaded data set to be visualized in the viewer. Loading data via the API ------------------------ Alternatively, if users are working in a coding environment like a Jupyter notebook, they have access to the :class:`~jdaviz.configs.specviz.helper.Specviz` helper class API. Using this API, users can load data into the application through code. -Below is an example of importing the :class:`~jdaviz.configs.specviz.helper.Specviz` helper class, creating a :class:`~specutils.Spectrum1D` object from a data file via the :func:`~specutils.Spectrum1D.read` method:: +Below is an example of importing the :class:`~jdaviz.configs.specviz.helper.Specviz` helper class, creating a :class:`~specutils.Spectrum1D` object from a data file via the `specutils.Spectrum1D.read` method:: >>> from specutils import Spectrum1D >>> spec1d = Spectrum1D.read("/path/to/data/file") #doctest: +SKIP - >>> specviz = Specviz() #doctest: +SKIP - >>> specviz.load_spectrum(spec1d) #doctest: +SKIP + >>> specviz = Specviz() # doctest: +SKIP + >>> specviz.load_spectrum(spec1d) # doctest: +SKIP -This method works well for data files that `specutils` understands. However, if you are using your own data file or in-memory data, you can instead create a :class:`~specutils.Spectrum1D` object directly. In this example that is done using randomly generated data, and then that :class:`~specutils.Spectrum1D` object is loaded into the Specviz application:: +This method works well for data files that ``specutils`` understands. However, if you are using your own data file or in-memory data, you can instead create a :class:`~specutils.Spectrum1D` object directly. In this example that is done using randomly generated data, and then that :class:`~specutils.Spectrum1D` object is loaded into the Specviz application:: - >>> from jdaviz.configs.specviz.helper import Specviz + >>> from jdaviz import Specviz >>> import numpy as np >>> import astropy.units as u >>> from specutils import Spectrum1D diff --git a/docs/specviz/index.rst b/docs/specviz/index.rst index f760b1cc1d..f756cfcd8e 100644 --- a/docs/specviz/index.rst +++ b/docs/specviz/index.rst @@ -8,7 +8,7 @@ Specviz ####### -Specviz is a tool for visualization and quick-look analysis of 1D astronomical spectra. Like the rest of `jdaviz`, it is written in the Python programming language, and therefore can be run anywhere Python is supported (see :doc:`../installation`). Specviz is built on top of the `specutils `_ package from `Astropy `_ , providing a visual, interactive interface to the analysis capabilities in that library. +Specviz is a tool for visualization and quick-look analysis of 1D astronomical spectra. Like the rest of Jdaviz, it is written in the Python programming language, and therefore can be run anywhere Python is supported (see :ref:`install`). Specviz is built on top of the `specutils `_ package from `astropy `_ , providing a visual, interactive interface to the analysis capabilities in that library. Specviz allows spectra to be easily plotted and examined. It supports flexible spectral unit conversions, custom plotting attributes, interactive selections, multiple plots, and other features. diff --git a/docs/specviz/plugins.rst b/docs/specviz/plugins.rst index b7c6413b40..6122f41b17 100644 --- a/docs/specviz/plugins.rst +++ b/docs/specviz/plugins.rst @@ -6,9 +6,9 @@ Data Analysis Plugins To enable quick analysis of astronomical spectra, Specviz ships with a number of plugins that let you do various standard spectral analysis tasks. Note that -these plugins all depend on `specutils` to do the actual analysis work - when +these plugins all depend on ``specutils`` to do the actual analysis work - when doing these operations in the Notebook you are often better off using -the `specutils` or `astropy` APIs directly instead of using the plugins. But +the ``specutils`` or ``astropy`` APIs directly instead of using the plugins. But for quick-look or interaction heavy workflows, the plugins provide a UI-based alternative. @@ -37,6 +37,8 @@ viewer. It can be selected and shown in the viewer via the :guilabel:`gear-->Data` tab. +.. _specviz-model-fitting: + Model Fitting ============= @@ -61,17 +63,19 @@ For example, add together Constant and Gaussian models with model IDs 'C' and 'G1' by entering the Model Equation 'C+G1'. Fitted models can be extracted from the app into notebook cells by using -the `get_models` method of the configuration `helper` class , e.g. :: +the :meth:`~jdaviz.core.helpers.ConfigHelper.get_models` method of the +configuration helper class, e.g.:: specviz.get_models(model_label="Model") -The `get_models` method returns the fitted `astropy` model objects. If only +The :meth:`~jdaviz.core.helpers.ConfigHelper.get_models` method returns the +fitted ``astropy`` model objects. If only the parameters of the model are needed, those can be extracted using the following code:: specviz.get_model_parameters(model_label="Model") -If nothing is specified for the `model_label` parameter, information for +If nothing is specified for the ``model_label`` keyword, information for all models will be returned. Unit Conversion @@ -145,6 +149,6 @@ No continuum operations are performed as part of this plugin. This means that the statistics may or may not be correct depending on how you have prepared your spectrum - most statistics assume a continuum-subtracted spectrum, aside from equivalent width which assumes continuum-normalized. If your continuum is -not in this form initially, you may wish to either use the `specutils` API in +not in this form initially, you may wish to either use the ``specutils`` API in the Notebook Interface to perform continuum subtraction/normalization, or make use of the model fitting plugin to do the appropriate corrections. diff --git a/docs/specviz/redshift.rst b/docs/specviz/redshift.rst index c0370ecf4b..8654c4487e 100644 --- a/docs/specviz/redshift.rst +++ b/docs/specviz/redshift.rst @@ -13,9 +13,10 @@ to set an app-level redshift or radial velocity. The user can toggle between the two modes by clicking the dropdown menu to the left of the slider bar. Any redshift or radial velocity set by the slider bar is automatically applied to any spectral lines that have been loaded into the app (see -:ref:`Line Lists`), and are applied to spectra output using the -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 +:ref:`Line Lists `), and are applied to spectra output using the +: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. .. image:: img/redshift_slider.png @@ -34,6 +35,6 @@ From the notebook The upper and lower bounds of the slider, as well as the resolution of a single step in the slider, can be set from a notebook cell using the -`set_redshift_slider_bounds` method by specifying the `upper`, `lower` and -`step` keywords. The redshift on the slider can be set from the notebook using -the `set_redshift` method. +:meth:`jdaviz.configs.specviz.Specviz.set_redshift_slider_bounds` method by +specifying the ``upper``, ``lower`` and ``step`` keywords. +The redshift on the slider can be set from the notebook using the ``set_redshift`` method. diff --git a/jdaviz/app.py b/jdaviz/app.py index 8cca61ea05..0282f7bd6f 100644 --- a/jdaviz/app.py +++ b/jdaviz/app.py @@ -197,37 +197,25 @@ def __init__(self, configuration=None, *args, **kwargs): @property def hub(self): """ - Reference to the stored application handler hub instance. - - Returns - ------- - `glue.core.Hub` - The internal ``Hub`` instance for the application. + Reference to the stored application handler `~glue.core.hub.Hub` instance + for the application. """ return self._application_handler.data_collection.hub @property def session(self): """ - Reference to the stored session instance. - - Returns - ------- - `glue.core.Session` - The ``Session`` instance maintained by Glue for this application. + Reference to the stored `~glue.core.session.Session` instance + maintained by Glue for this application. """ return self._application_handler.session @property def data_collection(self): """ - Reference to the stored data collection instance, used to maintain the - the data objects that been loaded into the application this session. - - Returns - ------- - `glue.core.DataCollection` - The ``DataCollection`` instance for this application session. + Reference to the stored `~glue.core.data_collection.DataCollection` instance, + used to maintain the the data objects that been loaded into the application + this session. """ return self._application_handler.data_collection @@ -305,7 +293,7 @@ def _link_new_data(self): def load_data(self, file_obj, parser_reference=None, **kwargs): """ Provided a path to a data file, open and parse the data into the - `~glue.core.DataCollection` for this session. This also attempts to + `~glue.core.data_collection.DataCollection` for this session. This also attempts to find WCS links that exist between data components. Extra key word arguments are passed to the parsing functions. @@ -1065,7 +1053,7 @@ def _on_data_added(self, msg): Parameters ---------- - msg : `~glue.core.DataCollectionAddMessage` + msg : `~glue.core.message.DataCollectionAddMessage` The Glue data collection add message containing information about the new data. """ @@ -1080,7 +1068,7 @@ def _on_data_deleted(self, msg): Parameters ---------- - msg : `~glue.core.DataCollectionAddMessage` + msg : `~glue.core.message.DataCollectionAddMessage` The Glue data collection add message containing information about the new data. """ diff --git a/jdaviz/configs/specviz/plugins/unit_conversion/unit_conversion.py b/jdaviz/configs/specviz/plugins/unit_conversion/unit_conversion.py index 55dc241185..80e5cec110 100644 --- a/jdaviz/configs/specviz/plugins/unit_conversion/unit_conversion.py +++ b/jdaviz/configs/specviz/plugins/unit_conversion/unit_conversion.py @@ -95,11 +95,11 @@ def set_spectrum(self, spectrum, label): Set spectrum for unit conversion. Parameters - spectrum : `Spectrum1D` + ---------- + spectrum : `~specutils.Spectrum1D` Spectrum for unit conversion. - label : `string` + label : str Label used to represent spectrum. - ---------- """ self.spectrum = spectrum self.selected_data = label @@ -130,7 +130,7 @@ def update_ui(self): def vue_unit_conversion(self, *args, **kwargs): """ - Runs when the `apply` button is hit. Tries to change units if `new` units are set + Runs when the ``apply`` button is hit. Tries to change units if ``new`` units are set and are valid. """ @@ -208,16 +208,16 @@ def process_unit_conversion(self, spectrum, new_flux=None, new_spectral_axis=Non Parameters ---------- - spectrum : `Spectrum1D` + spectrum : `specutils.Spectrum1D` The spectrum that will have its units converted. - new_flux : `` + new_flux The flux of spectrum will be converted to these units if they are provided. - new_spectral_axis : `` + new_spectral_axis The spectral_axis of spectrum will be converted to these units if they are provided. Returns ------- - converted_spectrum : `Spectrum1D` + converted_spectrum : `specutils.Spectrum1D` A new spectrum with converted units. """ set_spectral_axis_unit = spectrum.spectral_axis diff --git a/jdaviz/configs/specviz/plugins/viewers.py b/jdaviz/configs/specviz/plugins/viewers.py index 22737d66fc..5a01e7f39f 100644 --- a/jdaviz/configs/specviz/plugins/viewers.py +++ b/jdaviz/configs/specviz/plugins/viewers.py @@ -303,16 +303,17 @@ def add_data(self, data, color=None, alpha=None, **layer_state): Parameters ---------- - spectrum : :class:`glue.core.Data` + spectrum : :class:`glue.core.data.Data` Data object with the spectrum. - color: color specification - Color value for plotting - alpha: float - Alpha value for plotting + color : obj + Color value for plotting. + alpha : float + Alpha value for plotting. Returns ------- - :bool: True if success, False otherwise. + result : bool + `True` if successful, `False` otherwise. """ # The base class handles the plotting of the main # trace representing the spectrum itself. diff --git a/jdaviz/core/helpers.py b/jdaviz/core/helpers.py index 37af535418..dfdd380d96 100644 --- a/jdaviz/core/helpers.py +++ b/jdaviz/core/helpers.py @@ -7,27 +7,29 @@ on the motivation behind this concept. """ import re + import numpy as np import astropy.units as u - -from ..app import Application from glue.core import HubListener +from jdaviz.app import Application + __all__ = ['ConfigHelper'] class ConfigHelper(HubListener): - """The Base Helper Class + """The Base Helper Class. Provides shared abstracted helper methods to the user. - Subclasses should set `_default_configuration` if they are meant to be + Subclasses should set ``_default_configuration`` if they are meant to be used with a specific configuration. Parameters ---------- - app : jdaviz.app.Application or None - The application object, or if None, creates a new one based on the + app : `~jdaviz.app.Application` or `None` + The application object, or if `None`, creates a new one based on the default configuration for this helper. + verbosity : {'debug', 'info', 'warning', 'error'} Verbosity of the application. """ @@ -67,7 +69,7 @@ def get_models(self, models=None, model_label=None, x=None, y=None): models : dict A dict of models, with the key being the label name and the value being an `astropy.modeling.CompoundModel` object. Defaults to - `self.fitted_models` if no parameter is provided. + `fitted_models` if no parameter is provided. model_label : str The name of the model that will be found and returned. If it equals default, every model present will be returned. @@ -78,7 +80,8 @@ def get_models(self, models=None, model_label=None, x=None, y=None): Returns ------- - :dict: dictionary of the selected models. + selected_models : dict + Dictionary of the selected models. """ selected_models = {} # If models is not provided, use the app's fitted models diff --git a/jdaviz/core/registries.py b/jdaviz/core/registries.py index 96a06f088b..d159b7006e 100644 --- a/jdaviz/core/registries.py +++ b/jdaviz/core/registries.py @@ -1,12 +1,13 @@ -from glue.config import DictRegistry import re + +from glue.config import DictRegistry from ipyvuetify import VuetifyTemplate from ipywidgets import Widget __all__ = ['viewer_registry', 'tray_registry', 'tool_registry', 'data_parser_registry', 'ViewerRegistry', 'TrayRegistry', - 'ToolRegistry', 'MenuRegistry', 'DataParserRegistry'] + 'ToolRegistry', 'MenuRegistry', 'DataParserRegistry', 'UniqueDictRegistry'] def convert(name): diff --git a/jdaviz/core/template_mixin.py b/jdaviz/core/template_mixin.py index 7e1fa86f1c..e8c92e21e5 100644 --- a/jdaviz/core/template_mixin.py +++ b/jdaviz/core/template_mixin.py @@ -8,7 +8,7 @@ class TemplateMixin(VuetifyTemplate, HubListener): def __new__(cls, *args, **kwargs): """ Overload object creation so that we can inject a reference to the - ``Hub`` class before components can be initialized. This makes it so + `~glue.core.hub.Hub` class before components can be initialized. This makes it so hub references on plugins can be passed along to components in the call to the initialization method. """ @@ -21,9 +21,9 @@ def __new__(cls, *args, **kwargs): @property def app(self): """ - Allows access to the underlying jdaviz application instance. This is + Allows access to the underlying Jdaviz application instance. This is **not** access to the helper class, but instead the - `jdaviz.Application` object. + `jdaviz.app.Application` object. """ return self._app From 6c09a12c230374f93a0a8756c920d222cf9254ab Mon Sep 17 00:00:00 2001 From: Pey Lian Lim <2090236+pllim@users.noreply.github.com> Date: Tue, 14 Sep 2021 16:29:30 -0400 Subject: [PATCH 3/3] Fix code typo in doc and error in rebase. --- docs/imviz/notebook.rst | 2 +- docs/mosviz/plugins.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/imviz/notebook.rst b/docs/imviz/notebook.rst index 085a41c904..84f473b1ff 100644 --- a/docs/imviz/notebook.rst +++ b/docs/imviz/notebook.rst @@ -14,5 +14,5 @@ Imviz also provides programmatic access to its viewers using `Astrowidgets `_ API. For example:: - viewer = imviz.get_viewer('viewer-1') + viewer = imviz.app.get_viewer('viewer-1') viewer.center_on((100, 100)) diff --git a/docs/mosviz/plugins.rst b/docs/mosviz/plugins.rst index 65df7ff373..6f2bff19a6 100644 --- a/docs/mosviz/plugins.rst +++ b/docs/mosviz/plugins.rst @@ -68,5 +68,5 @@ The :guilabel:`Remove` button can be used to remove a slit once it has been appl In order to plot a slit onto the image viewer, we need WCS information from an image and slit position from a 2D spectrum. The slit position is calculated using the ``S_REGION`` header extension value, located in the -`~spectral_cube.SpectralCube.meta` attribute of the :class:`~specutils.Spectrum1D` object +`~specutils.Spectrum1D.meta` attribute of the :class:`~specutils.Spectrum1D` object that is active in the 2D spectrum viewer.