xtract control_file
This utility extracts data from a CODAS database and generates different types of ASCII files. These can be used as input to further other processing or visualizing tools. Unlike adcpsect which was created to access data from an ADCP database, xtract does not depend on the database being accessed. More exactly, it does not depend on the producer definition file used to create the CODAS database. You can therefore access with the same utility any CODAS database.
A producer definition file is required for creating a CODAS database. This file defines the variables that are going to be present in the database. Once the database has been created, information from the producer definition file is saved into the database, so that access to the variable properties is possible without the need of the original definition file.
The way xtract access the variables is by using their names, as they are defined in the database. See varnames(5) for more information on the syntax used to specify a variable name in the control file.
All extracted data are rescaled to their physical unit and converted to FLOAT before output.
The control file must define the following parameters:
Year base to use for converting time into decimal days.
Name (with path) of database to access.
Number of profiles to move during each steps.
The different type of files to output is controlled by the options listed in the control file. Several output files can be generated by declaring several product types and/or repeating repeating them with different options. The main options define the kind of file to generate. Possibilities are:
This key word can be used to improve the clarity of the control
file and specify the beginning of options. It has no effect.
This generates a columnar output with the values of each specified variable var in different columns. Several variables can be specified by repeating option var. Variables values are listed along columns in the same order they are specified in the control file. Lines containing only bad or data outside range are not output.
Product specifications are a list of sub-options. These are:
See below for a list of common options.
This option specifies a variable to extract from the
database. It can be repeated in order to extract data from
several variables simultaneously.
This keyword is mandatory and terminates the list of selected sub-options.
This options generates a profile file with in the first column values corresponding to X variable, all the other columns having values from the specified Y variables. Several Y variables can be specified by repeating option Y. Variables values are listed along columns in the same order they are specified in the control file, except for the X data which appear in the first column. Lines with bad X values are not output.
Product specifications are a list of sub-options. These are:
See below for a list of common options.
This option specifies the X variable in the
profile.
This option specifies an Y variable to extract
from the database. It can be repeated in order to extract
data from several variables simultaneously.
This keyword is mandatory and terminates the list of selected sub-options.
This options generates a contour file with in the first two columns values corresponding to X and Y variables, respectively, all other columns having values from the specified Z variables. Several Z variables can be specified by repeating option Z. Variables values are listed along columns in the same order they are specified in the control file, except for X and Y data which appear in columns one and two, respectively. Lines with bad X orY values are not output.
Product specifications are a list of sub-options. These are:
See below for a list of common options.
This option specifies the X variable in the
contour.
This option specifies the Y variable in the
contour.
This option specifies a Z variable to extract
from the database. It can be repeated in order to extract
data from several variables simultaneously.
This keyword is mandatory and terminates the list of selected sub-options.
This keyword is mandatory and terminates the list of selected options.
Variable specifications are a list of sub-options which is the same for each product listed above:
Name of variable to access and extract. See varnames(5) for more information on the syntax of variable names. A grid specification can be appended to the variable name (separate both with a colon) in order to extract certain points. Grid specifications can be formulated as follows:
where n? are integers, specifies a grid by bin
indexes.
where r? are floats, specifies a grid by the
values of the variable itself. This is most useful if
applied to variable DEPTH for extracting data at
specific depths.
This option is similar to the previous one, however it specifies a tolerance t1 to be applied around the following grid points. Tolerance values must be floats and can be repeated within the list in order to have different tolerance values for different grid points. This option allows to extract only data having values near specific ones.
Specifies a minimal threshold for the given variable in order to
be valid. The value can be either float or a string
specifying another variable name in the database. In the latter
case, the value of this variable is used as the threshold value.
This is also different in the sense that it is updated for each
profile. Default is -1.0E38.
This option is similar to option min, but is used for
specifying a maximal threshold value. Default is 1.0E38.
This option specifies a scaling factor to be multiplied to the
extracted data before output. In case threshold values are
specified with options min and/or max, these
are also scaled by the same value.
Default is 1.0.
This keyword is mandatory and terminates the list of selected sub-options.
Specifying threshold values with options min and max are especially useful when extracting DEPTH data from a post-processed ADCP dataset. Setting the minimal and maximal threshold values to ACCESS_VARIABLES.first_good_bin and ACCESS_VARIABLES.last_good_bin, respectively, will produce only values of good bins. Note that values outside the given ranges are still output, but as bad values.
Some application require depth data to be negative, but these must be positive for some other. Sometimes velocity data must be in cm/s instead of m/s. The main purpose of specifying option scale is to generate compatible files for these different requirements.
Options common to the different products are:
Specifies the name for the output file.
When several variables are to be extracted, the amount of data might not be the same for each of them. Normally, if a variable has less data, bad values are output. If this option is specified, output will stop when one of the specified variables has no more data. See also option undefined
For the variable product, all specified variables are
affected. For the profile product, only Y
variables are affected. Finally, for the contour
product, only Z variables are affected.
This options avoids output of bad data. It affects the same
variables as those affected by option combined.
This option writes a % between each profile
written to the output file. This can be useful during
post-processing for retrieving only data from specific profiles.
When several variables of different length have to be output in
the same file, undefined data can be output as -1.0E38
instead of being flagged as bad. See also option
combined. This option affects the same variables as
those affected by option combined.
Specify this for converting longitude values between -180 and +180 degree before using them.
Finally, the control file is terminated by a list of time ranges. See time_rng(5) for the syntax of these.
All files specified by the different file options.
Pierre Jaccard, Geophysical Institute, University of Bergen, 1999