From 27a3f678ec15da3c8dea3d672e3e8dc1d0e01a47 Mon Sep 17 00:00:00 2001 From: Pey Lian Lim <2090236+pllim@users.noreply.github.com> Date: Wed, 11 Aug 2021 14:59:12 -0400 Subject: [PATCH 1/3] DOC: Update known issues. And better organize the page. Also link to it from installation doc. --- docs/installation.rst | 9 ++-- docs/known_bugs.rst | 97 +++++++++++++++++++++++++++---------------- 2 files changed, 67 insertions(+), 39 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index ae8eefa7ed..d4606a5db9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -6,21 +6,24 @@ Installation The following details how to install the ``jdaviz`` Python package. +If you encounter problems while following these installation instructions, +please consult :ref:`known installation issues `. + Quick Installation ------------------ Installing the released version can be done using pip:: - pip install jdaviz + pip install jdaviz --upgrade -or if you want the latest in-development version, you can install via Github:: +or if you want the latest development version, you can install via GitHub:: pip install git+https://github.com/spacetelescope/jdaviz --upgrade Developer Installation ---------------------- -To install ``jdaviz`` for development, or from source:: +To install ``jdaviz`` for development or from source in editable mode:: git clone https://github.com/spacetelescope/jdaviz.git cd jdaviz diff --git a/docs/known_bugs.rst b/docs/known_bugs.rst index 9660bece8e..126a311c19 100644 --- a/docs/known_bugs.rst +++ b/docs/known_bugs.rst @@ -1,8 +1,25 @@ Known Issues ============ -On MacOS versions 10.13 and older, install fails due to `scikit-image` ----------------------------------------------------------------------- +You can `report an issue to the Jdaviz GitHub issues `_. + +Some currently known but unresolved common issues that users encounter +are as follow in their respective categories. This list is not exhaustive, +so please also consult `existing Jdaviz GitHub issues `_ +as well if you are unable to find your issue here: + +* :ref:`known_issues_installation` +* :ref:`known_issues_cubeviz` +* :ref:`known_issues_imviz` +* :ref:`known_issues_specviz` + +.. _known_issues_installation: + +Installation +------------ + +On MacOS versions 10.13 and older, install fails due to scikit-image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This can be fixed by reinstalling scikit-image:: @@ -19,24 +36,24 @@ Another way to get the up-to-date `scikit-image` version is:: Although this solution takes much longer (~5 minutes) to install than the first solution. -On some platforms, install fails due to `vispy` ------------------------------------------------ +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 workaround if you have an older version of vispy is to ensure you have a -compatible version: +compatible version:: - % conda create -n jdaviz python=3.8 - % conda activate jdaviz - % pip install vispy>=0.6.5 - % pip install jdaviz --no-cache-dir + conda create -n jdaviz python=3.8 + conda activate jdaviz + pip install vispy>=0.6.5 + pip install jdaviz --no-cache-dir See `Issue #305 `_ for updates on this topic. -On some platforms, install fails due to `bottleneck` ----------------------------------------------------- +On some platforms, install fails due to bottleneck +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In a conda environment, where numpy was installed using conda, installing jdaviz using pip will attempt to pull bottleneck from PyPI. This might result @@ -44,22 +61,23 @@ in bottleneck trying to build numpy from source and crash, stalling the installation altogether. When this happens, exit the installation, install bottleneck with conda, and try to install jdaviz again. -Collapse Plugin spectral bounds don't match selected region ------------------------------------------------------------ +In Python 3.7.1, install fails due to terminado +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Spectral bounds are off in the plugin compared to the spectrum viewer. +In Python 3.7.1, installing jdaviz might produce this error:: + ERROR: Cannot uninstall 'terminado'. It is a distutils installed project... -Ghost subsets and models in spectrum viewer -------------------------------------------- +The solution is to upgrade your Python version to at least the latest bug-fix +version of 3.7. -Mysterious extra subsets and models appear in the Specviz spectrum viewer -after fitting a model. Pan/zoom and resize were also used, but it is unclear -if they play a role or not in this bug. +.. _known_issues_cubeviz: +Cubeviz +------- -Cubeviz Collapse and Moment Maps: Spectral bounds do not match Region selection -------------------------------------------------------------------------------- +Collapse and Moment Maps: Spectral bounds do not match Region selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When trying to do a second collapse with the same spectral region, but with resized bounds: change to Region=None, resize the region, then reselect Region 1, @@ -67,34 +85,41 @@ the region bounds are correct. However, applying Collapse again, it errors out a the image viewer that contained the intial collapse goes blank. -Cubeviz cube viewer colormap printed out ----------------------------------------- - -When changing the colormap in the Cubeviz cube viewer-->Layer-->colormap, -the colormap name is printed in the cell output. - - -Cubeviz cube viewer contrast changes when collapsing jupyter scroll window ---------------------------------------------------------------------------- +Cube viewer contrast changes when collapsing Jupyter scroll window +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to see the full Cubeviz app in a Jupyter notebook, one can click on the side of the cell output to collapse or expand the scrollable window. This has the unintended consequence of changing the contrast of the image displayed in the Cubeviz cube viewer. +.. _known_issues_imviz: + +Imviz +----- -Imviz add_markers may not show markers --------------------------------------- +add_markers may not show markers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In some OS/browser combinations, ``imviz.add_markers(...)`` might take a few tries to show the markers, or not at all. This is a known bug reported in https://github.com/glue-viz/glue-jupyter/issues/243 . If you encounter this, try a different OS/browser combo. +.. _known_issues_specviz: -Reporting a bug ---------------- +Specviz +------- + +Collapse Plugin spectral bounds do not match selected region +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Spectral bounds are off in the plugin compared to the spectrum viewer. -You can report a bug in the Jdaviz GitHub issues: -https://github.com/spacetelescope/jdaviz/issues/new +Ghost subsets and models in spectrum viewer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Mysterious extra subsets and models appear in the Specviz spectrum viewer +after fitting a model. Pan/zoom and resize were also used, but it is unclear +if they play a role or not in this bug. From ac8a09810f7e7b996b5d9befe888294b1d6e710d Mon Sep 17 00:00:00 2001 From: Pey Lian Lim <2090236+pllim@users.noreply.github.com> Date: Mon, 16 Aug 2021 14:12:17 -0400 Subject: [PATCH 2/3] DOC: Remove ghost bug from listing --- docs/known_bugs.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/known_bugs.rst b/docs/known_bugs.rst index 126a311c19..1dc630b5cc 100644 --- a/docs/known_bugs.rst +++ b/docs/known_bugs.rst @@ -115,11 +115,3 @@ Collapse Plugin spectral bounds do not match selected region ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Spectral bounds are off in the plugin compared to the spectrum viewer. - - -Ghost subsets and models in spectrum viewer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mysterious extra subsets and models appear in the Specviz spectrum viewer -after fitting a model. Pan/zoom and resize were also used, but it is unclear -if they play a role or not in this bug. From 6130169ff74ecadb74fbd46c4188b7ce1770a292 Mon Sep 17 00:00:00 2001 From: "P. L. Lim" <2090236+pllim@users.noreply.github.com> Date: Fri, 20 Aug 2021 00:59:41 -0400 Subject: [PATCH 3/3] Clarify spectral bug Co-authored-by: Ricky O'Steen <39831871+rosteen@users.noreply.github.com> --- docs/known_bugs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/known_bugs.rst b/docs/known_bugs.rst index 1dc630b5cc..52603d3147 100644 --- a/docs/known_bugs.rst +++ b/docs/known_bugs.rst @@ -114,4 +114,4 @@ Specviz Collapse Plugin spectral bounds do not match selected region ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Spectral bounds are off in the plugin compared to the spectrum viewer. +Spectral bound values in the plugin sometimes differ slightly from the bounds shown visually in the spectrum viewer.