Merge pull request #47 from paudetseis/v021

V021

Author: paudetseis

.github/workflows/deploy.yml

@@ -52,22 +52,22 @@ jobs:
       #     pytest -v --cov=orientpy ../orientpy/tests/
       #     bash <(curl -s https://codecov.io/bash)
 
-      - name: Make docs
-        if: matrix.python-version == '3.12' 
-        shell: bash -l {0}
-        run: |
-          cd docs
-          conda install sphinx
-          pip install sphinx_rtd_theme
-          make html
-          touch _build/html/.nojekyll
-          cd ..
+      # - name: Make docs
+      #   if: matrix.python-version == '3.12' 
+      #   shell: bash -l {0}
+      #   run: |
+      #     cd docs
+      #     conda install sphinx
+      #     pip install sphinx_rtd_theme
+      #     make html
+      #     touch _build/html/.nojekyll
+      #     cd ..
 
-      - name: Deploy 🚀
-        if: matrix.python-version == '3.12' 
-        uses: JamesIves/[email protected]
-        with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BRANCH: gh-pages # The branch the action should deploy to.
-          FOLDER: docs/_build/html # The folder the action should deploy.
-          CLEAN: true # Automatically remove deleted files from the deploy branch
+      # - name: Deploy 🚀
+      #   if: matrix.python-version == '3.12' 
+      #   uses: JamesIves/[email protected]
+      #   with:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #     BRANCH: gh-pages # The branch the action should deploy to.
+      #     FOLDER: docs/_build/html # The folder the action should deploy.
+      #     CLEAN: true # Automatically remove deleted files from the deploy branch

docs/conf.py

@@ -29,7 +29,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode']
 
 autodoc_member_order = 'bysource'
 

docs/index.rst

@@ -17,8 +17,6 @@ used in command-line scripts.
    :target: https://doi.org/10.5281/zenodo.3905414
 .. image:: https://travis-ci.com/paudetseis/RfPy.svg?branch=master
     :target: https://travis-ci.com/paudetseis/RfPy
-.. image:: https://codecov.io/gh/paudetseis/RfPy/branch/master/graph/badge.svg
-    :target: https://codecov.io/gh/paudetseis/RfPy
 
 .. note::
 
@@ -33,9 +31,6 @@ used in command-line scripts.
    * ``RfData`` objects are used to calculate single-station and single-event receiver 
      functions, whereas ``rf`` can handle multiple stations at once. 
 
-.. warning::
-   ``RfPy`` was recently updated to fix a problem when running the scripts under Windows OS. The consequence is that version ``0.1.1`` will throw an error if the extension .py is specified when calling the scripts. The accompanying documentation also uses version ``0.2.1`` of ``StDb`` in the Tutorials section.
-
 .. toctree::
    :maxdepth: 1
    :caption: Quick Links

docs/rfpy.rst

@@ -58,7 +58,7 @@ Install the `StDb` dependency using ``pip`` inside the ``rfpy`` environment:
 
 .. sourcecode:: bash
 
-   pip install stdb
+   pip install stdb@git+https://github.com/schaefferaj/stdb
 
 Installing from GitHub development branch
 -----------------------------------------
@@ -83,6 +83,59 @@ Installing from source
 
    pip install .
 
+Using local data
+================
+
+The main script packaged with ``RfPy`` uses 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 <https://docs.obspy.org/packages/autogen/obspy.clients.filesystem.sds.html>`_ archive containing SAC or miniSEED waveform data. Check out the scripts ``rfpy_calc`` below and the argument ``--SDS-path`` 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 <https://www.fdsn.org/xml/station/>`_ file
+containing the metadata. The corresponding ObsPy documentation is
+`here <https://docs.obspy.org/packages/obspy.core.inventory.html>`_. 
+
+You can now use a stationXML (`.xml`) file instead of the StDb `.pkl` format. 
+Alternatively, you can convert the stationXML file to an StDb `.pkl` file
+by running the command ``gen_stdb station.xml`` (these options are only
+available on StDb version 0.2.7. 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 <https://seiscode.iris.washington.edu/projects/stationxml-converter>`_.
+
+.. note::
+   Please note that using the stationXML directly as input means you cannot
+   correct the orientation of H1 and H2 components using the azimuth correction term stored as ``azcorr`` in the StDb file, as this information is not stored in the stationXML file. 
+
+Waveform Data
+-------------
+
+The SDS folder containing the waveform data has the structure:
+
+.. code-block:: python
+
+   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:
+
+.. code-block:: python
+
+   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.
+
 Basic Usage
 ===========