Unidata - To provide the data services, tools, and cyberinfrastructure leadership that advance Earth system science, enhance educational opportunities, and broaden participation. Unidata
         
  advanced  
 

NetCDF Subset Service for Gridded Data (version 0.2)


Please note that the interface described here is still a prototype, and subject to change.

Please send comments to the THREDDS email group (preferred) or to John Caron

See NetCDF Subset Service for an overview.

NetCDF Subset Service for Gridded Datasets

Gridded Datasets may be subset by Lat/Lon bounding box, Time, and Variable, and a netCDF file using CF-1.0 Conventions is returned. Example HTML form:

Currently vertical coordinate selection is not supported; all vertical levels are returned.

NetCDF Subset Service for Grid as Point Datasets

Gridded Datasets may be thought of as a collection of point data, with location at the center of each grid cell. The Grid as Point service requires selection of a single cell using lat/lon coordinates, then subsetting by Time, Variable, and vertical level is possible. Either an XML, CSV (Comma Seperated Values in ASCII) document or a NetCDF files in Unidata Point Observation format is returned. Example HTML form:

 

Subsetting Parameters

A. Specify subset type

B. Specify variables

The list of valid variables is available from the Dataset Description.

Examples:

Variable names with spaces or other illegal characters must be escaped. For Grid as Point, its best not to select multiple variables with different vertical coordinates, see below.

C. Specify spatial extent

Latitude, longitude values are specified in decimal degrees north and east, respectively.

1. Specify lat/lon bounding box for Grid Subsetting

Specify all of these parameters (order does not matter):

The bounding box has west as its west edge, includes all points going east until the east edge. Units must be degrees east, may be positive or negative, and will be taken modulo 360. Therefore, when crossing the dateline, the west edge may be greater than the east edge. If the grid is on a projection, the 4 corners of the lat/lon bounding box are converted into projection coordinates, then the smallest rectangle including those 4 points is used

Example:

2. Specify lat/lon point for Grid as Point Subsetting:

The requested point must lie within the dataset spatial range. The grid cell containing the requested point will be used.

Example:

3. Specify horizontal stride (Grid Subsetting only)

You can optionally take only every nth point in both the x and y dimensions.

Example:

D. Specify time

Use one of the following methods for both Grid and Grid as Point Subsetting:

1. Time range

Specify 2 of these 3 parameters (order does not matter):

The intersection of the requested time range with the dataset time range will be returned.

Examples:

2. Time point

The requested time point must lie within the dataset time range. The time slice closest to the requested time will be returned.

Examples:

E. Specify the vertical coordinate

For Grid as Point only (for now), you may specify the vertical coordinate. The vertical slice closest to the requested coordinate will be returned. The possible vertical coordinates are shown in the Dataset Descriptor document, and on the HTML form. The following indicates that variables Geopotential_height, Geopotential_height, Temperature, u_wind and v_wind all have a vertical coordinate named isobaric, with possible values 1000.0 850.0 700.0 500.0 400.0 300.0 250.0 200.0 150.0 100.0 hPa:

with Vertical Levels (isobaric) : 1000.0 850.0 700.0 500.0 400.0 300.0 250.0 200.0 150.0 100.0 hPa
Geopotential_height
Geopotential_height
Temperature
u_wind
v_wind

Variable with different vertical coordinates

If you specify multiple variables with different vertical coordinates, ambiguous results are possible, and you are advised not to use the service in this way. If you do, the following rules are used:

  1. Variables are examined in order they appear in the query, and the vertical coordinate for the first variable that has one is used.
  2. The service loops through the levels of that vertical coordinate, and for each variable looks for the closest value (ignoring units!!)
  3. If the value is outside the range for that variable, a missing value (NaN) is used.

For example, when choosing these two variables:

with Vertical Levels (isobaric1) : 850.0 700.0 500.0 250.0 hPa
Absolute_vorticity

with Vertical Levels (isobaric2) : 1000.0 850.0 700.0 500.0 400.0 300.0 hPa
Relative_humidity

The vertical coordinate from the first variable is used, giving this result:

time,lat[unit="degrees_north"],lon[unit="degrees_east"],vertCoord[unit="hPa"],Absolute_vorticity[unit="1/s"],Relative_humidity[unit="%"]
2007-05-31T18:00:00Z,32.66617895383808,-49.853769375356826,850.0,1.0700001E-4,87.0
2007-05-31T18:00:00Z,32.66617895383808,-49.853769375356826,700.0,1.1100001E-4,84.0
2007-05-31T18:00:00Z,32.66617895383808,-49.853769375356826,500.0,1.09000015E-4,54.0
2007-05-31T18:00:00Z,32.66617895383808,-49.853769375356826,250.0,1.4799999E-4,38.0

Noice that for the second variable, the 1000 and 400 levels are not returned, and the 300 level is misrepresented as being at 250. Restricting the level to a common coordinate value is sensible though:

time,lat[unit="degrees_north"],lon[unit="degrees_east"],vertCoord[unit="hPa"],Absolute_vorticity[unit="1/s"],Relative_humidity[unit="%"]
2007-05-31T18:00:00Z,32.66617895383808,-49.853769375356826,850.0,1.0700001E-4,87.0

Examples:

 

F. Specify the return format

G. Adding Lat/Lon arrays to the file

For Grid Subsetting: If the grid is a lat/lon grid, the lat and lon coordinates will be automatically included (as 1D coordinate variables). When the grid is on a projection, the lat/lon information will not be included unless the query parameter addLatLon is present. In that case, the lat, lon coordinates will be calculated and included into the file (as 2D variables).

 

NetCDF File Writing Rules


This document is maintained by John Caron and was last updated on June 18, 2007

 

 
 
  Contact Us     Site Map     Search     Terms and Conditions     Privacy Policy     Participation Policy
 
National Science Foundation (NSF) UCAR Community Programs   Unidata is a member of the UCAR Community Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.
P.O. Box 3000     Boulder, CO 80307-3000 USA     Tel: 303-497-8643     Fax: 303-497-8690