#======================================================================

#                    L A D C P P R O C . D E F A U L T S 

#                    doc: Fri Sep 17 09:44:21 2010

#                    dlm: Wed May 28 23:23:41 2014

#                    (c) 2010 A.M. Thurnherr

#                    uE-Info: 260 0 NIL 0 0 72 0 2 4 NIL ofnI

#======================================================================

# default parameters for [LADCPproc]

# NOTES:

#	- defaults are taken:

#		1) from my current UH processing merge control files

#		2) from the defaults set in Eric's [merge.c]

#	- the default version in the ANTS bin dir is always loaded

#	- if there is a version in the current processing directory it is loaded 

#	  afterwards

#	- per-station parameters can be chosed based on $LADCP_file and $CTD_file

# 	- for additional notes, see [LADCPproc]

# HISTORY:

#	Sep 17, 2010: - created

#	Dec  9, 2010: - added doc for ASCII CTD file support

#	Jun 15, 2011: - added Svbin_start, Svbin_end

#	Jul  7, 2011: - added BT processing parameters

#	Jul 12, 2011: - added $PPI_editing_enabled

#	Apr 11, 2012: - cosmetics

#	May 16, 2012: - BUG: comment var name typo

#	Jan  8, 2013: - added CTD_ASCII_header_lines

#	Apr 22, 2013: - BUG: BT_begin_search_above value of 300m did not make sense

#	Jun  5, 2013: - added $bad_beam

#	Sep  6, 2013: - BUG: BT_begin_search_above value of 300m was correct; 

#						 the original bug was in the documentation

#	Sep 19, 2013: - added support for $BT_range_method

#	Feb 22, 2014: - added $LADCP_max_gap

#	Mar 21, 2014: - added $ignore_tilt

#----------------------------------------------------------------------

# Data editing

#----------------------------------------------------------------------

# Sometimes, an ADCP beam degrades to the point where its data contaminate 

# the 4-beam solutions. Set the following variable to the number of the

# bad beam to discard its data. This variable can also be used for crude

# wake editing in cases where only a single beam is affected, which can

# happen in particular with CTD platforms that tend to "weather vane".

# $bad_beam = 1;

# Calculation of the LADCP time series of depth is re-started

# after a gap exceeding $LADCP_max_gap seconds. This is useful

# for dealing with double dips, data from instruments that

# return occasional velocities while on deck, etc. By default,

# all gaps are ignored. To turn on this heuristic,

# reduce the value of the following varible (time in seconds) to the 

# longest real gap (large tilt, bottom stop, etc.) in the data. 

$LADCP_max_gap = 9999;

# For DVL data collected on 2014 Webb gliders, the pitch information 

# is offset by 11 degrees. Setting $ignore_tilt = 1 causes

# tilt information not be used:

#	- to set TILT_BIT DELTA_TILT_BIT PPI_BIT

#	- to calculate the depth of a particular bin

undef($ignore_tilt);

# The values in the following variables are added to the corresponding

# tilt measurements.

$pitch_offset = 0;

$roll_offset = 0;

#----------------------------------------------------------------------

# ASCII CTD file support

#----------------------------------------------------------------------

# By default, [LADCPproc] reads a standard seabird .cnv file. Alternatively,

# the CTD data can be supplied in a plain ASCII file. To do so, the following

# variables must be defined in the setup file (-s). Each variable defines 

# the field (column) number of the corresponding data field. Fields are

# numbered beginning with 1.

# $CTD_ASCII_sampfreq		= 1;  ## in Hz

# $CTD_ASCII_press_field 	= 1;

# $CTD_ASCII_temp_field 	= 2;

# $CTD_ASCII_salin_field	= 3;

# $CTD_ASCII_lat_field 		= 4;

# $CTD_ASCII_lon_field 		= 5;

# The following variables are optional:

# $CTD_ASCII_header_lines	= 4;			# if this variable is defined, #-comments are disallowed

# $CTD_ASCII_badval 		= 999;

#----------------------------------------------------------------------

# Time Lagging

#----------------------------------------------------------------------

#----------------------------------------------------------------------

# Backscatter Profile Parameters

#----------------------------------------------------------------------

# The output profile of volume-scattering coefficient is calculated 

# from a subset of the bins only. This is based on the observation,

# from on a single P403 profile, that the volume-scattering coefficient 

# correction of Deines (IEEE 1999) yield similar results only for

# bins 3-9. 

# The seabed-finding routine, on the other hand, uses acoustic 

# backscatter from all bins, as it is possible that the seabed is only

# seen in the farthest bins. 

$Svbin_start = 3;

$Svbin_end	 = 9; 

#----------------------------------------------------------------------

# Bottom Track Parameters

