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.earthscope.org/irisws/fedcatalog/1/datacenters?format=html>__ available through the EarthScope fedcatalog <https://service.earthscope.org/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 Miniforge <https://github.com/conda-forge/miniforge?tab=readme-ov-file#install>__ first, if necessary)

   .. code-block:: xml

   mamba env create --file environment.yml 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 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 :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

To install sonify's development packages, with your environment activated run

.. code-block:: xml

pip install --requirement requirements.txt

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