======================================================================

                    R E A D M E . P O S T E D I T 

                    doc: Wed Jun 13 20:30:10 2012

                    dlm: Thu Jun 14 18:22:13 2012

                    (c) 2012 A.M. Thurnherr

                    uE-Info: 95 50 NIL 0 0 72 3 2 8 NIL ofnI

======================================================================

=Summary=

This README explains how to post-edit the shear output from b[LADCPproc]

before feeding it to [LADCPintsh], e.g. for removing data collected when

the ADCP was very shallow and possibly affected by the ship's magnetic

field.

=Nitty-Gritty=

The default output from [LADCPproc] is a so-called time-depth-series

(.tds) file with one record per valid shear sample. Each record

contains the following fields:

ens		ensemble number the shear sample is from

elapsed		elapsed time in seconds of the present ensemble

CTD_depth	depth of CTD at the time the ensemble was recorded

downcast	a boolean flag set to 1 (nan) for down(up)cast records

depth		"nominal" depth of shear sample (center depth in gridded profile)

u_z		vertical shear of zonal velocity

v_z		vertical shear of meridional velocity

w_z		vertical shear of vertical velocity

This is the "general" output of [LADCPproc]. For standard processing,

the shear is bin-averaged in depth space. While this can easily be

accomplished, e.g. with a Matlab script, for convenience the binned

output can be requested with the -p option of [LADCPproc]. The binned

output cannot be post-edited!

The .tds data can be post-edited. Matlab users can import these files

with [loadANTS.m] (see [README.Output]), edit the structures, bin the

shear in depth space, and export the new structures as ANTS files with

[struct2ANTS.m]. For example, to remove all data collected with the

ADCP shallower than 5m, simply delete the records for which CTD_depth

<= 5. Or, you can bin your shear data with different statistics (e.g.

median), instead of the arithmetic mean used by [LADCPproc] -p.

Inconveniently, [LADCPintsh] at present requires its shear input to be

in the format generated by the -p option of [LADCPproc], with the

following fields (Matlab version):

depth		center depth of bin

dc_elapsed	mean elapsed time of downcast shear samples in present bin

dc_nsamp	number of downcast shear samples in bin

dc_u_z		bin-averaged downcast vertical shear of zonal velocity

dc_u_z_sig	corresponding standard deviation

dc_v_z		same for meridional velocity

dc_v_z_sig

dc_w_z		same for vertical velocity

dc_w_z_sig

uc_elapsed	mean elapsed time of upcast shear samples in present bin

uc_nsamp	number of upcast shear samples in bin

uc_u_z		bin-averaged upcast vertical shear of zonal velocity

uc_u_z_sig	corresponding standard deviation

uc_v_z		same for meridional velocity

uc_v_z_sig

uc_w_z		same for vertical velocity

uc_w_z_sig

elapsed		mean elapsed time of mean dn/upcast shear samples in present bin

nsamp	    	number of mean dn/upcast shear samples in bin

u_z	     	bin-averaged mean dn/upcast vertical shear of zonal velocity

u_z_sig      	corresponding standard deviation

v_z	     	same for meridional velocity

v_z_sig

w_z	     	same for vertical velocity

w_z_sig

Sv		bin-averaged acoustic volume scattering coefficient

Sv.nsamp	number of samples in bin

Note that the .tds file does not contain acoustic backscatter

information, i.e. the Sv field should be set to nan and the Sv.nsamp to

zero.

After binning the shear data, Matlab users can create a structure with

the fields listed above. Metadata (scalars in the .tds import

structure) should be copied verbatim from the .tds import structure.

Each of the listed fields is a vector and they must all have the same

length. (Since the down- and upcasts do not usually cover exactly the

same depth range, padding is almost always required.) The resulting

structure can then be exported with [struct2ANTS.m]; the 'dependencies'

argument should be set to the filename(s) of the .tds file(s) from

which the binned shear profile was constructed.

The only option for non-Matlab users is to create an ASCII file with

the required columns (nan values are permitted) in the order listed

above and prepend this with the header from the corresponding

[LADCPproc] output file produced by the -p option.