This README file describes the file contents and processing steps for
each file of level1 mooring adcp data for the Long Bay Wintertime
(2012) Project.

---------
History of upload
---------
June 20, 2012 (SH) initial parsing, format and upload 

July 11, 2012 (SH) QC'd data using range tests and sensor health and
signal strength

July 23, 2012 (SH) lb2 and lb3 depth replaced by CTD data and used for
surface mask

Dec 17, 2014 (SH) after reviewing previous QC tolerances were too aggressive.
The error velocity tolerances and percent good were relaxed.
Also modified lb3 surface mask to account for tilt on slope shelf.

---------
1. Files
---------

/data/long_bay/level1/

lb1
|-- lb1_adcp.mat
lb2
|-- lb2_adcp.mat
lb3
|-- lb3_adcp.mat

-----------------
2. File Contents
-----------------

Three structures contain data pertaining to the deployment and sensor configuration

          platform: [1x1 struct] -- deployment location and depth info about bottom frame
            config: [1x1 struct] -- sensor configuration info and parameters
                qc: [1x1 struct] -- added structure that contains tolerances and flagged 
		    	 	    data for various qc tests

For example LB1 platform structure contains the following

                        id: 'lb1'
                       loc: 'Long Bay, NC, Shelf Bottom Frame'
          mean_water_depth: 30
    mean_water_depth_units: 'm'
                       lat: 33.1695
                       lon: -78.3334
                      mvar: -8.7000
                  start_dn: 7.3489e+005
                   last_dn: 7.3496e+005

The distance or range in meters of each profile depth cell above the
ADCP is stored in config structure called config.ranges

>> config.ranges

The cell array in config structure called config.units stores the
units of each variable

>> config.units

    'mtime'             'days since 0000-01-01T00:00'
    'pitch'             'deg'                        
    'roll'              'deg'                        
    'heading'           'deg'                        
    'depth'             'm'                          
    'temperature'       'deg C'                      
    'salinity'          'psu'                        
    'pressure'          'dbar'                       
    'east_vel'          'm s-1'  -- relative to True N       
    'north_vel'         'm s-1'  -- relative to True N
    'vert_vel'          'm s-1'                      
    'error_vel'         'm s-1'                      
    'corr_mag'          ''                           
    'echo_intensity'    'count'                      
    'percent_good'      '%'

Each file contains measured and derived parameters-one variable for
each parameter.  The variable index corresponds to same index of mtime
(or matlab time) for time of each sample.

             mtime: [1x21575 double]
             pitch: [1x21575 double]
              roll: [1x21575 double]
           heading: [1x21575 double]
             depth: [1x21575 double]
       temperature: [1x21575 double]
          salinity: [1x21575 double]
          pressure: [1x21575 double]
          east_vel: [29x21575 double]
         north_vel: [29x21575 double]
          vert_vel: [29x21575 double]
         error_vel: [29x21575 double]
          corr_mag: [29x21575 double]
    echo_intensity: [29x21575 double]
      percent_good: [29x21575 double]


--------------------
3. Processing Steps
--------------------

The following scripts are used to process level0 raw data to level1.  

More detailed information regarding the processing steps can be
obtained from the MATLAB scripts and the summary below. 

proc_adcp_raw.m -- reads data from RDI ADCP binary format downloaded
from each ADCP and stored in level0

proc_adcp_qc.m -- quality control steps applied to adcp data to
eliminate data not associated or out tolerances specified.

1. remove data when bottom frame not at deployment depth (trim beginning and end values)
2. evaluate sensor health (pitch, roll, heading, water temperature with tolerances)
3. quality and strength of returned signal used for acoustic doppler shift

echoIntensityTest
rangeTest of Correlation Magnitude 
rangeTest of Error Velocity 
rangeTest of Percent Good 

4. evaluate a surface mask for ADCP within range of the surface.
There are two ways of doing this. One is to define echo Intensity
threshold for surface reflection.  The second method uses certain
distance below water level determined from pressure sensor on or near
ADCP. The second method is the preferred method for this project.

LB2 ADCP did not have a pressure sensor, and LB3 ADCP pressure did not
function properly.  Pressure records from the CTDs were used to form
the surface mask in profile data.

5. The horizontal velocity components were rotated to be relative to
True North based on magnetic variation of the deployment location.

For example LB1 ADCP quality control tolerances are provided in the qc structure:

qc = 

        echoIntensityTest_tol: 20
             rangeTest_cm_tol: 90
      rangeTest_error_vel_tol: 0.2500
        rangeTest_heading_tol: 5
        rangeTest_mag_vel_tol: 2
             rangeTest_pg_tol: 50
          rangeTest_pitch_tol: 2
           rangeTest_roll_tol: 2
       rangeTest_salinity_tol: [30 40]
    rangeTest_temperature_tol: [0 35]
       rangeTest_vert_vel_tol: 0.1000
                corr_mag_flag: [29x21575 double]
          echo_intensity_flag: [29x21575 double]
               error_vel_flag: [29x21575 double]
               horiz_vel_flag: [29x21575 double]
            percent_good_flag: [29x21575 double]
           sensor_health_flag: [29x21575 double]
            surface_mask_flag: [29x21575 double]
                vert_vel_flag: [29x21575 double]
                     PASS_all: [29x21575 double]

Name - Definition 

rangeTest - The check to ensure that a measurement or
value or set of values (x) fall within established upper (max) and
lower (min) limits, min ≤ x ≤ max.  If the value or set of values are
less than the upper and greater than the lower, then the test passes.

echoIntensityTest - The check to determine the lowest or closest range where 
echo intensity exceeds a maximum allowed value for each measured profile. 

Correlation Magnitude - This parameter is a measure of the
pulse-to-pulse correlation in a ping for each depth cell. Correlation
magnitude data give the magnitude of the normalized echo
autocorrelation at the lag used for estimating the Doppler phase
change. As the correlation magnitude value decreases, so does the data
accuracy.

Error Velocity - This parameter is the difference between the two
independent estimates of vertical velocity at given range bin derived
from each beam pair at that range.

Percent Good - This data quality indicator reports the percentage of
good data collected at each depth cell of the velocity profile.
Rejection criteria of the instrument include low correlation, large
error velocity and fish detection.

Echo Intensity - This parameter provides a measure of the intensity or
strength of the returned backscattered echo for each depth cell. 

[1] D.R. Symonds, “QA/QC Parameters for Acoustic Doppler Current
Profilers,” Teledyne RDI Application Note, June, 2006.
