/*---------------------------------------------------------------------- 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 ----------------------------------------------------------------------*/