pyTremor/sonify

*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
`__
available through the Incorporated Research Institutions for Seismology (IRIS)
Data Management Center (DMC) `fedcatalog
`__ web service.

|screenshot|

*sonify* `won an Honorable Mention
`__ in the 2020 SciPy `John
Hunter Excellence in Plotting Contest (JHEPC) `__.

Quickstart
----------

1. Obtain

.. code-block:: xml

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

2. Create environment, install, and activate (`install conda
`__
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 `__. 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
`__ (preferred) or email me at
|liam@liam.earth|_. You are also welcome to create a `pull request
`__.
Please don't allow `imposter 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