.. _tools_to_access_adcp_data:


Tools to access ADCP data
---------------------------

|

.. NOTE:: A scientist with an existing UHDAS dataset who
          wants to use Matlab to access the ADCP data
          should look

          - :ref:`here <read_netcdf>` to read netCDF files
          - :ref:`here <read_getmat>` to read 'allbins*.mat' files



The following mechanisms exist for directly accessing data (into a program)

  - The **CODAS database** can only be accessed with Python (direct
    read) or executables (read and write to disk).  Python can also
    read the netCDF files.  "Matlab access to the data" means reading
    netCDF files pr ``*.mat`` files.

  - Binary **raw ADCP data** can be accessed by both Matlab and Python.


Useful data products are scattered througout the UHDAS cruise directory,
in the individual sonar processing directories, eg. **vg0810/proc/os75nb**
in these locations:


+-----------------------------------------------+-----------------------------+
|        **data**                               |  **files to use**           |
+-----------------------------------------------+-----------------------------+
|  every bin and every profile (netCDF)         |   ``contour/*.nc``          |
|  every bin and every profile (matlab)         |   ``contour/allbins_*.mat`` |
+-----------------------------------------------+-----------------------------+
|  coarse resolution averaged ocean velocity    |   ``vector/vect*.mat``      |
+-----------------------------------------------+-----------------------------+
|  moderate resolution averaged ocean velocity  |   ``contour/cont*.mat``     |
+-----------------------------------------------+-----------------------------+
|  every bin and every profile (CODAS database) |   ``adcpdb/a*.blk``         |
+-----------------------------------------------+-----------------------------+
|  figures from the cruise                      |   ``png_archive/*.png``     |
+-----------------------------------------------+-----------------------------+





|
|

    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    |  data source     | what you get            |  python program                          |  matlab program                           | C-code executable or Python script          |
    |                  |                         |                                          |                                           | (extract to disk)                           |
    +==================+=========================+==========================================+===========================================+=============================================+
    | UHDAS ``*.raw``  | beam coords singleping, |  :ref:`Multiread <python_read_raw>`      | :ref:`read.m <matlab_read_raw>`           |        NA                                   |
    |                  | no navigation           |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    | UHDAS ``*.raw``  | earth coords singleping |                                          |                                           |        NA                                   |
    |                  | with navigation,        |      NA                                  | :ref:`get_xfraw.m <matlab_read_xfraw>`    |                                             |
    |                  | with heading            |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    | VmDAS ``*.ENR``  | beam coords singleping  | :ref:`Multiread <python_read_raw>`       | :ref:`read.m <matlab_read_raw>`           |        NA                                   |
    |                  | no navigation,          |                                          |                                           |                                             |
    |                  | no heading              |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    | VmDAS ``*.ENS``  | beam coords singleping  |  :ref:`Multiread <python_read_raw>`      | :ref:`read.m <matlab_read_raw>`           |        NA                                   |
    |                  | with navigation,        |                                          |                                           |                                             |
    |                  | no heading              |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    | VmDAS ``*.ENX``  | earth coords singleping | :ref:`Multiread <python_read_raw>`       |  :ref:`read.m <matlab_read_raw>`          |        NA                                   |
    |                  | with navigation,        |                                          |                                           |                                             |
    |                  | with heading            |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    | VmDAS ``*.STA``, | earth coords averaged   | :ref:`Multiread <python_read_raw>`       | :ref:`read.m <matlab_read_raw>`           |        NA                                   |
    |  ``*.LTA``       |                         |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    |                  |  **matlab files**       |                                          |                                           |                                             |
    | CODAS database   | earth coordinates:      |        NA                                |       NA                                  | :ref:`adcpsect <extract_adcpsect>`          |
    |                  | (further averaged)      |                                          |                                           | (extract files to disk)                     |
    |                  | time, lon, lat          |                                          |                                           | ``contour_xy.mat``, ``contour_uv.mat``      |
    |                  | ocean velocities        |                                          |                                           | :ref:`file description <read_adcpsect>`     |
    |                  |                         |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    |                  |  **matlab files**       |                                          |                                           |                                             |
    | CODAS database   | earth coordinates:      | :ref:`get_profiles <python_read_codas>`  |  download ``load_getmat.m``               | :ref:`getmat <extract-getmat>`              |
    |                  | time, lon, lat          |                                          |  :ref:`here <read_getmat>`                | (extract to disk) ``allbins*.m``            |
    |                  | ocean velocities        |                                          |  (load the files created by getmat)       | :ref:`read with load_getmat.m<read_getmat>` |
    |                  | (CODAS avg, eg 5min)    |                                          |                                           |                                             |
    |                  |                         |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+
    |                  |  **netCDF file**        |                                          |                                           |                                             |
    | CODAS database   | earth coordinates:      | :ref:`get_profiles <python_read_codas>`  |  download ``load_netcdf.m``               | :ref:`adcp_nc.py <extract_netCDF>`          |
    |                  | time, lon, lat          |                                          |  :ref:`here <read_netcdf>`                | (extract netCDF file to disk)               |
    |                  | ocean velocities        |                                          |  (load the files created by adcp_nc.py)   |                                             |
    |                  | (CODAS avg, eg 5min)    |                                          |                                           | :ref:`file description <netcdf_output>`     |
    |                  |                         |                                          |                                           |                                             |
    +------------------+-------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------+


----


Although we are not actively using or devloping Matlab
programs, we will ensure that the programs for reading
CODAS Matlab output and raw RDI data files continue to
work.


**Most popular**:

 - Matlab access to data CODAS database:
    * matlab files (use :ref:`load_getmat.m<read_getmat>` to load ``allbins_*.mat``) from the
      CODAS processing directory.  (see :ref:`file description<agetmat_output>`)
    * netCDF file (load :ref:`load_netcdf.m<read_netcdf>` into matlab)

Other useful tools:

 - Python:

   * CODAS database: (every bin, every profile - eg. 5min averages) -- read data with :ref:`get_profiles<python_read_codas>`)
   * read raw ADCP data (``ENR``, ``*.raw``) with :ref:`Multiread<python_read_raw>`
   * write the netCDF file with :ref:`adcp_nc.py<extract_netCDF>`

 - Matlab:

   * :ref:`read raw data<matlab_read_raw>` (``*.raw``, or VmDAS output ``*.LTA``, ``*.STA``, ``*.ENR``)

 - extract matlab files from CODAS database:

  * :ref:`getmat <extract-getmat>` (all bins and all profiles from a CODAS database, eg 5-min averages)
  * :ref:`adcpsect <extract_adcpsect>` (getting time, velocities, and positions from a codas database,
    typically with further averaging, eg. 15min or 1hour).  See :ref:`adcpsect file description <read_adcpsect>`.

 - HOWTO extract netCDF file:

  * extract using command-line tool :ref:`adcp_nc.py<extract_netCDF>` (see :ref:`netCDF file contents<read_netCDF>`).


.. toctree::
   :hidden:

   agetmat_output
   extract_adcpsect
   extract-getmat
   extract_netCDF
   matlab_read_raw
   netcdf_output
   python_read_codas
   python_read_raw
   read_adcpsect
   read_getmat
   read_netCDF