.. _read_getmat:



Loading files generated by getmat
+++++++++++++++++++++++++++++++++++



1. You will probably want the matlab program
   :download:`load_getmat.m </txtfiles/load_getmat.m>`

2. Identify the location of the files generated by ``getmat``.  For example,
   a modern UHDAS installation writes files  in ``contour/allbins_*.mat``
   You can see the live processing directory and access the
   ``allbins*.mat`` files by looking at the shared ``data`` directory and
   following the  example in the next step.  (see
   `this link </UHDAS_OPERATIONS/UHDAS_atsea/uhdas_data_atsea.html>`_
   for information about network shares)

3. If the location of the getmat output is
   ``uhdas_data/km1001c/proc/os38nb/contour``
   then load the files with matlab as follows:

::

   data = load_getmat('uhdas_data/km1001c/proc/os38nb/contour/allbins_');

   % DO apply the editing mask:
   u = data.u .* data.nanmask;
   v = data.v .* data.nanmask;

..

4. Variable names are documented with "help load_getmat", shown below.



::


  Fieldnames in "load_getmat" output:

      fieldnames   size         meaning:
       dday       1 x nprofs   zero-based decimal day (end of profile)
       time       6 x nprofs   year,month,day,hour,minute,second (end of profile)
    iblkprf       2 x nprofs   database block and profile number
        lon       1 x nprofs   longitude (from smoothed navigation; end of profile)
        lat       1 x nprofs   latitude  (from smoothed navigation; end of profile)
    heading       1 x nprofs   average primary heading (usually gyro)
    tr_temp       1 x nprofs   average temperature
    last_temp     1 x nprofs   last temperature
    last_good_bin 1 x nprofs   last good bin (-1 is bad profile)
        amp   nbins x nprofs   signal return amplitude or rssi (averaged)
       amp1   nbins x nprofs   signal return amplitude or rssi (beam 1)
       amp2   nbins x nprofs   signal return amplitude or rssi (beam 2)
       amp3   nbins x nprofs   signal return amplitude or rssi (beam 3)
       amp4   nbins x nprofs   signal return amplitude or rssi (beam 4)
      swcor   nbins x nprofs   spectral width (nb150) or correlation (os or wh)
      umeas   nbins x nprofs   measured  velocity (positive east, m/s)
      umeas_bt  1   x nprofs   measured  velocity (positive east, m/s) from bottom track
      uship     1   x nprofs   ship      velocity (positive east, m/s)
          u   nbins x nprofs   ocean     velocity (positive east, m/s)
      umean     1   x nprofs   ref layer velocity (positive east, m/s)
      vmeas   nbins x nprofs   measured  velocity (positive north, m/s)
      vmeas_bt  1   x nprofs   measured  velocity (positive north, m/s) from bottom track
      vship     1   x nprofs   ship      velocity (positive north, m/s)
          v   nbins x nprofs   ocean     velocity (positive north, m/s)
      vmean     1   x nprofs   ref layer velocity (positive north, m/s)
          w   nbins x nprofs   vertical  velocity (up   , m/s)
      wmean       1 x nprofs   mean vertical velocity for each profile
          e   nbins x nprofs   error velocity (m/s)
      depth   nbins x nprofs   center depth for each bin and profile, positive down
         pg   nbins x nprofs   percent good
      pflag   nbins x nprofs   0 is unflagged, otherwise there is a code.  see www docs
    nanmask   nbins x nprofs   suitable for dot-multiply with velocity

    ---- all diagnostics: only if called with (......'all')
                  (some might not be present in any case)

       mps        1 x nprofs   ship speed, m/s
      fmeas   nbins x nprofs   measured velocity (positive ship's fwd direction, m/s)
      pmeas   nbins x nprofs   measured velocity (positive ship's port direction, m/s)
       fvel   nbins x nprofs   ocean velocity (positive ship's fwd direction, m/s)
       pvel   nbins x nprofs   ocean velocity (positive ship's port direction, m/s)
    head_misalign 1 x nprofs   heading correction (best_head = heading - head_misalign)
    scale_factor  1 x nprofs   scale factor applied to watertrack data

    -------------------------------------------------------------------
    data =  load_getmat(prefix)
    input:
            prefix is the whole path up to the common base of the files
                   or, use path as well as prefix

    eg
            cd cruisedir
            data = load_getmat('allbins_');
    eg
            data = load_getmat(fullfile(cruisedir, 'allbins_'));

    The field "nanmask" holds the editing flags and is designed to turn bad
    velocity data into NaNs.    Use as follows

    u = data.u .* data.nanmask;
    v = data.v .* data.nanmask;

    ---------------

    depending on the version of "getmat", some of these fields may not be available

    NOTE: (1) decimal day starts with zero, i.e. Jan 1 noon is 0.5 (not 1.5)
          (2) The following values are from the END of the ensemble
                   decimal day, time
                   longitude
                   latitude
          (3) To get additional diagnostic fields, call with
                   load_getmat('allbins_', 'all');