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:

• http://motherlode.ucar.edu:8080/thredds/ncss/grid/fmrc/NCEP/NAM/CONUS_80km/NCEP-NAM-CONUS_80km_best.ncd/dataset.html

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:

• http://motherlode.ucar.edu:8080/thredds/ncss/grid/fmrc/NCEP/NAM/CONUS_80km/NCEP-NAM-CONUS_80km_best.ncd/pointDataset.html

 

Subsetting Parameters

A. Specify subset type

• point="true" indicates the Grid as Point subset service
• otherwise, you are using the Grid subset service

B. Specify variables

• var=name of variables, separated by ',' (comma).

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

Examples:

• var=QCSurface
• var=QC,LZT,PQ
• var=T&var=Pressure&var=RH (allowed, but comma seperated names are preferred)

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

• north: latitude north (decimal degrees)
• south: latitude south (decimal degrees)
• east: longitude east (decimal degrees)
• west: longitude west (decimal degrees)

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:

• north=17.3&south=12.088&west=140.2&east=160.0

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

• latitude: latitude of point, decimal degrees north
• longitude: longitude of point, decimal degrees east

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

Example:

• latitude=17.3&longitude=-140.2

3. Specify horizontal stride (Grid Subsetting only)

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

Example:

• horizStride=3 (take every 3rd point in both x and y)

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

• time_start: starting time as an W3C date string or "present"
• time_end: ending time as an W3C date string or "present"
• time_duration: length of time as an W3C time duration

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

Examples:

• time_start=2007-03-29T12:00:00Z&time_end=2007-03-29T13:00:00Z (between 12 and 1 pm Greenwich time)
• time_start=present&time_duration=P3D (get 3 day forecast starting from the present)
• time_end=present&time_duration=PT3H (get last 3 hours)

2. Time point

• time: time as an W3C date string or "present"

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

Examples:

• time=2007-03-29T12:00:00Z
• time=present

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:

• vertCoord=850

 

F. Specify the return format

• For Grid Subsetting, only accept=netcdf is supported.
• For Grid as Point subsetting, accept=xml or accept=csv or accept=netcdf are supported.

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

• A valid NetCDF file is returned in CF-1 format.
• The specified variables(s) and their attributes are included.
• All coordinate variables for the specified variable(s) are included.
• If a bounding box or time range is specified, the variable and its coordinates are subsetted.
• All global attributes are included.