/*----------------------------------------------------------------------

  1.  NAME

  vgeo - Calculate geostrophic current

  2.  USAGE

  vgeo control_file

  3.  DESCRIPTION

  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.

  4.  PARAMETERS

  The control file must contain the following parameters:

     year_base YYYY
        Year base to use for converting time into decimal days.

     ctd_db: name
        Name (with path) of CTD database to visit.

     output name
        Base name (with path) for output files.

  5.  OPTIONS

  There are many options for controlling the behaviour of vgeo. These
  are:

     OPTIONS:
        This key word can be used to improve the clarity of the control
        file and specify the beginning of options. It has no effect.

     reference_method: keyword
        Specify the method for determining the reference level. Default
        is ctd_max_depth. Possible keywords are:

        adcp_min_H_shear
           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:

           range:
              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:
              TIME_RANGE: YYYY/MM/DD hh:mm:ss to YYYY/MM/DD hh:mm:ss to
              specify a time range.

              DAY_RANGE: yd to yd to specify a time range given with
              decimal days.

              BLOCK_RANGE: blk to blk to specify a range of blocks. Be
              aware that blocks are numbered from zero.

              BLKPRF_RANGE: blk prf to

              blk prf to specify a range by block and profile numbers.
              Be aware that blocks and profiles are numbered from zero.

           data_profiles: keyword
              Specify which ADCP profiles to choose for calculating the
              minimal horizontal shear at profiles of geostrophic
              current. Available possibilities are:

              constant
                 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:

                 nprf= n
                    Specifies the number of profiles to choose.  There
                    is no default value for this option, i.e.  it has to
                    be defined if option constant is chosen.

                 end
                    This keyword is mandatory and terminates the list of
                    selected sub-options.

              between_ctd
                 All ADCP profiles between the two CTD profiles used to
                 calculate the geostrophic current are used. This is the
                 default.

           profile_tolerance= float
              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.

           data_good_bins= n
              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.

           data_file: file
              Name (with path) of database or external ASCII file
              containing the ADCP data to use for determining the
              horizontal current shear.

           use_adcp_pos
              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.

           flag_data
              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.

           data_format: keyword
              This option specifies the format of the specified file
              containing ADCP data to use for calculating the current
              shear. Implemented formats are:

              ascii
                 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 adcpsect and
                 con2con(1). If only a plain file is available, then one
                 should use con2db(1) to create a CODAS database from it
                 and select keyword codas_db instead.

              codas_db
                 Read data from an ADCP CODAS database. This is the
                 default.

           data_interp_axis: keyword
              This option specifies an axis common to the CTD and ADCP
              data. Default is time. Implemented axes are:

              time or none

              longitude

              latitude

           adcp_reference: keyword
              This option specifies the reference for calculating
              absolute currents from data stored in an ADCP CODAS
              database. Possible references are:

              none
                 Use current values as is. This is useful if the
                 database already contains absolute currents, such as
                 one created by con2db(1).
              ship
                 Use the final ship velocities stored in the
                 ACCESS_VARIABLE structure of the database.  This is the
                 default.

              navigation
                 Use the navigation data stored in the NAVIGATION
                 structure of the database.

           end
              This keyword is mandatory and terminates the list of
              selected sub-options.

        ctd_max_depth
           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:

           v= float
              Specify the reference velocity (in m/s) to be used at the
              reference level. Default value is zero.

           end
              This keyword is mandatory and terminates the list of
              selected sub-options.

        const_depth
           The reference level is chosen at a constant depth through the
           whole section. Further options for this method are:

           v= float
              Specify the reference velocity (in m/s) to be used at the
              reference level. Default value is zero.

           z= float
              Specify the reference level depth (in m). No default is
              supplied for this option.

           end
              This keyword is mandatory and terminates the list of
              selected sub-options.

     ctd_sort_axis: keyword
        Before calculating the geostrophic current, CTD profiles are
        sorted along the specified axis.  Implemented axes are:

        time or none
           This is the default.

        longitude

        latitude

     vgeo_direction: keyword
        The geostrophic current is calculated so that positive values
        correspond to a direction starboard to the chosen direction.
        Possible direction keywords are:

        northward
           This is the default.

        southward

        eastward

        westward

     grid: keyword grid
        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 keyword must be grid_list:. It must be followed by the
        grid specification corresponding to this method. This is

          number= n z1 z2 ...  zn

     where n is the number of grid points and z1-zn are the n depths
     where data should be regridded.

     time_tolerance= n
        Time tolerance in seconds for positioning inside CTD and ADCP
        data. Default is 30 seconds.

     ctd_good_bins= n
        Minimal number of good bins allowed in a CTD profile for
        considering this profile as valid. Default is 20.

     velocity_scale= float
        Scaling factor for geostrophic current in output files. A value
        of 0.001 will output data in cm/s. Default is 1.

     ctd_time_offset= n
        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.
     ctd_steps= n
        Number of CTD profiles to move within the CTD database. Default
        is 1.

     longitude_180
        Specify this for converting longitude values between -180 and
        +180 degree before using them.

     stat_output
        This option generates an output file about statistical data.

     log_output
        This option generates a log file.

     contour
        This option generates a contour file.

     end
        This keyword is mandatory and terminates the list of selected
        options.

  6.  TIME RANGES

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

  7.  OUTPUT FILES

  The generated files have all the name specified by parameter output
  but differ according to the following list of suffixes:

     con
        Contour data of geostrophic current. It is turned on with option
        contour. This file has the following columns:

        1. Time in decimal days

        2. Longitude in decimal degrees

        3. Latitude in decimal degrees

        4. Depth

        5. Geostrophic current

        The unit for the depth is the same as in the CTD database. How-
        ever, 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 velocity_scale.

     sta
        Statistics about reference level. It is turned on with option
        stat_output. This file has the following columns:
        1. Time in decimal days

        2. Longitude in decimal degrees

        3. Latitude in decimal degrees

        4. Depth of reference level

        5. Value of reference velocity

        6. Uncertainty of reference velocity at chose reference level

        7. Number of points used to determine the reference level

        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 vgeo.m can be used to
        visualize these data. Units are the same as those discussed for
        the contour output.

     log
        Additional log information. This is useful to control how the
        geostrophic current has been determined. It is turned on with
        option log_output.

     grd
        Regridded values of the geostrophic current. It is turned on if
        a grid is specified (see option grid). This file has the
        following columns:

        1. Time in decimal days

        2. Longitude in decimal degrees

        3. Latitude in decimal degrees

        4. Selected depth

        5. Geostrophic current

        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.

  8.  AUTHOR

  Pierre Jaccard, Geophysical Institute, University of Bergen, 1999



----------------------------------------------------------------------*/