#----------------------------------------------------------------------

# First bin to consider when looking for seabed to calculated post-

# processed BT. NB: For consistency with EF's code, bin 1 is the 

# first bin.

$BT_bin_start = 1;

# Apparently valid BT data collected at distances greater than 300m 

# from the seabed are discarded.

$BT_begin_search_above = 300;

# Maximum allowed spread of bin number where max echo is found. Large values

# imply sloping seabed and/or large instrument tilt. The default value of

# 3 is probably too tight. The range spread calculation should be modified

# to take instrument tilt into consideration.

$BT_max_bin_spread = 3;

# For tricky BT cases, the acoustic backscatter from the seabed can be plotted

# and the bottom range set manually. This has been found to be very powerful

# in case of 2011_IWISE yoyo profile 160, where the bottom was around 150m 

# from the lower turning points and where the method of Deines [1999] clearly

# does not work.

#$BT_min_depth = xxx;

#$BT_max_depth = xxx;

# Maximum difference between water depth and average distance of echo max.,

# if $BT_min_depth and $BT_max_depth are not set. The stddev of the detected

# water depth is added to this number.

$BT_max_depth_error = 20;

# Maximum allowed difference between reference-layer w and BT w. Note 

# that this must be relaxed in regions of significant near-bottom

# vertical velocity, e.g. due to cross-slope currents.

$BT_max_w_difference = 0.03;

# When the BT velocity is taken from the wrong bin, the measurement is not

# taken from the main acoustic beam but, rather, from a side lobe. As a

# result, the BT measurement is biased, causing biased near-bottom LADCP

# velocities when the instrument is moving horizontally.

# Methods:

#	0: Take BT velocity from bin with max(Sv). Not recommended.

#	1: Chose either bin at max(Sv) or one of its neighbors, 

#	   depending which shows the smallest discrepancy between w_BT and w_reflr. 

#	   Causes underestimation of instrument speed in P403 tow-yos.

#	2: Visbeck (2002): use median from 3 bins. Requires $BT_range_Visbeck_center

#	   to define where the 3 bins should be centered wrt. the max(Sv) bin.

#	   Visbeck suggests +1. Based on P403 tow-yo 030 it looks more like -2.

$BT_range_method = 1;		

#----------------------------------------------------------------------

# Shear Processing Parameters

#----------------------------------------------------------------------

##   u_bin0, u_bin1, w_bin0, w_bin1: These set the first and

##      last bin indices used when integrating horizontal and

##      vertical velocity, respectively.  The indices start

##      from 1 and are inclusive.  These parameters do not  

##      affect the calculation of shear.  They should specify

##      a good reference layer (for the calculation of the

##      barotropic component) such as bins 1 to 4.

$wbin_start	= 1;	## These parameters start from 1, not zero

$wbin_end 	= 5;

$ubin_start	= 1;

$ubin_end	= 5;

##   sh_bin0, sh_bin1: These are like the above except that  

##      they affect the shear calculation only.  They can

##      normally be left at the default range of 1 to 128  

##      (disabled).

$shbin_start	= 1;

$shbin_end		= $LADCP{N_BINS};

##   w_ref_bin, w_dif: These control one of the editing  

##      criteria recommended by Fischer and Visbeck, or rather

##      a modification of it.  All velocity data are rejected

##      below the point at which the vertical velocity

##      estimate is w_dif larger or smaller than the estimate

##      in w_ref_bin.  I have not found this criterion

##      helpful.  94/12/22: changed, so that only those points

##      where w actually deviates from the mean from 0 to w_ref_bin

##      are flagged.

$w_ref_bin = 10;

$w_dif	   = 0.05;

##   wake_hd_dif, wake_ang_min, min_wake_w, n_wake_bins:  These control

##      editing based upon the direction and inclination of the package wake,

##      calculated from reference layer U,V, and W.  wake_hd_dif

##      sets how close to the heading of the wake must be to

##      the heading of any beam for interference (in degrees).

##      wake_ang_min sets the minimum wake angle from the

##      vertical for interference (in degrees).  min_wake_w sets

##      the minimum package speed required for wake interference

##      (although upward speed is measured negative, this parameter

##      is input as a positive value).  All three criteria

##      must be satisfied for the wake flag to be set.  n_wake_bins

##      determines how many bins from the top are removed from a

##      flagged profile, the default is 1 (top bin only).

##      Additionally, if the previous ensemble met all

##      interference criteria, the present ensemble

##      will be flagged even if the criteria are not met.

##      Default values are wake_hd_dif=0.0, wake_ang_min=90.0,

##      and min_wake_w=0.1, which results in no wake editing.

$wake_hd_dif  = 0.0;   ## set wake editing defaults so that no wake editing

