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

  1.  NAME

  process - Average and load NB raw ADCP data into a CODAS database

  2.  USAGE

  process control_file

  3.  DESCRIPTION

  This utility averages NB raw ADCP pings and load them into a CODAS
  database. It is currently designed to load data as defined in producer
  definition file adcp_hm.def. See below for the syntax of the
  control_file.

  4.  PARAMETERS

  The following parameters are required:

     year_base: YYYY
        Specify the year base to use for converting dates in decimal
        days. Since the format of NB ADCP raw files does not contain
        full dates with year, a good choice for this parameter is to
        choose the year during which measurements were carried out.

     file_list: file
        Name of file containing successive names (including path) of NB
        ADCP raw files to average. This file can contain C-syntax
        comments.

     log_file: file
        Name of file for log information.

     db_name: name
        Name of database with path. Remember that the base name of a
        CODAS database can only be made of five characters and that
        suffixes are added automatically

     prd_file: file
        Producer definition file. This is the file containing the
        content of the database.

     avg_time: seconds
        Averaging time in seconds.

  5.  OPTIONS

  The rest of the averaging process is controlled by the following
  options:

     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.
     use_scan_nav:
        Specify that navigation data should be read from a file
        generated by scan_nav(1). This file contains pre-processed
        navigation data synchronized with ADCP pings. The following sub-
        options are available:

        file: file
           Name of file (with path) containing pre-processed navigation
           data.

        time
           Use time from the navigation file as the ping time.  Default
           is to use the one from the raw file.

        heading
           Use heading from the navigation file as the ping heading.
           Default is to use the one from the raw file.

        pitch
           Use pitch from the navigation file as the ping pitch.
           Default is to use the one from the raw file.

        roll
           Use roll from the navigation file as the ping roll.  Default
           is to use the one from the raw file.

        time_ref: ref_keyword
           Specify which ensemble time to load into the database.
           Possible keywords are:

           ensemble_start
              The time loaded into the database will correspond to the
              start of ensembles.

           ensemble_stop
              The time loaded into the database will correspond to the
              end of ensembles. This is the default because most
              applications in the CODAS package are designed for this.
              It is therefore a natural choice here. Choose another
              reference if you know what you are doing.

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

     nav_output:
        This options allows to generate a file with navigation data for
        each averaged ensembles. The format of this file as the same as
        the output from getnav. Possible sub-options are:

        file: file
           Name of file in which navigation data should be written.

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

     conversion_controls:
        This option controls how data is converted. The following sub-
        options are available:

        bin_mapping
           Select this option to perform mapping of bin depths using
           pitch and roll data.

        echo_scale_temp: float
           Water temperature for scaling of echo amplitude data, in
           degree Celsius. Default is 10.0.

        sound_speed: float
           Speed of sound in water in m/s. Default is 1536. Here, it is
           probably best to specify the value used during collection of
           data. Correction for each specific ensemble is carried out
           during the calibration procedure with CTD data.

        sound_absorption: float
           Sound absorption for mapping echo amplitude data to their
           corresponding depths, in dB/m. Default is 0.039.

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

     transducer_settings:
        This option allows to specify transducer parameters. The
        following sub-options are available:

        beam_angle= float
           Angle in degree of beams relative to the vertical axis. This
           is usually 30.0 or 20.0. Default is 30.0.

        beam_3_offset: float
           Normally, the transducer is mounted so that beam numbered 3
           faces the bow of the ship. However, this is often not the
           case. This option specifies this mounting offset in degree
           with increasing positive values corresponding to an offset
           toward starboard. Default is 0.0. Note that this parameter is
           not meant for the transducer misalignment.

        transducer_depth: float
           Depth of transducer in m. Default is 0.0. This option is
           required to get the true bin depths.

        transducer_frequency: float
           Transducer frequency in Hz. Since most NB VM-ADCP are
           operating on a frequency of 150kHz, the default is 153600.0.

        transducer_misalignment:
           This options allow to specify transducer misalignment
           relative to the selected value of parameter beam_3_offset.
           The following tilt values (in degree, default is 0.0) can be
           specified:

           heading= float

           pitch=   float

           roll=    float

           end
              This keyword is mandatory and terminates the list of
              misalignment specifications.

        bt_profiling_pings: integer
           This option specifies the number of water tracking pings per
           water tracking pings. This parameter has no effect on data
           processing, however it is that value that will be loaded into
           the database, as the format of raw files does not contain
           this information. Furthermore, it has no effect on later
           processing of bottom track velocities.

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

     processing_controls:
        This option allows to tune the averaging and processing of raw
        ADCP pings. The following sub-options are available:

        beam_solutions:
           Specify the allowed beam solutions. With a well working
           transducer, one has four beam velocities to resolve current
           into Earth's coordinate system and an error velocity. With
           three beam velocities, only currents can be determined, one
           of them being probably less precise. When only two beam
           velocities are available, it still possible if available
           beams are orthogonal to each other, both of them being less
           precise. Clearly, when only one beam velocity is available
           for a direction, the current does not correspond to the
           vector average of velocities, yielding less precise data.

           Before resolving currents, data are checked for bad values
           according to different methods. The latter determine how many
           beam velocities are made available for yielding currents. The
           following methods are implemented:

           1  Set to bad beam values that already set to bad the ADCP.

           2  Calculate the mean of the four beam values (those that
              have not been already set to bad by the ADCP), as well as
              the standard deviation. Beam values that lie outside the
              interval defined by the mean value and the standard
              deviation are set to bad.

           The following list describes how the different variables are
           flagged as bad:

           beam velocities
              Method 1.

           echo amplitude
              Method 2.

           spectral width
              Method 2 on echo amplitude data.

           bottom tracking velocities
              Method 1.

           In addition, the following sub-options are available:

           min_beam= integer
              The minimal beam solution allowed. This is a number
              between 2 and 4.

           max_beam= integer
              The maximal beam solution allowed. This is a number
              between 2 and 4.

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

           The default for allowed beam solutions is to try all of them,
           starting from the best which is four. Results from a two beam
           solution are not expected to be of good quality.  Hence, one
           should probably allow three and four beam solutions only.
           However, situation where the transducer was not well working
           might require a two beam solution.

        time_controls:
           This option allows to control the averaging process over
           time. The following parameters can be modified:

           max_gap= integer
              Maximal time gap allowed (in second) between two pings.
              If this value is exceeded, averaging of the current
              ensemble is stopped and averaging of a new one is started.
              Gaps between pings can also occur when navigation data is
              not available during a laps of time.  The current ensemble
              is considered or thrown away according to the value of
              parameter avg_min (see below). Default is 20% of the given
              averaging interval.

           avg_min= integer
              Minimal average time (in second) allowed for an ensemble
              to be considered. This parameter is useful to decide
              whether the last ensemble should be kept or not. It is
              also used during the averaging process when large time
              gaps occur between valid pings (see parameter max_gap).
              Default value is 80% of the given averaging interval.

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

        new_block
           Normally, averaged ensembles are loaded into the database as
           successive profiles within the current block. A new block is
           only created for the first ensemble and when the number of
           profiles in the current block exceeds the allowed maximal
           value. This option allows a better control. If specified, a
           new block will also be created at the beginning of each time
           range specified at the end of the control file.

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

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

  6.  TIME RANGES

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

  7.  OUTPUT FILES

  The following files are generated:

     *.blk
        Database files.

     log_file
        This file contains log information about the whole process, as
        well as some data in form of an ASCII table. Text information is
        commented with a %, so that this file can be read by the Matlab
        script process.m to view these data.
     nav_output file
        This file contains navigation data for each loaded ensemble. It
        has the same format as the output of getnav.

  8.  AUTHOR

  Pierre Jaccard, Geophysical Institute, University of Bergen, 1999



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