.. _install:
Installation
============
.. Note:: Requires: Python >=3.5
Tested on:
* macOS El Capitan (10.11.6) - Catalina (10.15.3)
* Ubuntu 16.04 - 18.04
* Windows 10 Subsystem for Linux
How to Install
--------------
The Data Tools can currently be installed from the tar file available at
the `Fermi Science Support Center
`_. Download the tar file
to some place on the machine you want it installed on.
One of the easiest and suggested methods of install is to create a virtual
environment, which allows you to install the Data Tools requirements without
worrying about possible conflicts with other versions of packages you may
already have installed. It's not mandatory to install in a virtual environment,
but it could make your life much easier.
.. Note::
One of the requirements for the Data Tools is Basemap, which is a part of
the Matplotlib toolkit. Basemap requires the installation of the GEOS C
library. If you do not have the library already compiled in a standard
place, the Data Tools installation will attempt to compile it
for you. There may be cases where this fails. If you encounter such a
case, you should follow the instructions on how to compile the GEOS library
for basemap `here `_.
To install via ``pip``, navigate to the directory where you want the virtual
environment to live and::
$ python3 -m venv gbm
$ source gbm/bin/activate
This will create a new virtual environment called "gbm" and activates the
environment.
To install via ``conda``::
$ conda create --name gbm
$ source activate gbm
This will similarly create a new virtual environment and activates it.
It's also good to ensure you have ``pip`` updated::
$ pip3 install --upgrade pip
The complete version of the Data Tools requires Matplotlib Basemap, although
the Data Tools can be installed without Basemap with the loss of only some
plotting functionality (EarthPlot and some SkyPlot functions). If you wish to
install the "light" version with Basemap, simply::
$ pip3 install /gbm_data_tools-1.1.1.tar.gz
If you want the full install, including Basemap, you will need the GEOS C
library. If it is not already installed in a standard location, set your
``GEOS_DIR`` environment variable to a path where you would like it installed
(and where you have write privileges). For example, if you use bash, you can
do something like this: ::
$ export GEOS_DIR=~/.geos_dir
If you already have the GEOS C library installed in a *non-standard* location,
set ``GEOS_DIR`` to that path instead. Then you can install the data tools::
$ pip3 install /gbm_data_tools-1.1.1.tar.gz[basemap]
Finally, if you want to run the Jupyter notebooks provided with the Data Tools
(trust us, you do)::
$ pip3 install ipython
$ pip3 install notebook
If you don't wish to install via a virtual environment, you are welcome to
install with your preferred method, but you may encounter more difficulties,
especially if you have existing package installs that conflict with what is
required for the Data Tools. Check the requirements.txt for required packages
and versions.
----
How to Uninstall
----------------
To uninstall::
$ pip3 uninstall gbm-data-tools
There are also a number of files (documentation, notebooks, etc.) for the tools
that are copied into your ``$HOME/.gbm_data_tools`` directory. You can delete
thesefiles if you wish.
Documentation
-------------
On successful installation, you can launch the local HTML documentation by
calling::
$ gbm-docs
from the command line.
----
.. _notebook_launch:
Launching the Notebooks
-----------------------
If you have installed Jupyter as suggested above, you can run the notebooks
provided with the Data Tools. After successful installation, the notebooks
can be launched by calling::
$ gbm-demos
from the command line.
----
Quickstart
----------
To load the Data Tools within your python environment, simply::
import gbm
The Data Tools has several different modules. For example, the data module
containing the interfaces to the GBM data files can be loaded by::
from gbm import data
Known Issues
------------
* **On install, Python complains the tar.gz file is not a valid file.**
This is a known issue with certain browsers, where they download *and*
decompress the file without removing the .gz extension. The easiest fix is
to rename the file without the .gz extension and retry the install.
* **When running a notebook in Linux, you observe a similar error**::
%matplotlib notebook
Warning: Cannot change to a different GUI toolkit: notebook. Using osx instead.
This is due to some backend plotting issue with Jupyter notebook on Linux.
Remove the ``%matplotlib inline`` in the notebook cell and re-evaluate the
cell *twice* to see the plot.
* **The FTP Data Finders fail with a connection error.** This may be due to the
underlying OpenSSL library that the Python ``ftplib`` uses. You may need to
update your OpenSSL library to get this to work. Note that this only appears
to be an issue with the FTPS protocol, not the normal FTP protocol.
A potential solution is to try the following:
* $ pip3 install pyopenssl
* $ pip3 install requests[security]
* **The virtual environment is using your system ipython (or other package)
install.** This can sometimes happen if you didn't install ipython (or other
package) in the virtual environment. Try installing ipython (or other package)
and restart your virtual environment.
* **You observe the following error**::
ImportError: No module named '_tkinter'
This is a situation where Matplotlib is using the ``tkinter`` backend for
plotting. You would see this error if you don't have ``tkinter`` installed.
You don't need to install ``tkinter`` if you don't want to; instead, you can
create a file named `matplotlibrc` in your working directory that contains the
following::
backend : Agg