.if n .ds Q \&"
.if t .ds Q ``
.if n .ds U \&"
.if t .ds U ''
.TH vgeo 1 "CODAS Utilities" "GFI"
.tr \&
.nr bi 0
.nr ll 0
.nr el 0
.de DS
..
.de DE
..
.de Pp
.ie \\n(ll>0 \{\
.ie \\n(bi=1 \{\
.nr bi 0
.if \\n(t\\n(ll=0 \{.IP \\(bu\}
.if \\n(t\\n(ll=1 \{.IP \\n+(e\\n(el.\}
.\}
.el .sp
.\}
.el \{\
.ie \\nh=1 \{\
.LP
.nr h 0
.\}
.el .PP
.\}
..
.SH NAME

.Pp
\fBvgeo\fP - Calculate geostrophic current

.SH USAGE

.Pp
\fBvgeo\fP \fIcontrol_file\fP

.SH DESCRIPTION

.Pp
This utility calculates the geostrophic current from CTD profiles
located in a CODAS database. Several methods are implemented to
determine the reference level. However, be aware that this utility
is still experimental.

.SH PARAMETERS

.Pp
The control file must contain the following parameters:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fByear_base\fP \fIYYYY\fP"
.nr bi 1
.Pp
Year base to use for converting time into decimal days.

.IP "\fBctd_db:\fP \fIname\fP"
.nr bi 1
.Pp
Name (with path) of CTD database to visit.

.IP "\fBoutput\fP \fIname\fP"
.nr bi 1
.Pp
Base name (with path) for output files.

.if \n(ll>1 .RE
.nr ll -1


.SH OPTIONS

.Pp
There are many options for controlling the behaviour of
\fBvgeo\fP. These are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBOPTIONS:\fP \fI\fP"
.nr bi 1
.Pp
This key word can be used to improve the clarity of the control
file and specify the beginning of options. It has no effect.

.IP "\fBreference_method:\fP \fIkeyword\fP"
.nr bi 1
.Pp
Specify the method for determining the reference level. Default
is \fBctd_max_depth\fP. Possible
keywords are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBadcp_min_H_shear\fP \fI\fP"
.nr bi 1
.Pp
This method uses ADCP data from a separate CODAS database or
external file. It calculates the horizontal current shear in
the section direction and select the reference level at the
depth where this shear is minimal. The mean velocity at this
depth is taken as the reference velocity. Further options
for this method are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBrange:\fP \fI\fP"
.nr bi 1
.Pp
Specify the range of profiles to consider from the
external ADCP data. Default is a time range with all
profile times. The following syntax are allowed:
.Pp
\fBTIME_RANGE:\fP
\fIYYYY/MM/DD\fP \fIhh:mm:ss\fP
\fBto\fP
\fIYYYY/MM/DD\fP \fIhh:mm:ss\fP
to specify a time range.
.Pp
\fBDAY_RANGE:\fP
\fIyd\fP \fBto\fP \fIyd\fP
to specify a time range given with decimal days.
.Pp
\fBBLOCK_RANGE:\fP
\fIblk\fP \fBto\fP \fIblk\fP
to specify a range of blocks. Be aware that blocks
are numbered from zero.
.Pp
\fBBLKPRF_RANGE:\fP
\fIblk\fP \fIprf\fP \fBto
\fP
\fIblk\fP \fIprf\fP
to specify a range by block and profile numbers. Be
aware that blocks and profiles are numbered from
zero.

.IP "\fBdata_profiles:\fP \fIkeyword\fP"
.nr bi 1
.Pp
Specify which ADCP profiles to choose for calculating
the minimal horizontal shear at profiles of geostrophic
current. Available possibilities are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBconstant\fP \fI\fP"
.nr bi 1
.Pp
Always choose a constant number of profiles. These
are chosen so that they are centered on the
geostrophic profile. In this case, the following
options are implemented:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBnprf=\fP \fIn\fP"
.nr bi 1
.Pp
Specifies the number of profiles to choose.
There is no default value for this option, i.e.
it has to be defined if option \fBconstant\fP
is chosen.

.IP "\fBend\fP \fI\fP"
.nr bi 1
.Pp
This keyword is mandatory and terminates the
list of selected sub-options.

.if \n(ll>1 .RE
.nr ll -1


.IP "\fBbetween_ctd\fP \fI\fP"
.nr bi 1
.Pp
All ADCP profiles between the two CTD
profiles used to calculate the geostrophic current
are used. This is the default.

.if \n(ll>1 .RE
.nr ll -1


.IP "\fBprofile_tolerance=\fP \fIfloat\fP"
.nr bi 1
.Pp
Because ADCP bins can contain bad data which are not
taken into account when calculating the horizontal
shear, one has to avoid the reference level to be chosen
at depths where too few points where available. This
parameter specifies the minimal value of good profiles
relative to the total number of profiles considered.
This value is used at each depth to validate the
computed current shear. Default value is 0.75.

.IP "\fBdata_good_bins=\fP \fIn\fP"
.nr bi 1
.Pp
Minimal number of good bins within an ADCP profile. This
parameter is used to validate those profiles that might be
considered healthy. Default is 15.

.IP "\fBdata_file:\fP \fIfile\fP"
.nr bi 1
.Pp
Name (with path) of database or external ASCII file
containing the ADCP data to use for determining the
horizontal current shear.

.IP "\fBuse_adcp_pos\fP \fI\fP"
.nr bi 1
.Pp
Specifies that geostrophic profile positions should be taken
from the ADCP data instead from the CTD ones. This can be
useful when CTD data have been collected simultaneously
with a CTD SeaSoar, since ADCP positions undergo usually a
more consistent calibration procedure.

.IP "\fBflag_data\fP \fI\fP"
.nr bi 1
.Pp
When extracting current data from an ADCP CODAS database,
data can be flagged according to the profile flags. It is a
good idea to specify this option if the database has been
edited and updated.

.IP "\fBdata_format:\fP \fIkeyword\fP"
.nr bi 1
.Pp
This option specifies the format of the specified file
containing ADCP data to use for calculating the current
shear. Implemented formats are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBascii\fP \fI\fP"
.nr bi 1
.Pp
Read current data from a plain ASCII file. This method
is not completely implemented yet. The idea was to read
data from a contour file generated by \fBadcpsect\fP
and \fBcon2con\fP(1). If only a plain file is
available, then one should use \fBcon2db\fP(1) to
create a CODAS database from it and select keyword
\fBcodas_db\fP instead.

.IP "\fBcodas_db\fP \fI\fP"
.nr bi 1
.Pp
Read data from an ADCP CODAS database. This is the
default.

.if \n(ll>1 .RE
.nr ll -1


.IP "\fBdata_interp_axis:\fP \fIkeyword\fP"
.nr bi 1
.Pp
This option specifies an axis common to the CTD and ADCP
data. Default is \fBtime\fP. Implemented axes are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBtime\fP or \fBnone\fP"
.nr bi 1
.Pp
.IP "\fBlongitude\fP \fI\fP"
.nr bi 1
.Pp
.IP "\fBlatitude\fP \fI\fP"
.nr bi 1
.Pp
.if \n(ll>1 .RE
.nr ll -1


.IP "\fBadcp_reference:\fP \fIkeyword\fP"
.nr bi 1
.Pp
This option specifies the reference for calculating
absolute currents from data stored in an ADCP CODAS
database. Possible references are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBnone\fP \fI\fP"
.nr bi 1
.Pp
Use current values as is. This is useful if the
database already contains absolute currents, such as
one created by \fBcon2db\fP(1).

.IP "\fBship\fP \fI\fP"
.nr bi 1
.Pp
Use the final ship velocities stored in the
\fBACCESS_VARIABLE\fP structure of the database.
This is the default.

.IP "\fBnavigation\fP \fI\fP"
.nr bi 1
.Pp
Use the navigation data stored in the
\fBNAVIGATION\fP structure of the database.

.if \n(ll>1 .RE
.nr ll -1


.IP "\fBend\fP \fI\fP"
.nr bi 1
.Pp
This keyword is mandatory and terminates the
list of selected sub-options.

.if \n(ll>1 .RE
.nr ll -1


.IP "\fBctd_max_depth\fP \fI\fP"
.nr bi 1
.Pp
This method defines the reference level to be at the lowest
available cell depth of the calculated relative geostrophic
current. Further options for this method are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBv=\fP \fIfloat\fP"
.nr bi 1
.Pp
Specify the reference velocity (in m/s) to be used at
the reference level. Default value is zero.

.IP "\fBend\fP \fI\fP"
.nr bi 1
.Pp
This keyword is mandatory and terminates the
list of selected sub-options.

.if \n(ll>1 .RE
.nr ll -1


.IP "\fBconst_depth\fP \fI\fP"
.nr bi 1
.Pp
The reference level is chosen at a constant depth through
the whole section. Further options for this method are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBv=\fP \fIfloat\fP"
.nr bi 1
.Pp
Specify the reference velocity (in m/s) to be used at
the reference level. Default value is zero.

.IP "\fBz=\fP \fIfloat\fP"
.nr bi 1
.Pp
Specify the reference level depth (in m). No default is
supplied for this option.

.IP "\fBend\fP \fI\fP"
.nr bi 1
.Pp
This keyword is mandatory and terminates the
list of selected sub-options.

.if \n(ll>1 .RE
.nr ll -1


.if \n(ll>1 .RE
.nr ll -1


.IP "\fBctd_sort_axis:\fP \fIkeyword\fP"
.nr bi 1
.Pp
Before calculating the geostrophic current, CTD profiles are
sorted along the specified axis.
Implemented axes are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBtime\fP or \fBnone\fP"
.nr bi 1
.Pp
This is the default.

.IP "\fBlongitude\fP \fI\fP"
.nr bi 1
.Pp
.IP "\fBlatitude\fP \fI\fP"
.nr bi 1
.Pp
.if \n(ll>1 .RE
.nr ll -1


.IP "\fBvgeo_direction:\fP \fIkeyword\fP"
.nr bi 1
.Pp
The geostrophic current is calculated so that positive values
correspond to a direction starboard to the chosen direction.
Possible direction keywords are:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBnorthward\fP"
.nr bi 1
.Pp
This is the default.

.IP "\fBsouthward\fP \fI\fP"
.nr bi 1
.Pp
.IP "\fBeastward\fP \fI\fP"
.nr bi 1
.Pp
.IP "\fBwestward\fP \fI\fP"
.nr bi 1
.Pp
.if \n(ll>1 .RE
.nr ll -1


.IP "\fBgrid:\fP \fIkeyword\fP \fIgrid\fP"
.nr bi 1
.Pp
Specifies grid points for a separate gridded output. This is
useful if one is only interested to have the value of the
geostrophic current at specified depths. The calculated values
are linearly interpolated to the given points. Currently, only
one method for specifying a grid is implemented. Hence, the
value of \fIkeyword\fP must be \fBgrid_list:\fP. It must
be followed by the grid specification corresponding to this
method. This is

.br
.po 0.75i
.ll 6.0i
.nr LL 6.0i
.LP
\fBnumber=\fP \fIn\fP \fIz1\fP \fIz2\fP ...
\fIzn\fP

.br
.po 0.25i
.ll 7.0i
.nr LL 7.0i
.LP

where \fIn\fP is the number of grid points and
\fIz1\fP-\fIzn\fP are the n depths where data should be
regridded.

.IP "\fBtime_tolerance=\fP \fIn\fP"
.nr bi 1
.Pp
Time tolerance in seconds for positioning inside CTD and ADCP
data. Default is 30 seconds.

.IP "\fBctd_good_bins=\fP \fIn\fP"
.nr bi 1
.Pp
Minimal number of good bins allowed in a CTD profile for
considering this profile as valid. Default is 20.

.IP "\fBvelocity_scale=\fP \fIfloat\fP"
.nr bi 1
.Pp
Scaling factor for geostrophic current in output files. A value
of 0.001 will output data in cm/s. Default is 1.

.IP "\fBctd_time_offset=\fP \fIn\fP"
.nr bi 1
.Pp
Time offset (in seconds) to add to CTD profile times if these
are wrong. This is especially important when CTD and ADCP are
combined using time as a synchronization parameter between both
datasets. Default is 0.

.IP "\fBctd_steps=\fP \fIn\fP"
.nr bi 1
.Pp
Number of CTD profiles to move within the CTD database. Default
is 1.

.IP "\fBlongitude_180\fP \fI\fP"
.nr bi 1
.Pp
Specify this for converting longitude values between -180 and
+180 degree before using them.

.IP "\fBstat_output\fP \fI\fP"
.nr bi 1
.Pp
This option generates an output file about statistical data.

.IP "\fBlog_output\fP \fI\fP"
.nr bi 1
.Pp
This option generates a log file.

.IP "\fBcontour\fP \fI\fP"
.nr bi 1
.Pp
This option generates a contour file.

.IP "\fBend\fP \fI\fP"
.nr bi 1
.Pp
This keyword is mandatory and terminates the list of selected
options.

.if \n(ll>1 .RE
.nr ll -1


.SH TIME RANGES

.Pp
Finally, the control file is terminated by a list of time ranges.
See \fBtime_rng\fP(5) for the syntax of these.

.SH OUTPUT FILES

.Pp
The generated files have all the name specified by parameter
\fBoutput\fP but differ according to the following list of
suffixes:

.nr ll +1
.nr t\n(ll 2
.if \n(ll>1 .RS
.IP "\fBcon\fP"
.nr bi 1
.Pp
Contour data of geostrophic current. It is turned on with option
\fBcontour\fP. This file has the following columns:

.nr ll +1
.nr el +1
.nr t\n(ll 1
.nr e\n(el 0 1
.af e\n(el \*(f\n(el
.if \n(ll>1 .RS
.nr bi 1
.Pp
Time in decimal days
.nr bi 1
.Pp
Longitude in decimal degrees
.nr bi 1
.Pp
Latitude in decimal degrees
.nr bi 1
.Pp
Depth
.nr bi 1
.Pp
Geostrophic current
.if \n(ll>1 .RE
.nr el -1
.nr ll -1

The unit for the \fIdepth\fP is the same as in the
CTD database. However, during the whole process it is assumed to
be in meter, and to be the same as in ADCP external datasets if
these are used during the process. The units for the geostrophic
current depends on the value of option \fBvelocity_scale\fP.

.IP "\fBsta\fP"
.nr bi 1
.Pp
Statistics about reference level. It is turned on with option
\fBstat_output\fP. This file has the following columns:

.nr ll +1
.nr el +1
.nr t\n(ll 1
.nr e\n(el 0 1
.af e\n(el \*(f\n(el
.if \n(ll>1 .RS
.nr bi 1
.Pp
Time in decimal days
.nr bi 1
.Pp
Longitude in decimal degrees
.nr bi 1
.Pp
Latitude in decimal degrees
.nr bi 1
.Pp
Depth of reference level
.nr bi 1
.Pp
Value of reference velocity
.nr bi 1
.Pp
Uncertainty of reference velocity at chose reference
level

.nr bi 1
.Pp
Number of points used to determine the reference level

.if \n(ll>1 .RE
.nr el -1
.nr ll -1

These data are especially useful if the method used to
determine the reference level uses the minimal horizontal
current shear from external ADCP data. It allows to control if
the calculated values are consistent. The Matlab script
\fBvgeo.m\fP can be used to visualize these data. Units are
the same as those discussed for the contour output.

.IP "\fBlog\fP"
.nr bi 1
.Pp
Additional log information. This is useful to control how the
geostrophic current has been determined. It is turned on with
option \fBlog_output\fP.

.IP "\fBgrd\fP"
.nr bi 1
.Pp
Regridded values of the geostrophic current. It is turned on if
a grid is specified (see option \fBgrid\fP). This file has
the following columns:

.nr ll +1
.nr el +1
.nr t\n(ll 1
.nr e\n(el 0 1
.af e\n(el \*(f\n(el
.if \n(ll>1 .RS
.nr bi 1
.Pp
Time in decimal days
.nr bi 1
.Pp
Longitude in decimal degrees
.nr bi 1
.Pp
Latitude in decimal degrees
.nr bi 1
.Pp
Selected depth
.nr bi 1
.Pp
Geostrophic current
.if \n(ll>1 .RE
.nr el -1
.nr ll -1

Each line is repeated for each specified grid depth before data
for a new profile is encountered. The unit of the geostrophic
current here is not scaled. Hence, it is assumed to be in m/s.

.if \n(ll>1 .RE
.nr ll -1


.SH AUTHOR

.Pp
Pierre Jaccard, Geophysical Institute, University of Bergen, 1999