# xtract

##

Last updated Fri Nov 19 13:00:20 1999

Extract data from a CODAS database

## 1. USAGE

xtract control_file

## 2. DESCRIPTION

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.

## 3. PARAMETERS

The control file must define the following parameters:

year_base: YYYY

  Year base to use for converting time into decimal days.

dbname: name

  Name (with path) of database to access.

step_size: n

  Number of profiles to move during each steps.

## 4. OPTIONS

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:

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.

variable: <product specifications>

  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:

  <common_options>

    See below for a list of common options.

  var: <variable specifications>

    This option specifies a variable to extract from the database. It can be repeated in order to extract data from several variables simultaneously.

  end

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

profile: <product specifications>

  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:

  <common_options>

    See below for a list of common options.

  X: <variable specifications>

    This option specifies the X variable in the profile.

  Y: <variable specifications>

    This option specifies an Y variable to extract from the database. It can be repeated in order to extract data from several variables simultaneously.

  end

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

contour: <product specifications>

  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:

  <common_options>

    See below for a list of common options.

  X: <variable specifications>

    This option specifies the X variable in the contour.

  Y: <variable specifications>

    This option specifies the Y variable in the contour.

  Z: <variable specifications>

    This option specifies a Z variable to extract from the database. It can be repeated in order to extract data from several variables simultaneously.

  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.

## 5. VARIABLE SPECIFICATIONS

Variable specifications are a list of sub-options which is the same for each product listed above:

name: name[:grid specifications]

  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:

  {n1, n2, ... }

    where n? are integers, specifies a grid by bin indexes.

  {r1, r2, ... }

    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.

  {(t1), r1, ... }

    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.

min= value

  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.

max= value

  This option is similar to option min, but is used for specifying a maximal threshold value. Default is 1.0E38.

scale= value

  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.

end

  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.

## 6. COMMON OPTIONS

Options common to the different products are:

file: file

  Specifies the name for the output file.

combined

  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.

no_bad

  This options avoids output of bad data. It affects the same variables as those affected by option combined.

separate

  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.

undefined

  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.

longitude_180

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

## 7. TIME RANGES

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

## 8. OUTPUT FILES

All files specified by the different file options.

## 9. AUTHOR

Pierre Jaccard, Geophysical Institute, University of Bergen, 1999

Back to the top documentation Index of GFI Extensions