-
-
Notifications
You must be signed in to change notification settings - Fork 15
/
installation.rst
269 lines (193 loc) · 10.6 KB
/
installation.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
Installing pywwt
================
Try without installing
----------------------
You can try out the pywwt Jupyter widget without installing anything locally by
using one of our example notebooks, served from the cloud! `Click here
<https://bit.ly/pywwt-notebooks>`_ to launch our examples using the great
`MyBinder <https://mybinder.org/>`_ service. These notebooks are defined in `the
pywwt-notebooks repository`_ on GitHub, which has further links and information
about these samples.
.. _the pywwt-notebooks repository: https://github.com/WorldWideTelescope/pywwt-notebooks#readme
Install pywwt with conda-forge (recommended)
--------------------------------------------
The recommended way to install pywwt is using the `conda`_ package manager and
packages provided by the `conda-forge`_ project. If you’re already using a
conda-based Python environment, you can install the latest release of pywwt with:
.. code-block:: sh
conda install -c conda-forge pywwt
.. _conda: https://conda.io/
.. _conda-forge: https://conda-forge.org/
This will install pywwt, its `dependencies`_, and the Jupyter extension. **If
you want to use pywwt inside JupyterLab** — which we heartily recommend — see
`Set Up pywwt’s JupyterLab Integration`_ below.
We recommend that you `permanently enable conda-forge`_ in your Python
environment to ensure that your packages are self-consistent and get the latest
updates. Be advised that activating conda-forge may update a whole bunch of your
software at once, which might be something to avoid right before a proposal
deadline.
.. _permanently enable conda-forge: https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge
If you aren’t using a conda-based Python environment, it’s easy to set one up.
The `Anaconda Distribution <https://www.anaconda.com/products/individual>`_ is
popular and widely supported, or you can use `Miniforge
<https://github.com/conda-forge/miniforge#user-content-install>`_ or `Miniconda
<https://docs.conda.io/en/latest/miniconda.html>`_ for a smaller download. These
environments install in a fully self-contained manner, so you can try them out
without modifying your computer’s existing Python installation(s).
Install pywwt with pip
----------------------
You can also install the latest release of pywwt using `pip
<https://pip.pypa.io/en/stable/>`_:
.. code-block:: sh
pip install pywwt
While ``pip`` will automatically install most dependencies as needed, to use the
Qt widget you will need to install `PyQt
<https://riverbankcomputing.com/software/pyqt/intro>`_ and `PyQtWebEngine
<https://riverbankcomputing.com/software/pyqtwebengine/intro>`_, or `PySide
<https://wiki.qt.io/PySide>`_ separately. See the full list of dependencies
below.
.. _setup-jupyterlab:
Set Up pywwt’s JupyterLab Integration
-------------------------------------
To use pywwt in an interactive computing environment, we recommend combining it
with `JupyterLab <https://jupyterlab.readthedocs.io/>`_. It’s worth noting that
the JupyterLab web application is a separate thing than just “Jupyter,” the
lower-level system upon which it is built. `Learn how to install JupyterLab here
<https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html>`_.
Once you’ve installed JupyterLab, you need to install a couple of other
supporting components beyond pywwt to get the best experience: the `WWT Kernel
Data Relay`_ (KDR) extension, the `WWT JupyterLab Extension`_, and the
`JupyterLab widget manager extension`_. The following commands should ensure
that everything is set up:
.. _WWT Kernel Data Relay: https://github.com/WorldWideTelescope/wwt_kernel_data_relay/#readme
.. _WWT JupyterLab Extension: https://github.com/WorldWideTelescope/wwt-jupyterlab#readme
.. _JupyterLab widget manager extension: https://www.npmjs.com/package/@jupyter-widgets/jupyterlab-manager
.. code-block:: sh
pip install wwt-kernel-data-relay # or use conda
jupyter labextension install --no-build @jupyter-widgets/jupyterlab-manager
jupyter labextension install --no-build @wwtelescope/jupyterlab
jupyter lab build
If the installation is successful, then the next time you start up JupyterLab
the “Launcher” display should now contain a WorldWide Telescope icon:
.. image:: images/jlab-launcher.jpg
:scale: 50%
:alt: Screenshot of JupyterLab launcher with WWT icon
:align: center
Clicking on this icon should open up the `WWT research app
<https://docs.worldwidetelescope.org/research-app/latest/>`_, which you can then
control using pywwt, via :func:`pywwt.jupyter.connect_to_app`.
.. _setup-jupyter-widget:
Set up the pywwt Jupyter Widget
-------------------------------
If you are using a Jupyter notebook, either within JupyterLab or in “vanilla
“Jupyter, you may also wish to set up pywwt’s “Jupyter widget” support. This
integration *should* be set up automatically if you install pywwt through one of
the standard methods, but it can be somewhat finicky. As with the JupyterLab support,
you should install the `WWT Kernel Data Relay`_ (KDR) extension:
.. code-block:: sh
pip install wwt-kernel-data-relay # or use conda
To check whether the widget is working, run the following Python commands inside
of a Jupyter notebook::
from pywwt.jupyter import WWTJupyterWidget
wwt = WWTJupyterWidget()
wwt # just "print" this variable on its own line
If everything is working, you should see a WWT window open up inside your
notebook, like so:
.. image:: images/jupyter.jpg
:scale: 25%
:alt: Screenshot of Jupyter notebook with WWT widget
:align: center
If you get any other result, some troubleshooting may be necessary.
Troubleshooting the Jupyter Integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first thing to check is the “notebook extension”. Run:
.. code-block:: sh
jupyter nbextension install --py --sys-prefix pywwt
jupyter nbextension enable --py --sys-prefix pywwt
jupyter nbextension list
These commands should not report any error messages, and should indicate at the
end that the ``pywwt`` extension is installed, enabled, and validated. The
``ipyevents`` extension should also be available. Unfortunately, if there is a
problem at this stage, there might be a lot of possible reasons. For help, try
`filing an issue on our GitHub
<https://github.com/WorldWideTelescope/pywwt/issues/new>`_ with a copy-paste of
the output from the commands above.
Next are the Jupyter “server extension”s, which are controlled similarly:
.. code-block:: sh
jupyter serverextension enable --py --sys-prefix pywwt
jupyter serverextension list
Here too, the commands should report that the ``pywwt`` and
``wwt_kernel_data_relay`` extensions are installed and enabled, without any
apparent errors.
The recommended way to use pywwt inside of JupyterLab (not vanilla Jupyter) is
with the help of the separate `WWT JupyterLab Extension`_:
.. code-block:: sh
jupyter labextension install --no-build @wwtelescope/jupyterlab
jupyter labextension list
Finally, if you wish to use the specific combination of the pywwt *widget* (not
app) inside of JupyterLab (not vanilla Jupyter), you may also need to ensure
that pywwt is installed as its own, different, “lab extension”, along with
additional helpers:
.. code-block:: sh
jupyter labextension install --no-build @jupyter-widgets/jupyterlab-manager
jupyter labextension install --no-build ipyevents
jupyter labextension install --no-build pywwt
jupyter labextension list
If the above commands seem to be OK but report that a “build” is needed, that is
OK:
.. code-block:: sh
jupyter lab build
Dependencies
------------
If you install pywwt using pip or conda as described above, any required
dependencies will get installed automatically (with the exception of PyQt/PySide
if using pip). For the record, these dependencies are as follows:
* `Python <https://www.python.org>`_ 3.7 or later
* `NumPy <https://numpy.org>`_ 1.9 or later
* `Matplotlib <https://matplotlib.org>`_ 1.5 or later
* `Astropy <https://www.astropy.org>`_ 1.0 or later
* `Requests <https://requests.kennethreitz.org/en/master/>`_
* `Beautiful Soup 4 <https://www.crummy.com/software/BeautifulSoup>`_
* `Dateutil <http://labix.org/python-dateutil>`_
* `lxml <https://lxml.de>`_
* `ipywidgets <https://ipywidgets.readthedocs.io>`_ 7.0.0 or later
* `ipyevents <https://github.com/mwcraig/ipyevents>`_
* `traitlets <https://traitlets.readthedocs.io>`_
* `reproject <https://reproject.readthedocs.io/>`_
* `pytz <https://pythonhosted.org/pytz>`_
In addition, if you want to use the Qt widget, you will need:
* `PySide <https://wiki.qt.io/PySide>`__ or `PyQt
<https://riverbankcomputing.com/software/pyqt/intro>`__ and `PyQtWebEngine
<https://riverbankcomputing.com/software/pyqtwebengine/intro>`__ (both PyQt4
and PyQt5 are supported)
* `QtPy <https://pypi.org/project/QtPy/>`__ 1.2 or later
* `tornado <https://www.tornadoweb.org/en/stable/>`_
For the Jupyter widget, you will need:
* `Jupyter <https://jupyter.org/>`__ 1.0.0 or later
* `notebook <https://jupyter-notebook.readthedocs.io/en/stable/>`__ 5.0.0 or later
Installing the developer version
--------------------------------
If you want to use the very latest developer version version, you can clone
this repository and install the package manually (note that this requires `npm
<https://www.npmjs.com>`_ to be installed)::
git clone https://github.com/WorldWideTelescope/pywwt.git
cd pywwt
pip install -e .
If you want to use the Jupyter widget with a recent installation of the Jupyter
stack, you will also need to run::
jupyter nbclassic-extension install --py --symlink --sys-prefix pywwt
jupyter nbclassic-extension enable --py --sys-prefix pywwt
jupyter nbclassic-extension list # check that the output shows pywwt as enabled and OK
jupyter nbclassic-serverextension enable --py --sys-prefix pywwt
jupyter nbclassic-serverextension list # check that the output shows pywwt as enabled and OK
On older versions of Jupyter, use the ``nbextension`` subcommand instead of
``nbclassic-extension``, and use just ``serverextension`` instead of
``nbclassic-serverextension``.
And if you additionally want to use the widget in JupyterLab, run::
jupyter labextension install frontend
jupyter labextension list # check that the output shows pywwt as enabled and OK
Besides ``pywwt``, the `WWT Kernel Data Relay`_ server extension and the `WWT
JupyterLab extension`_ are both strongly recommended, but not technically
necessary. If you want to use pywwt as a widget in JupyterLab, the
``@jupyter-widgets/jupyterlab-manager`` and ``ipyevents`` lab-extensions must be
installed and enabled.