Merge pull request #31 from leewujung/master

Added EK60 model class and methods

docs/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 8cb741cee45ed58d00396b6bf7633242
+config: f4592810de280cb48e0d2f1645d82d30
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/data-format.rst.txt

@@ -1,22 +1,70 @@
 Data Format
 ===============
 
-The lack of interoperability among data collected by different sonar systems is currently a major obstacle in integrative analysis of sonar data at large scales.
+The lack of interoperability among data collected by different sonar
+systems is currently a major obstacle in integrative analysis of sonar
+data at large scales.
 
-echopype addresses this problem by creating tools for converting data from manufacturer-specific formats into a common, interoperable [netCDF](https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_introduction.html) file format. NetCDF is the [current defacto standard](https://clouds.eos.ubc.ca/~phil/courses/parallel_python/02_xarray_zarr.html) in climate research and is supported by many powerful Python packages for efficient computation.
+echopype addresses this problem by creating tools for converting data
+from manufacturer-specific formats into a common, interoperable
+`netCDF <https://www.unidata.ucar.edu/software/netcdf/docs/
+netcdf_introduction.html>`_ file format.
+NetCDF is the `current defacto standard <https://clouds.eos.ubc.ca/
+~phil/courses/parallel_python/02_xarray_zarr.html>`_ in climate
+research and is supported by many powerful Python packages for
+efficient computation.
 
-### Common file format
-Currently echopype use a modified form of the [ICES SONAR-netCDF4 convention](http://www.ices.dk/sites/pub/Publication%20Reports/Cooperative%20Research%20Report%20(CRR)/CRR341/CRR341.pdf) as the common data format to which all data can be converted to. This convention is actually pretty new (released in mid 2018) and we think modification is needed to leverage functionalities of many powerful Python libraries. Detail of the modification is discussed [below](#modification-to-the-SONAR-netCDF4-convention). We consider switching to using [zarr](https://zarr.readthedocs.io/en/stable/) for cloud-optimized data storage and access in the future.
 
-### Supported file types
-In the first stage of development (until spring 2019), we plan to support data conversion for three sonar systems commonly found on research vessels:
+Interoperable netCDF file
+--------------------------
+
+echopype use a modified form of the `ICES SONAR-netCDF4 convention
+<http://www.ices.dk/sites/pub/Publication%20Reports/
+Cooperative%20Research%20Report%20(CRR)/CRR341/CRR341.pdf>`_ as the
+interoperable data format to which all data can be converted to.
+This convention is very recently proposed (mid 2018) and we made
+critical modifications to the data storage structure so that
+the underlying computation can take full advantage of the power of
+xarray in manipulating labelled multi-dimensional arrays. Detail of
+the modification is discussed a separate section below. We also
+consider switching to use `zarr <https://zarr.readthedocs.io/en/stable/>`_
+in the future for cloud-optimized data storage and access.
+
+
+Supported file types
+----------------------
+
+In the first stage of development (until spring 2019), we plan to
+support data conversion for three sonar systems commonly found on
+research vessels and moorings:
 - `.raw` files from Simrad EK60 narrowband echosounder
 - `.raw` files from Simrad EK80 broadband echosounder
 - `.01A` files from ASL Environmental Sciences AZFP echosounder
 
-We plan to support conversion of *raw beam* data from common Acoustic Doppler Current Profilers (ADCPs) and echo data from multibeam sonar in the next stage of development.
+We plan to support conversion of *raw beam* data from common Acoustic
+Doppler Current Profilers (ADCPs) and echo data from multibeam sonar
+in the next stage of development.
 
-### Modification to the SONAR-netCDF4 convention
-We modified how backscatter data (the sonar echoes) are stored in a netCDF file. In the SONAR-netCDF4 convention, backscatter data from each sonar beam are stored in separate `Beam` subgroups under the `Sonar` group. This was designed to accommodate potential differences in the recorded echo lengths across different channels. Specifically, the number of bins and bin size along range (which corresponds to depth in most cases) may differ. However, this form of storage is not the most efficient if the number of bins and bin size are the same. If these parameters are identical, it is much more convenient to store and access data as a multi-dimensional array indexed by time, range, *and* frequency or beam direction (for multibeam data).
+Modifications to SONAR-netCDF4
+----------------------------------------------
+We modified how backscatter data (the sonar echoes) are stored in a
+netCDF file. In the SONAR-netCDF4 convention, backscatter data from
+each sonar beam are stored in separate ``Beam`` subgroups under the
+``Sonar`` group. This was designed to accommodate potential
+differences in the recorded echo lengths across different channels.
+Specifically, the number of bins and bin size along range
+(which corresponds to depth in most cases) may differ. However, this
+form of storage is not the most efficient if the number of bins and
+bin size are the same. If these parameters are identical, it is much
+more convenient to store and access data as a multi-dimensional array
+indexed by time, range, *and* frequency or beam direction (for
+multibeam data).
 
-echopype handles this by adaptively switching the storage format depending on the range bin parameters. This is not a perfect solution, since this means that all subsequent computation needs to be adaptive as well. However this is an acceptable solution, since many popular analysis routines operate on top of heavily averaged and interpolated echo data, instead of the *raw* data discussed here. At that stage, data across frequency or channel are required to have the dimensions and coordinates.
+echopype handles this by adaptively switching the storage format
+depending on the range bin parameters. This is not a perfect solution,
+since this means that all subsequent computation needs to be adaptive
+as well. However this is an acceptable solution, since many popular
+analysis routines operate on top of heavily averaged and interpolated
+echo data, instead of the *raw* data discussed here. At that stage,
+data across frequency or channel are required to have the dimensions
+and coordinates.

docs/build/html/_sources/other-resources.rst.txt

@@ -1,18 +1,35 @@
 Other Resources
 ==================
 
-Below is a list of existing software resources for processing sonar data. When appropriate we note whether the software is proprietary or open-source, and in which language it is written.
+Below is a list of existing software resources for processing sonar data.
+When appropriate we note whether the software is proprietary or open-source,
+and in which language it is written.
 
-- `EchoView <https://www.echoview.com/>`_: GUI-based proprietary software, current go-to tool for echosounder data analysis
+- `EchoView <https://www.echoview.com/>`_: GUI-based proprietary software,
+  current go-to tool for echosounder data analysis
 
-  - `EchoView R <https://github.com/AustralianAntarcticDivision/EchoviewR>`_: interfacing R and EchoView
+  - `EchoView R <https://github.com/AustralianAntarcticDivision/EchoviewR>`_:
+    interfacing R and EchoView,
+    related `paper <https://www.frontiersin.org/articles/10.3389/
+    fmars.2015.00015/full>`_
+
+- `Echogram <https://CRAN.R-project.org/package=echogram>`_: an R package for
+  reading data in the `HAC <http://www.ices.dk/sites/pub/Publication%20Reports/
+  Cooperative%20Research%20Report%20%28CRR%29/crr278/crr278.pdf>`_ format
 
-- `Echogram <https://CRAN.R-project.org/package=echogram>`_: an R package for reading data in the `HAC <http://www.ices.dk/sites/pub/Publication%20Reports/Cooperative%20Research%20Report%20%28CRR%29/crr278/crr278.pdf>`_ format
 - `ESP3 <https://bitbucket.org/echoanalysis/esp3/overview>`_: a Matlab toolbox
+
 - `LSSS <https://cmr.no/projects/10396/lsss/>`_ (Large Scale Survey System)
-- `MATECHO <https://usermanual.wiki/Pdf/MatechoUserManual18052017.963673607.pdf>`_: requires MATLAB and Movies3D
 
-  - `Movies3D <http://flotte.ifremer.fr/content/download/6032/129677/file/MOVIES3D_general.pdf>`_: reads and writes HAC files and is capable of joining EK60 and ME70 data
+- `MATECHO <https://usermanual.wiki/Pdf/MatechoUserManual18052017.963673607.pdf>`_:
+  requires MATLAB and Movies3D
+
+  - `Movies3D <http://flotte.ifremer.fr/content/download/6032/129677/file/
+    MOVIES3D_general.pdf>`_: reads and writes HAC files and is capable of
+    joining EK60 and ME70 data
+
+- `PyEchoLab <https://drive.google.com/drive/folders/
+  1q2ddkBx1cathE-6V_bIjqLBQj4yX7csm?usp=sharing>`_: a Python package based
+  solely on the NumPy library
 
-- `PyEchoLab <https://drive.google.com/drive/folders/1q2ddkBx1cathE-6V_bIjqLBQj4yX7csm?usp=sharing>`_: a Python package based solely on the NumPy library
 - `Sonar4 and Sonar5-Pro <http://folk.uio.no/hbalk/sonar4_5/index.htm>`_