I strongly recommend installing the following dependencies via Anaconda (https://www.anaconda.com/distribution/). These and other requirements are available in the environment.yml file in the project’s GitHub repository.
Those that are not available via the Anaconda installer are available on the Python Package Index (PyPI):
1.2. Installation guide¶
This does not cover the installation of Anaconda, as it may differ depending on your system, and there are many excellent resources out there that can explain far better than me for your system of choice. Start with the Anaconda installation guide.
The console commands outlined here use Linux bash script. Mac users should be able to use all the same commands as I do, but Windows users will need to install and understand the Windows Subsystem for Linux (WSL) in order to execute these commands successfully. If you’d like information about installing and using WSL, see this guide for more details: https://docs.microsoft.com/en-us/windows/wsl/install-win10
Use of Anaconda is strongly recommended. After you’ve installed Anaconda, open a Terminal interface (UNIX) or the Anaconda Prompt (Windows) and make sure Anaconda works:
You should get output that displays the conda version (4.8.5 in my case). If not, please see note 1 above.
1.2.1. Installing from Anaconda Cloud¶
# create an environment named readgssi and install readgssi from the iannesbitt channel: conda create -n readgssi -c iannesbitt readgssi # and then activate the environment by doing: conda activate readgssi
Remember, you will need to activate the readgssi conda environment (i.e.
conda activate readgssi) each time you open a new terminal window in order for the readgssi commands to work (see note below for a brief explanation).
This should allow you to run the commands in the next section (General usage).
conda activate readgssi switches into a “virtual environment” which is basically a python space where you can install dependencies without messing with the functionality of python on the rest of your machine. This is useful but can be confusing: if you try to run readgssi from outside the virtual environment you just made, you will not be able to find it! The reason it’s useful is that it doesn’t modify the version of python or packages that your computer may use for system tasks (no one likes obscure errors, so we try to avoid them…and one of the best ways of doing that is by using virtual environments). To get back into the readgssi environment you created from a newly opened terminal window, simply do
conda activate readgssi.
1.2.2. Installing from PyPI¶
PyPI is the Python Package Index.
Once you have conda running, installing requirements is pretty easy. All dependencies are available through conda or pip.
conda config --add channels conda-forge conda create -n readgssi python==3.7 pandas h5py pytz obspy conda activate readgssi pip install readgssi
That should allow you to run the commands in the next section (General usage).
This code is doing a couple important things so if you’re unfamiliar with python and/or terminal commands, let’s go over what they are.
conda config --add channels conda-forge tells conda to look in the conda user code repository called “Conda Forge”. ObsPy and a lot of other user-created code lives in the Forge. Next,
conda create -n readgssi creates a virtual environment (more on that in a second).
We tell conda what software to put in that virtual environment using the rest of the line (
python==3.7 pandas h5py pytz obspy). We want python 3.7 specifically (hence
python==3.7), and then the latest release of pandas, h5py, pytz, and obspy. This will install several other dependencies, notably numpy which is the library we really care about because it allows us to do math on arrays.
Then, we activate our virtual environment using
conda activate readgssi which allows us to operate in a “virtual environment” which is basically a python space where you can install dependencies without messing with the functionality of python on the rest of your machine. Now that we’re in the virtual environment, we can install things using
pip, the python package manager.
pip install readgssi will install the readgssi version available on the Python Package Index (PyPI) into your readgssi environment, but nowhere else. This is useful but can be confusing: if you try to run readgssi from outside the virtual environment you just made, you will not be able to find it! The reason it’s useful is that it doesn’t modify the version of python or packages that your computer may use for system tasks (no one likes obscure errors, so we try to avoid them…and one of the best ways of doing that is by using virtual environments). To get back into the readgssi environment you created, simply do
conda activate readgssi.
1.2.3. Installing from source¶
If you choose to install a specific commit rather than the latest working release of this software, I recommend doing so via the following commands:
conda config --add channels conda-forge conda create -n readgssi python==3.7 pandas h5py pytz obspy conda activate readgssi pip install git+https://github.com/iannesbitt/readgssi
If you plan on modifying the code and installing/reinstalling once you’ve made changes, you can do something similar to the following, assuming you have conda dependencies installed:
cd ~ git clone https://github.com/iannesbitt/readgssi # make code changes if you wish, then: pip install ~/readgssi
1.2.4. Installing onto armv7l architecture¶
This has not been tested (though will be in the future), but installing on the Raspberry Pi and other ARM processors should be possible in theory. Start with this:
# from https://github.com/obspy/obspy/wiki/Installation-on-Linux-via-Apt-Repository deb http://deb.obspy.org stretch main wget --quiet -O - https://raw.github.com/obspy/obspy/master/misc/debian/public.key | sudo apt-key add - sudo apt-get update sudo apt-get install python-obspy python3-obspy sudo apt-get install ttf-bistream-vera rm -rf ~/.matplotlib ~/.cache/matplotlib sudo apt-get install python-pandas python-h5py pip install -U pytz pynmea2 geopy readgssi
Install and test readgssi on armv7l architecture
There is no testing module as such yet, but a simple test will ensure that most things are working properly:
readgssi -V # this will display the version readgssi -h # this will display the help text
If it’s working, head over to General usage.
Create a testing module and routines.