noaa.coastwatch.tools.cwsample

public class cwsample extends Object

The sampling tool extracts data values at specified earth locations.

Name

cwsample - extracts data values at specified earth locations.

Synopsis

cwsample [OPTIONS] input output

Sampling type options:

-s, --sample=LATITUDE/LONGITUDE
-S, --samples=FILE

General options:

-d, --dec=DECIMALS
-D, --delimit=STRING
-h, --help
-H, --header
-i, --imagecoords
-m, --match=PATTERN
-M, --missing=VALUE
-n, --nocoords
-R, --reverse
-t, --statsvar=NAME
-V, --variable=NAME1[/NAME2/...]
-w, --window=N
--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:

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.

Sampling type options:

-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.

General 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'.

-t, --statsvar=NAME

The variable name to compute statistics. If specified, the named variable is used to compute statistics using the values within an NxN window surrounding each sample point. The statistics are reported on each output line as:

Count - the count of total data values sampled
Valid - the number of valid (not missing) data values
Min - the minimum data value
Max - the maximum data value
Mean - the average data value
Stdev - the standard deviation from the mean
Median - the median data value

See also the --window option to set the window size. The default is not to compute statistics and only report the variable sample values at the sample points.

-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.

-w, --window=N

The window size in pixels for computing statistics. The default is to use a 3x3 window. Only odd values are allowed: 3, 5, 7, etc. This option is only relevant when the --statsvar option is also specified.

--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:

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

Since:: 3.1.0
Author:: Peter Hollemans

Method Summary

Modifier and Type

Method

Description

static void

main(String[] argv)

Performs the main function.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- main
  
  public static void main(String[] argv)
  
  Performs the main function.
  
  Parameters:
  
  argv - the list of command line parameters.

Class cwsample

Name

Synopsis

Sampling type options:

General options:

Description

Parameters

Main parameters:

Sampling type options:

General options:

Exit status

Examples

Method Summary

Methods inherited from class java.lang.Object

Method Details

main