$wake_ang_min = 90.0;  ## occurs

$min_wake_w	  = 0.1;

$n_wake_bins  = 1;     ## wake editing default - top bin only

##   e_max is the maximum error velocity.  An error velocity

##         greater than e_max will flag the other velocity

##         components.  For the BB with 2-ping ensembles, 0.01

##         m/s looks about right for this parameter.  It

##         knocks out the incorrect ambiguity glitches as well

##         as some smaller but still significant glitches.

##         Note that for the BB, the PG criteria operate on

##         percent 4-beam solutions, so PG combined with the

##         e_max provides a reliable filter against big

##         glitches.

##         For the NB with 18-ping ensembles, it is not yet

##         clear whether there is any benefit in using e_max

##         at all.  To be effective, the value will have to be

##         small, something like 0.015 or 0.02.  Note also

##         that for the NB, the pg array holds pg counting

##         both 4-beam and 3-beam solutions, so 3-beam

##         glitches will slip through the e_max net.

##         Default is e_max= 10.0, which effectively disables

##         it.

$e_max = 0.1;

##   min_correlation (BB only) is the minimum correlation, in

##      counts, for each beam in a given bin.

#	mk_prof() in [RDI_Utils.pl] removes all velocities with

#	correlations < 70 before this criterion is applied.

$min_cor = 70;

##   Shear editing:  This requires 2 passes through the

##      database, one using the option

##            binned_shear_time_range:

##      to set the time range for a pass during which the

##      shear statistics will be calculated on a relatively

##      coarsely grid by binning rather than interpolation,

##      then using the usual option

##            time_range:

##      for the normal pass in which the results of the

##      previous pass can be used to flag bad velocity values

##      based on anomalous shears.  The first pass can include

##      both up and down casts if desired, in which case it

##      would be followed by a second pass for the up and

##      downcasts separately.  The binned shear statistics are

##      saved until they are explicitly recalculated with the

##      "binned_shear_time_range:" option.

##      The shear editing is controlled by these parameters:

##         shear_dev_max= x.x, where x.x is a floating point

##            number giving a threshold in standard

##            deviations.  Any shear component deviating from

##            the binned mean by more than this times the

##            local standard deviation will raise a flag.

##            Suitable values for this parameter are probably

##            in the range 3-5.  Less than 3 is likely to

##            start trimming too many valid samples, more than

##            4 or 5 is likely to do nothing at all.

##         shear_sum_dev_max= x.x gives a threshold used in

##            detecting isolated bad velocity points.  If the

##            sum of two successive bad shears (based on

##            shear_dev_max), divided by the

##            standard deviation, is LESS THAN this amount,

##            then the common velocity point is considered to

##            be an isolated glitch, and it alone is flagged.

##            Otherwise, both velocity samples contributing to

##            a flagged shear will be flagged.  A reasonable

##            value for this parameter is probably around 1-2,

##            but I don't yet have enough experience to be

##            sure.

##         Warning: don't forget to reset the first_x=,

##         first_y=, and first_z= parameters after pass 1

##         (with binned_shear_time_range:).  If you don't, and

##         the depths are not in the database, then the depths

##         will be completely wrong in pass 2 (with

##         time_range:).  You may also want to use a different

##         output file name for pass 1, so that the binned

##         shear statistics file will not be overwritten

##         during pass 2.

$max_shdev     = 3.5;	## to disable, set to nan

$max_shdev_sum = 1.5;

##   previous ping bottom bounce interference editing is controlled by:

##   clip_margin 0.0 turns off this editing; otherwise, it is the margin in

##      meters (on each side) by which the calculated range of the

##      interference is expanded before clipping.  A reasonable value would

##      be something like 32 (2 depth bins).

undef($PPI_editing_enabled);	# set to 1 to enable PPI editing

# NOTES:

# 	- default value (90m) taken from comment in merge control files

#	- clipping is disabled if water_depth cannot be determined

$clip_margin	= 90;  			## default: no previous ping bottom bounce editing

$first_clip_bin	= 1; 			## default: apply previous ping clipping to all bins */

# tilt editing as in Visbeck's code

$max_tilt 		= 22;			# max allowed angle from vertical

$max_delta_tilt = 4;			# max allowed ping-to-ping tilt difference

# On DIMES US2 stations in Drake Passage it was found that the ambiguity velocity had been

# set too low. It appears, however, that aliased velocities are easy to detect because aliasing

# causes a large positive velocity to appear as a large negative one, and vice versa.

# The following defines the maximum allowed discrepancy between the vertical velocity from CTD

# pressure and the LADCP reference-layer w. This parameter should probably be set to something

# similar as the ambiguity velocity.

$w_max_err = 2.5;

1;