Licence

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Installation

Dependencies

stdb
obspy

Conda environment

We recommend creating a custom conda environment where OBStools can be installed along with its dependencies.

conda create -n obs -c conda-forge python=3.12 obspy

Activate the newly created environment:

conda activate obs

Install dependency:

pip install git+https://github.com/schaefferaj/stdb

Installing development branch on GitHub

pip install git+https://github.com/nfsi-canada/obstools

Installing from source

Clone the repository:

git clone https://github.com/paudetseis/OBStools.git
cd OBStools

Install using pip:

pip install .

Using local data

The various scripts packaged with OrientPy use FDSN web services through and ObsPy Client to load waveform data. For waveform data locally stored on your hard drive, the scripts can use a Client that reads a SeisComP Data Structure archive containing SAC or miniSEED waveform data. Check out the scripts bng_calc and dl_calc below and the argument --local-data and --dtype for more details.

Station Metadata

If you have data stored locally on your drive, it is likely you also have a station XML file containing the metadata. The corresponding ObsPy documentation is here.

To convert the station XML file to an input that can be read by OrientPy, you run the command gen_stdb station.xml (only available on StDb version 0.2.7), which will create the file station.pkl. If you don’t have a station XML file but you have a dataless SEED file, you can convert it first to XML using this tools.

Waveform Data

The SDS folder containing the waveform data has the structure:

archive
  + year
    + network code
      + station code
        + channel code + type
          + one file per day and location, e.g. NET.STA.LOC.CHAN.TYPE.YEAR.DOY

For example:

SDS/
  2014/
    YH/
      LOBS3/
        HH1.D/
          YH.LOBS3..CH1.D.2014.332
          ...

Note, the filename does not include the extension (.MSEED or .SAC), and the characters .D (for type Data) that appear in both the channel code and the filename. Note also the two dots (..). If there is a location code, it should appear between those dots (e.g., for a location code 10, the corresponding filename should be YH.LOBS3.10.HH1.D.2014.332). There is no location code for the YH.LOBS3 data, and this field is simply absent from the filenames. Finally, the day-of-year (DOY) field must be zero-padded to be exactly 3 characters.