diff --git a/docs/source/acoustics.rst b/docs/source/acoustics.rst new file mode 100644 index 00000000..6d7715ce --- /dev/null +++ b/docs/source/acoustics.rst @@ -0,0 +1,24 @@ +.. _acoustics: + +Passive Acoustics Module +======================== +The acoustics module contains a set of functions to injest hydrophone *.wav* files. +Only available in MHKiT-Python in v0.9 or later. + +API Documentation +-------------------- +- `Python Acoustics API Documentation `_ +- MATLAB support is planned in an upcoming release + +Examples +-------------- + +- `Passive Acoustics Example `_ + +The acoustics module contains the following submodules: + +* ``io``: Contains functions to read and output *.wav* files +* ``analysis``: Contains functions to process, clean and analyze passive acoustics data +* ``graphics``: Contains functions to plot spectral data + +See :ref:`MHKiT-Python ` for more details on the acoustics module. diff --git a/docs/source/api.rst b/docs/source/api.rst index c8ea94ec..208ac9ad 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -19,6 +19,7 @@ MHKiT-Python API mhkit-python/api.dolfyn mhkit-python/api.mooring mhkit-python/api.utils + mhkit-python/api.acoustics .. _apidoc_matlab: diff --git a/docs/source/mhkit-python/api.acoustics.rst b/docs/source/mhkit-python/api.acoustics.rst new file mode 100644 index 00000000..080ab1ce --- /dev/null +++ b/docs/source/mhkit-python/api.acoustics.rst @@ -0,0 +1,68 @@ +.. _acoustics_api: + +Passive Acoustics Module +^^^^^^^^^^^^^^^^^^^^^^^^ +The passive acoustics module contains a set of functions +for analyzing and visualizing passive acoustic monitoring +data deployed in water bodies. This package reads in raw +*.wav* files and conducts basic acoustics analysis and +visualization. + +To start using the module, import it directly from MHKiT: +``from mhkit import acoustics``. The analysis functions +are available directly from the main import, while the +I/O and graphics submodules are available from +``acoustics.io`` and ``acoustics.graphics``, respectively. + +I/O submodule +""""""""""""" +There is one primary function of the I/O submodule that +can be used to read in *.wav* files output by hydrophones, +``acoustics.io.read_hydrophone``. There are a couple +manufacturer specific wrappers around this function, as +well as one to export audio back into a *.wav* file. + +.. autosummary:: + :nosignatures: + + ~mhkit.acoustics.io.read_hydrophone + ~mhkit.acoustics.io.read_soundtrap + ~mhkit.acoustics.io.read_iclisten + ~mhkit.acoustics.io.export_audio + + +Analysis submodule +"""""""""""""""""" +Analysis functions are stored in the analysis submodule, +accessed directly from ``mhkit.acoustics``. These functions +are intended to be used on top of the I/O submodule, and +include functionality to calibrate data, create spectral +densities, sound pressure levels, and time or band +aggregate spectral data. + +.. autosummary:: + :nosignatures: + + ~mhkit.acoustics.minimum_frequency + ~mhkit.acoustics.sound_pressure_spectral_density + ~mhkit.acoustics.apply_calibration + ~mhkit.acoustics.sound_pressure_spectral_density_level + ~mhkit.acoustics.band_aggregate + ~mhkit.acoustics.time_aggregate + ~mhkit.acoustics.sound_pressure_level + ~mhkit.acoustics.third_octave_sound_pressure_level + ~mhkit.acoustics.decidecade_sound_pressure_level + + +Graphics submodule +"""""""""""""""""" +The graphics submodule provides functions for plotting +spectograms (frequency vs time) and spectra (psd vs frequency). +These functions are fully configurable via matplotlib +and can be pulled into existing plotting frameworks. + +.. autosummary:: + :nosignatures: + + ~mhkit.acoustics.graphics.plot_spectogram + ~mhkit.acoustics.graphics.plot_spectra diff --git a/docs/source/module.rst b/docs/source/module.rst index 571085ca..c990afef 100644 --- a/docs/source/module.rst +++ b/docs/source/module.rst @@ -17,3 +17,4 @@ This section gives an overview of the functionality available within each of MHK dolfyn.rst mooring.rst utils.rst + acoustics.rst