From 4ee5d133f44b36967ce45d681add97b900a2b574 Mon Sep 17 00:00:00 2001 From: Wu-Jung Lee Date: Sun, 5 Apr 2020 20:33:12 -0400 Subject: [PATCH 1/3] change setGroups to be a simple function rather than a class --- echopype/convert/utils/set_groups.py | 46 ++++++++++++++-------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/echopype/convert/utils/set_groups.py b/echopype/convert/utils/set_groups.py index be33704d2..6ea0e14b1 100644 --- a/echopype/convert/utils/set_groups.py +++ b/echopype/convert/utils/set_groups.py @@ -7,28 +7,28 @@ from .set_groups_azfp import SetGroupsAZFP -class SetGroups: - def __new__(cls, file_path, echo_type, compress=True): - """Wrapper class to use for setting groups in .nc files. +def SetGroups(file_path, echo_type, compress=True): + """Wrapper function to set groups in converted files. - Parameters - ---------- - file_path : str - Path to .nc file to be generated - echo_type: str - Type of echosounder from which data were generated - compress: bool - Whether or not to compress the backscatter data - Returns - ------- - Returns a specialized SetGroups object depending on - the type of echosounder - """ + Parameters + ---------- + file_path : str + Path to .nc file to be generated + echo_type: str + Type of echosounder from which data were generated + compress: bool + Whether or not to compress the backscatter data - # Returns specific EchoData object - if echo_type == "EK60": - return SetGroupsEK60(file_path, compress) - elif echo_type == "AZFP": - return SetGroupsAZFP(file_path, compress) - else: - raise ValueError("Unsupported file type") + Returns + ------- + Returns a specialized SetGroups object depending on + the type of echosounder + """ + + # Returns specific SetGroup object + if echo_type == "EK60": + return SetGroupsEK60(file_path, compress) + elif echo_type == "AZFP": + return SetGroupsAZFP(file_path, compress) + else: + raise ValueError("Unsupported file type") From 2cc1400d29d935486fcd324b27be3334cf1c1527 Mon Sep 17 00:00:00 2001 From: Wu-Jung Lee Date: Sun, 5 Apr 2020 21:38:15 -0400 Subject: [PATCH 2/3] update docs --- README.rst | 9 +++--- docs/source/index.rst | 9 +++--- docs/source/resources.rst | 11 +++++++ docs/source/usage.rst | 63 ++++++++++++++++++++++++++++++++++++++- 4 files changed, 83 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index e5b326b64..ef8402d83 100644 --- a/README.rst +++ b/README.rst @@ -72,11 +72,12 @@ Watch the `echopype talk`_ at SciPy 2019 for background, discussions and a quic Contributors ------------ -`Wu-Jung Lee `_ (@leewujung) and -`Kavin Nguyen `_ (@ngkavin) -are primary developers of this project. +`Wu-Jung Lee `_ (@leewujung) leads this project +and along with `Kavin Nguyen `_ (@ngkavin) +are primary developers of this package. `Valentina Staneva `_ (@valentina-s) -provides consultation and also contributes to development. +and `Emilio Mayorga `_ (@emiliom) +provide consultation and also contribute to the development. Other contributors are listed `here `_. We thank Dave Billenness of ASL Environmental Sciences for diff --git a/docs/source/index.rst b/docs/source/index.rst index 7028e58ce..4e8e7303a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -33,11 +33,12 @@ scientists to make discovery using these new data. Contributors ------------ -`Wu-Jung Lee `_ (@leewujung) and -`Kavin Nguyen `_ (@ngkavin) -are primary developers of this project. +`Wu-Jung Lee `_ (@leewujung) leads this project +and along with `Kavin Nguyen `_ (@ngkavin) +are primary developers of this package. `Valentina Staneva `_ (@valentina-s) -provides consultation and also contributes to development. +and `Emilio Mayorga `_ (@emiliom) +provide consultation and also contribute to the development. Other contributors include: `Frederic Cyr `_ (@cyrf0006), diff --git a/docs/source/resources.rst b/docs/source/resources.rst index cfdde5085..54c5fca8b 100644 --- a/docs/source/resources.rst +++ b/docs/source/resources.rst @@ -1,6 +1,9 @@ Other Resources ================ +Software +-------- + Below is a list of software resources for processing ocean sonar data. When appropriate, we note whether the software is proprietary or open-source, as well as the programming language in which it is written. @@ -30,3 +33,11 @@ as well as the programming language in which it is written. an open-source Python package based solely on the NumPy library - `Sonar4 and Sonar5-Pro `_ + + +Echosounder information +----------------------- + +- `ASL Environemntal Sciences Acoustic Zooplankton Fish Profiler (AZFP) `_ +- `Kongsberg Simrad EK60 `_ +- `Kongsberg Simrad EK80 `_ \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 7d81a5a93..22aa03493 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -346,13 +346,74 @@ sample, and range. The updated values can be retrieved with: ed.sample_thickness # sample spatial resolution in [m] ed.range # range for each sonar sample in [m] +For EK60 data, echopype updates the sound speed and seawater absorption +using the formulae from Mackenzie (1981) [2]_ and +Ainslie and McColm (1981) [3]_, respectively. + +For AZFP data, echopype updates the sound speed and seawater absorption +using the formulae provided by the manufacturer ASL Environmental Sci. + + + + + +Calibration parameters +~~~~~~~~~~~~~~~~~~~~~~ + +*Calibration* here refers to the calibration of transducers on an +echosounder, which finds the mapping between the voltage signal +recorded by the echosounder and the actual (physical) acoustic pressure +received at the transducer. This mapping is critical in deriving biological +quantities from acoustic measurements, such as estimating biomass. +More detail about the calibration procedure can be found in [4]_. + +Echopype by default uses calibration parameters stored in the converted +files along with the backscatter measurements and other metadata parsed +from the raw data file. +However, since careful calibration is often done separately from the +data collection phase of the field work, accurate calibration parameters +are often supplied in the post-processing stage. +Currently echopypy allows users to overwrite calibration parameters for +EK60 data, including ``sa_correction``, ``equivalent_beam_angle``, +and ``gain_correction``. + +As an example, to reset the equivalent beam angle for 18 kHz only, +one can do: + +.. code-block:: python + + ed.equivalent_beam_angle.loc[dict(frequency=18000)] = -18.02 # set value for 18 kHz only + +To set the equivalent beam angle for all channels at once, do: + +.. code-block:: python + + ed.equivalent_beam_angle = [-17.47, -20.77, -21.13, -20.4 , -30] # set all channels at once + +Make sure you use ``ed.equivalent_beam_angle.frequency`` to check +the sequence of the frequency channels first, and always double +check after setting these parameters! + + + --------------- -.. [1] De Robertis and Higginbottoms (2007) A post-processing technique to +.. [1] De Robertis A, Higginbottoms I. (2007) A post-processing technique to estimate the signal-to-noise ratio and remove echosounder background noise. `ICES J. Mar. Sci. 64(6): 1282–1291. `_ +.. [2] Mackenzie K. (1981) Nine‐term equation for sound speed in the oceans. + `J. Acoust. Soc. Am. 70(3): 806-812 `_ + +.. [3] Ainslie MA, McColm JG. (1998) A simplified formula for viscous and + chemical absorption in sea water. + `J. Acoust. Soc. Am. 103(3): 1671-1672 `_ + +.. [4] Demer DA, Berger L, Bernasconi M, Bethke E, Boswell K, Chu D, Domokos R, + et al. (2015) Calibration of acoustic instruments. `ICES Cooperative Research Report No. + 326. 133 pp. `_ + .. TODO: Need to specify the changes we made from AZFP Matlab code to here: In the Matlab code, users set temperature/salinity parameters in AZFP_parameters.m and run that script first before doing unpacking. From 63fc8467d9c8a2c60e08489906c23660778c5de1 Mon Sep 17 00:00:00 2001 From: Wu-Jung Lee Date: Sun, 5 Apr 2020 22:04:40 -0400 Subject: [PATCH 3/3] add info about EK80 into docs --- README.rst | 4 ++++ docs/source/usage.rst | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index ef8402d83..a2a974144 100644 --- a/README.rst +++ b/README.rst @@ -30,6 +30,10 @@ Echopype currently supports file conversion and computation of data produced by: - Simrad EK60 echosounder (``.raw`` files) - ASL Environmental Sciences AZFP echosounders (``.01A`` files) +In the `ek80 `_ development branch +we are actively developing file conversion and processing routines +such as pulse compression and calibration for the broadband Simrad EK80 ``.raw`` files. + The file conversion functionality converts data from manufacturer-specific binary formats into a standardized netCDF files, based on which all subsequent computations are performed. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 22aa03493..d0af8fe45 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -48,7 +48,7 @@ into netCDF (stable) or zarr (beta) files. In the `ek80 `_ development branch we are actively developing file conversion and processing routines -such as pulse compression and calibration for the broadband Simrad EK80 ``.raw`` file. +such as pulse compression and calibration for the broadband Simrad EK80 ``.raw`` files. We are considering implementing calibration routines for *raw beam* data from common-found Acoustic Doppler Current Profilers (ADCPs).