pyTremor/sonify/README.rst

*sonify*
========

|docs_badge| |build_badge| |cov_badge| |black_badge| |isort_badge|

*sonify* “squeezes” seismic or infrasound signals into audible frequencies and
creates animated spectrograms to accompany the audio. Data are pulled from any
of the `FDSN data centers
<https://service.iris.edu/irisws/fedcatalog/1/datacenters?format=html>`__
available through the Incorporated Research Institutions for Seismology (IRIS)
Data Management Center (DMC) `fedcatalog
<https://service.iris.edu/irisws/fedcatalog/docs/1/help/>`__ web service.

|screenshot|

*sonify* `won an Honorable Mention
<https://jhepc.github.io/2020/entry_11/index.html>`__ in the 2020 SciPy `John
Hunter Excellence in Plotting Contest (JHEPC) <https://jhepc.github.io/>`__.

Quickstart
----------

1. Obtain

   .. code-block:: xml

     git clone https://github.com/liamtoney/sonify.git
     cd sonify

2. Create environment, install, and activate (`install conda
   <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`__
   first, if necessary)

   .. code-block:: xml

     conda env create
     conda activate sonify

3. Run using the Python interpreter

   .. code-block:: python

     python
     >>> from sonify import sonify

   or via the command-line interface

   .. code-block:: xml

     sonify --help

Example
-------

To make a movie of the seismic signal generated by a massive avalanche
occurring in Alaska on 21 June 2019, sped up by a factor of 200:

.. code-block:: python

   from sonify import sonify
   from obspy import UTCDateTime

   sonify(
       network='AV',
       station='ILSW',
       channel='BHZ',
       starttime=UTCDateTime(2019, 6, 20, 23, 10),
       endtime=UTCDateTime(2019, 6, 21, 0, 30),
       freqmin=1,
       freqmax=23,
       speed_up_factor=200,
       fps=1,  # Use fps=60 to ~recreate the JHEPC entry (slow to save!)
       spec_win_dur=8,
       db_lim=(-180, -130),
   )

Or (equivalently), via the command-line interface:

.. ~BEGIN~
.. code-block:: xml

  sonify AV ILSW BHZ 2019-06-20T23:10 2019-06-21T00:30 --freqmin 1 --freqmax 23 --speed_up_factor 200 --fps 1 --spec_win_dur 8 --db_lim -180 -130
.. ~END~

The result is a 4K 1fps video file named ``AV_ILSW_BHZ_200x.mp4``. A screenshot
of the movie is shown at the top of this README.

Documentation
-------------

Application programming interface (API) documentation for the module is available
`here <https://sonify.readthedocs.io/en/latest/sonify.html>`__. For command-line
usage instructions, type ``sonify --help`` (the ``sonify`` conda environment must
be active).

.. |docs_badge| image:: https://readthedocs.org/projects/sonify/badge/?version=latest
   :alt: Documentation status
   :target: https://sonify.rtfd.io/

.. |build_badge| image:: https://github.com/liamtoney/sonify/actions/workflows/build.yml/badge.svg
   :alt: Build status
   :target: https://github.com/liamtoney/sonify/actions/workflows/build.yml

.. |cov_badge| image:: https://codecov.io/gh/liamtoney/sonify/branch/main/graph/badge.svg?token=3OIGM34OFL
   :alt: Test coverage
   :target: https://codecov.io/gh/liamtoney/sonify

.. |black_badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :alt: Link to Black
   :target: https://black.readthedocs.io/en/stable/

.. |isort_badge| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
   :alt: Link to isort
   :target: https://pycqa.github.io/isort/

.. |screenshot| image:: screenshot.png
   :alt: Screenshot of example
   :target: #example

Contributing
------------

If you notice a bug with *sonify* (or if you'd like to request/propose a new
feature), please `create an issue on GitHub
<https://github.com/liamtoney/sonify/issues/new>`__ (preferred) or email me at
|liam@liam.earth|_. You are also welcome to create a `pull request
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`__.
Please don't allow `imposter syndrome
<https://en.wikipedia.org/wiki/Impostor_syndrome>`__ to obstruct you from
contributing your valuable ideas and skills to this project — **I'm happy to help
you contribute in any way I can.**

.. |liam@liam.earth| replace:: ``liam@liam.earth``
.. _liam@liam.earth: mailto:liam@liam.earth