The sampling tool extracts data values at specified Earth
locations.
Name
cwsample - extracts data values at specified earth locations.
Synopsis
cwsample {-s, --sample=LATITUDE/LONGITUDE} [OPTIONS] input output
cwsample {-S, --samples=FILE} [OPTIONS] input output
Options:
-d, --dec=DECIMALS
-D, --delimit=STRING
-h, --help
-H, --header
-i, --imagecoords
-m, --match=PATTERN
-M, --missing=VALUE
-n, --nocoords
-R, --reverse
-V, --variable=NAME1[/NAME2/...]
--version
Description
The sampling tool extracts data values at specified Earth
locations from 2D data variables. A sample point may be specified
on the command line using geographic coordinates, or multiple
sample points may be specified using a data file. A number of 2D
data variables may be sampled simultaneously. The sampled values
are printed as ASCII text to the output file, one line per sample
point. Various options are available to modify the output decimals
places, delimiters, and so on.
Parameters
Main parameters:
- -s, --sample=LATITUDE/LONGITUDE
- The sample point for a single sampling operation. The point
is specified in terms of earth location latitude and longitude in
the range [-90..90] and [-180..180] with a datum matching that of the
input file.
- -S, --samples=FILE
- The file name containing a list of sample points for
performing multiple sampling operations. The file must be an
ASCII text file containing sample points as latitude / longitude
pairs, one pair per line, with values separated by spaces or
tabs. The points are specified in terms of earth location
latitude and longitude in the range [-90..90] and
[-180..180] with a datum matching that of the input file.
- input
- The input data file name.
- output
- The output text file name. If the output file name is '-',
output is sent to standard output (normally the terminal). In this case,
the end of the options must be indicated with a lone '--' (see the
examples) or the '-' output file name will be interpreted as an option.
Options:
- -d, --dec=DECIMALS
- The number of decimal places for printed geographic
coordinate values. The default is 6 decimals.
- -D, --delimit=STRING
- The value delimiter string. By default, values are
separated with a single space character.
- -h, --help
- Prints a brief help message.
- -H, --header
- Specifies that a one line header should be written. The
header is written before any data and consists of the output
column names. By default no header is written.
- -i, --imagecoords
- Specifies that image coordinates (row and column) should be
printed for each output line. The default is to print only
geographic coordinates.
- -m, --match=PATTERN
- The variable name matching pattern. If specified, the
pattern is used as a regular expression to match variable names.
Only variables matching the pattern will be sampled. By default,
no pattern matching is performed and all variables are sampled
unless the --variable option is used. Note that either
--variable or --match may be specified, but not
both.
- -M, --missing=VALUE
- The output value for missing or out of range data. The
default is to print 'NaN' for missing values.
- -n, --nocoords
- Turns geographic coordinate printing off. By default, each
output line has the form 'latitude longitude value(s)' but with no
coordinates, each line simply contains the data value(s).
- -R, --reverse
- Specifies that coordinates should be printed in reverse
order, 'longitude latitude'. The default is 'latitude
longitude'.
- -V, --variable=NAME1[/NAME2/...]
- The variable names to sample. If specified, the variable
sample values are printed in columns in exactly the same order as
they are listed. This option is different from the
--match option because it (i) specifies the column order,
where as --match orders the columns as the variables are
encountered in the file, and (ii) does not support pattern
matching; all variable names must be specified exactly. Without
this option or the --match option, all variables are
sampled. Note that either --variable or --match
may be specified, but not both.
- --version
- Prints the software version.
Exit status
0 on success, > 0 on failure. Possible causes of errors:
- Invalid command line option.
- Invalid input or output file names.
- Invalid sample coordinates file format.
Examples
In the example below, a sample points file named
sample_locs.txt
was set up to follow the 93 W
longitude line at regular 0.2 degree intervals as follows:
28 -93
28.2 -93
28.4 -93
28.6 -93
28.8 -93
29 -93
29.2 -93
29.4 -93
29.6 -93
29.8 -93
30 -93
and a Gulf of Mexico data file sampled for SST and cloud data along
this line with output to the terminal screen:
phollema$ cwsample --header --match '(sst|cloud)' --samples sample_locs.txt
-- 2002_325_1546_n17_mr.hdf -
latitude longitude sst cloud
28 -93 25.24 0
28.2 -93 25.24 0
28.4 -93 24.78 0
28.6 -93 23.84 0
28.8 -93 22.72 0
29 -93 21.37 0
29.2 -93 20.06 0
29.4 -93 19.29 0
29.6 -93 18.16 0
29.8 -93 17.57 6
30 -93 17.48 22
Another example shows the sampling of one SST value as in the case
of comparison with a single buoy measurement with output to the
terminal screen:
phollema$ cwsample --header --match sst --sample 28.8/-93 -- 2002_325_1546_n17_mr.hdf -
latitude longitude sst
28.8 -93 22.72