.. ......................................
.. UHDAS/CODAS restructured text document
.. ......................................

UHDAS Heading and Averaging
============================

Setting Heading Sources
-----------------------

The heading correction comes from the device specified.
This heading device is specified in two places.  It is best if
they are the same, to avoid confusion.  The two locations are:


    -  in the file ``cruise_cfg.m`` (probably named something like
        ``km0601_cfg.m``, probably located in a subdirectory 'config'
        of the actual processing directory.   The line looks like this:

::
 
         hcorr_inst =  'ashtech';   %(gyro, posmv, ashtech, seapath)
 

..

    - in the control file for quick_adcp.py, where the line looks
      like:


::

         --hcorr_inst  ashtech # choose : gyro, ashtech, posmv, seapath

..

    - NOTES

        * The value in ``cruise_cfg.m`` is the default; the value in 
          quick_adcp.py's control file overrides it.  It's easiest to
          make them the same.

        * specifying 'gyro' disables the heading correction, i.e. the
          heading used is simply that of the gyro

Apply Heading Correction
-------------------------

There are two mechanisms of applying the heading correction.
Those are specified in the quick_adcp.py control file by
using one of the two following 

       
::

         -- ping_headcorr
         -- post_headcorr 

     
If neither is chosen, or if the heading correction instrument is
"gyro" then no heading correction is performed.

ping_headcorr
~~~~~~~~~~~~~

This is the mechanism used during real-time at-sea acquisition and
processing.  It is not recommended for batch processing.  This
mechanism calculates a heading correction for each independent
5-minute ensemble.  The value of the correction is stored in the
database as a watertrack and bottomtrack misalignment, and the
velocities are rotated *before* being stored.  Files written in
'cal/rotate' with prefix 'ens_hcorr'* indicate values stored IN the
ensembles.  Quick_adcp.py "rotate" stage does not apply a
time-dependent heading correction.  The files are left on the disk as
a record of what was applied IN the ensembles


post_headcorr
~~~~~~~~~~~~~

This is the mechanism recommended for use in batch processing.  Files
are generated in the 'cal/rotate' subdirectory that show the heading
correction to be applied.  These are not applied until the "rotate"
step, allowing the user to reprocess the dataset and clean the angle
file prior to use (eg. interpolate across gaps). These files all start
with "hcorr".



Details of files in 'cal/rotate':
----------------------------------

In both cases (ping_headcorr and post_headcorr)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    - The rotate.log file will show a post-processing correction using the
      file only if that method used it.
    
    - the  heading correction is in the ancillary_2 data structure
               of the database
    - the database should act the same with either method:
      * the gyro (primary) heading stored in ancillary_1 'heading'
      * heading correction applied is stored in ancillary_2
      * measured velocities have been rotated by the value in ancillary_2
    
    - using "unrotate" with "rotate rotate.cnt" will revert to
            zero heading  correction
    
    - lst_hdg now includes a column with the ancillary_2  heading correction
    
    - files are created in cal/rotate as a record
    
    
specific to --ping_headcorr
+++++++++++++++++++++++++++

::
    
    
 file                   purpose         details
 ------                 -------         --------
 ens_hcorr.ang          APPLIED         heading corrections present 
                                        IN the ensembles
 ens_hcorr.asc          diagnostics     heading corrections and their quality 
 ens_hcorr_err.txt      diagnostics     comment for each 5-minute average
 hcorr_stats.txt        diagnostics     running statistics from ens_hcorr.asc
 print_hcorrstats_tmp.m matlab program  (makes hcorr_stats.txt)
 hcorr_plot.png         diagnostics     at sea: running plot of ens_hcorr.asc
                                       heading correction and quality

NOTE: see this `link <ens_hcorr.html>`_ for important details about
ens_hcorr.txt


specific to --post_headcorr
+++++++++++++++++++++++++++

::
 
 file                   purpose         details
 ------                 -------         --------
 ens_hcorr.ang          diagnostics     heading corrections calculated
                                        on a per-ensemble basis
 ens_hcorr.asc          diagnostics     heading corrections and their quality 
 ens_hcorr_err.txt      diagnostics     comment for each 5-minute average
 hcorr.asc              intermediate    1-minute heading corrections with QC
 hcorr.ang              APPLIED         derived from hcorr.asc
 hcorr_stats.txt        diagnostics     statistics of whole dataset
 print_hcorrstats_tmp.m matlab program  (makes hcorr_stats.txt)
 plot_hcorrstats_tmp.m  matlab program  (makes hcorr.ps)