Documentation/README.PostEdit
changeset 34 e5731cc26b5b
new file mode 100644
--- /dev/null
+++ b/Documentation/README.PostEdit
@@ -0,0 +1,95 @@
+======================================================================
+                    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.