Every Metcast server offers a reflexive facility: an ability to describe what it can deliver, both in principle and in reality. The server can send the comprehensive menu of products and indicate which products on that list are actually present in the Metcast database and thus available for immediate download. A server can also tell how to build a Request Language phrase to ask for a desired product.
The reflexive facility is implemented by Metcast server modules that accept Describe MBL requests and send Metcast Table of Contents documents in reply. The Metcast Table of Contents (MTOC) is an XML format introduced in [MTOC]. An MTOC document is a collection of descriptions for one or several product categories. The present web page specifies the format and semantics of the table of contents for one particular category: multi-dimensional gridded products.
The XML format introduced here can potentially available gridded products (a potential MTOC, [MTOC]) as well as particular grids that are currently in a database (an actual MTOC).
The potential TOC should list forecast times (aka 'taus'), which a grid model is configured to compute. In contrast, the actual TOC should list valid-times and reference-times for computed products. There should be no taus in the actual TOC (nor in actual products).
Normally a single product (e.g, a temperature grid) can be available at many different levels and at many valid times -- as well computed by several models at several configurations for several areas of interest. We should group the descriptions to avoid unnecessary repetition. Furthermore, the grouping must reflect which vertical and time slices are merged within a single GRDValue of the datablade. Interpolation in time or in Z is only available within one GRDValue.
The datablade has an ability to convert grids from one projection to another. It can store an output of an MM5 model in the Lambert-Conformal projection and give the user a section of that grid in the Equidistant-Cylindrical (Lat/Lon) projection. What would be the resolution of that grid, and how a user would specify it? This is a tricky question. Suppose the original MM5 data had the resolution of 10 km at the standard parallel 30N. The database can give data in Equidistant-Cylindrical projection at the resolution 0.3 deg, or 0.4 deg, or 0.5 deg -- or any other resolution the user can request. Clearly some of these requests are saner than the other. How to tell the user which resolution is preferred and which is native? That's the big problem. I don't know the answer. I would greatly appreciate if somebody gave a hint or just explained what forecasters or mission-planning users want.
An element
grids describes 2D-4D grid products
currently available from a Metcast server. The products are delivered
as GIEF NetCDF files -- therefore, a request and the description of a
product follow guidelines set in the GIEF standard. The names of the
layers and the projections are relatively constant. Therefore, this
constant information is factored out into separate tables, described
by elements
levels and
projections. Separate
grid products refer to the projections and the levels by their ids, as
was explained in the introduction.
The top element of MTOC-grids
| XML DTD | |
|---|---|
<!ELEMENT grids ( levels, projections, model* )?> |
| TStamp-OPT | ||
|---|---|---|
| Time Stamp of the moment this description was created | ||
|
This attribute may be omitted, in which case a TStamp attribute of the parent
MTOC element is assumed. | ||
| HREF | ||
| A re-direction URL | ||
|
If present, this attribute redirects the client to another Metcast server, which presumably supports gridded products. | ||
<!ATTLIST grids %TStamp-OPT; %HREF-redir; > |
The element
levels defines a table of parameter
levels, as specified by the GIEF document. This element describes a
relatively constant information.
| XML DTD | |
|---|---|
<!ELEMENT levels ( level-desc )+> |
The element
level-desc describes a single GIEF
level. The attributes give the name to be used in an MBL request and
the applicable units. The name is a unique identifier of the level,
defined by the GIEF standard, and is referred to within elements
representing particular products. A
Title attribute may
specify a textual description for the level. As usual, if this
attribute is omitted, the
Name attribute is assumed to
provide a detailed enough description.
| XML DTD | |
|---|---|
<!ELEMENT level-desc EMPTY> |
| Name | ||
|---|---|---|
| A unique identifier for the level | token
ID | |
|
This name is used in le elements and MBL requests. | ||
| Title | ||
| A textual description for the level | varchar or omitted
CDATA | |
| Units | ||
| Units of measurement for the argument that defines a level | ||
|
For example, an isobar level is characterized by a pressure value, in hectoPascals. Other levels (for example, tropopause or
surface) do not have associated parameters. In this case, this
Units attribute is omitted. | ||
<!ATTLIST level-desc Name ID #REQUIRED Title CDATA #IMPLIED %Units; > |
A General Entity
STD-LEVELS defines a set of
levels in effect (as set forth in the GIEF standard). A gridded product
may refer to a level by its unique id. Note, this general entity may
be specified via an external reference -- for example,
SYSTEM
"http://metcast/cgi-bin/oleg/server/levels/" -- rather than by an
explicit string.
| XML DTD | |
|---|---|
<!ENTITY STD-LEVELS "
<levels>
<level-desc Name='isbr_lvl' Units='hPa'/>
<level-desc Name='msl' Title='Mean Sea Level'/>
<level-desc Name='surface' Title='surface of earth/sea'/>
<level-desc Name='isth_lvl' Title='isothermal level'/>
<level-desc Name='max_wnd_lvl'/>
<level-desc Name='trpp_lvl'
Title='tropopause level (top of troposphere)'/>
<level-desc Name='atms_top' Title='top of atmosphere'/>
<level-desc Name='ocn_bot' Title='ocean bottom'/>
<level-desc Name='isbr_lay'
Title='layer between 2 isobaric levels'/>
<level-desc Name='ht_sfc' Title='height above earth/sea surface'/>
<level-desc Name='sgma_lvl' Title='sigma level'/>
<level-desc Name='isnt_lvl'
Title='isentropic level (constant temp)'/>
<level-desc Name='ht_msl' Title='height above mean sea level'/>
<level-desc Name='dpth_sfc' Title='depth below sea surface'/>
<level-desc Name='mix_lay'
Title='mixed layer (in ocean; shallow, isothermal)'/>
<level-desc Name='ocn_lay' Title='layer between 2 depths in ocean'/>
<level-desc Name='atms_lay'
Title='layer between 2 heights in atmosphere'/>
<level-desc Name='flt_lvl_dom' Title='flight level domain'/>
<level-desc Name='isbr_lvl_dom' Title='Isobaric level domain'/>
<level-desc Name='sky_cvr' Title='full depth of atmospheres'/>
<level-desc Name='dpth_sfc_dom' Title='Depth levels domain'/>
<level-desc Name='ocn' Title='ocean (generic)'/>
<level-desc Name='blw_snd_lay'
Title='below sound layer (100 ft immediately below)'/>
<level-desc Name='shlw_snd_chan'
Title='shallow sound channel (layer in ocean)'/>
<level-desc Name='deep_snd_chan' Title='deep sound channel'/>
<level-desc Name='low_cld' Title='low cloud layer'/>
<level-desc Name='mid_cld' Title='middle cloud layer'/>
<level-desc Name='hi_cld' Title='high cloud layer'/>
<level-desc Name='deep_lay' Title='between 100 and 1000mb'/>
<level-desc Name='fcst_per_dom' Title='Forecast period domain'/>
<level-desc Name='freq_ix' Title='frequency index'/>
<level-desc Name='ht_sfc_dom' Title='height surface domain'/>
<level-desc Name='snd_lay'
Title='sound layer (sonic layer in ocean)'/>
<level-desc Name='thcl_grad'
Title='temperature gradient of thermocline upper portion'/>
<level-desc Name='thcl_lvl' Title='thermocline level'/>
<level-desc Name='trns_lay'
Title='transient layer (in ocean; shallow, afternoon)'/>
<level-desc Name='vert_xsct' Title='vertical cross section'/>
<level-desc Name='flight_lvl'
Title='altitude below 18,000 ft' Units='ft'/>
</levels>"> |
The set of projections is relatively constant. Therefore, it is factored out in a separate table, described by the following element.
| XML DTD | |
|---|---|
<!ELEMENT projections ( projection-desc )+> |
The element
projection-desc describes a single
mapping projections used by the grid datablade. Its attribute
Name gives a unique identifier of the projection, which is used
in a
projection element in the description of a
particular model. This identifier is also used in MBL requests. A
Title attribute may specify a more detailed textual
description. As usual, if this attribute is omitted, the
Name attribute is assumed to provide a detailed enough
description. The contents of
projection-desc is a SRTEXT
string as defined by the OpenGIS specification and the Informix
Datablade.
| XML DTD | |
|---|---|
<!ELEMENT projection-desc (#PCDATA)> |
| Name | ||
|---|---|---|
| A unique identifier for the projection | token
ID | |
|
This name is used within the projection elements and MBL requests. | ||
| Title | ||
| A textual description for the level | varchar or omitted
CDATA | |
<!ATTLIST projection-desc Name ID #REQUIRED Title CDATA #IMPLIED > |
A General Entity
STD-PROJECTIONS defines a set of
projections in effect. The description of a gridded product refers to
the projection by the projection's unique id. This general entity may
be specified via an external reference -- for example,
SYSTEM
"http://metcast/cgi-bin/oleg/server/projections/" -- rather than
by an explicit string.
| XML DTD | |
|---|---|
<!ENTITY STD-PROJECTIONS "
<projections>
<projection-desc Name='GCS_North_American_1983'
Title='NAD 1983 datum for use with unprojected lat/lon coords'>
GEOGCS["GCS_North_American_1983",
DATUM["D_North_American_1983",
SPHEROID["GRS_1980",6378137,298.257222101]],
PRIMEM["Greenwich",0],UNIT["Degree",0.0174532925199433]]
</projection-desc>
<projection-desc Name='Africa_Lambert_Conformal_Conic5'
Title='Lambert Conformal Projection'>
PROJCS["Africa_Lambert_Conformal_Conic",
GEOGCS["GCS_North_American_1983",
DATUM["D_North_American_1983",SPHEROID["GRS_1980",6378137,2
98.257222101]],PRIMEM["Greenwich",0],
UNIT["Degree",0.0174532925199433]],
PROJECTION["Lambert_Conformal_Conic"],
PARAMETER["False_Easting",1621611.1571984319016337],
PARAMETER["False_Northing",-2389687.7325572799891233],
PARAMETER["Central_Meridian",-117.5499999999999972],
PARAMETER["Standard_Parallel_1",60.0000000000000000],
PARAMETER["Standard_Parallel_2",30.0000000000000000],
PARAMETER["Latitude_Of_Origin",0],UNIT["Meter",1]]
</projection-desc>
</projections>"> |
The element
model specifies a particular weather
model run at the originating center. The model computes a set of
gridded products, which are described by child elements.
| XML DTD | |
|---|---|
<!ELEMENT model (projection, parameter*)> |
| Name | ||
|---|---|---|
| The name of the model | token
NMTOKEN | |
|
Example: NOGAPS | ||
| Publisher | ||
| The name of an originating center | varchar
CDATA | |
|
This is the official name of an organization that collects observations, reconciles them, runs weather models, and produces gridded products further described in child elements. | ||
| Area | ||
| The name of the geographical area and model run | tokens
NMTOKENS | |
|
The contents of this field is one or two tokens. The first is the name of the geographical area for which the model is configured. The second parameter, if present, is a model schedule or a similar identifier (e.g., PRELIM for a NOGAPS
model). Together these tokens identify a particular model
configuration. | ||
<!ATTLIST model Name NMTOKEN #REQUIRED Publisher CDATA #REQUIRED Area NMTOKENS #REQUIRED > |
This element describes the projection of the grids produced by the model.
| XML DTD | |
|---|---|
<!ELEMENT projection EMPTY> |
| Id | ||
|---|---|---|
| The identifier of the projection | token
IDREF | |
|
The identifier refers to a projection-desc element | ||
| BBox | ||
| The bounding box for the model | ||
| Resolution | ||
| The resolution of the model | list of numbers
NMTOKENS | |
|
This is the geographical resolution of the model, in the units specified by model's projection. For unprojected grids the resolution is in degrees of the great circle. For projected grids, the resolution is usually in meters. See the UNITS parameter in SRTEXT, the body of the element projection-desc. | ||
| MaxRows | ||
| The maximum number of rows in the grid | integer or omitted
NMTOKEN | |
|
This attribute is included only if the request for description specifically asks for it. | ||
| MaxCols | ||
| The maximum number of columns in the grid | integer or omitted
NMTOKEN | |
|
This attribute is included only if the request for description specifically asks for it. | ||
<!ATTLIST projection Id IDREF #REQUIRED %BBox-REQD; Resolution NMTOKENS #REQUIRED MaxRows NMTOKEN #IMPLIED MaxCols NMTOKEN #IMPLIED > |
The element
parameter describes a single
geophysical or meteorological quantity. It is represented by a grid of
values for one or several vertical levels (layers) -- for example,
isobars, height or depth levels, the surface or the mean-sea
layers. The latter are described in child elements.
In a potential MTOC, the element describes the layers that may
be available in the database. An element
valid-time will
be absent then.
In an actual MTOC, an element
parameter corresponds
to one GRDValue -- a 4D element of the grid datablade.
| XML DTD | |
|---|---|
<!ELEMENT parameter (le, (le* | valid-time))> |
| Name | ||
|---|---|---|
| The name of the parameter | varchar
CDATA | |
|
Example: Air Temperature | ||
| Units | ||
| The units of measurement for the parameter | ||
| ComponentCount | ||
| The number of components in the parameter | integer
NMTOKEN | |
|
For scalar parameters such as Air temperature or Pressure, this attribute has the value of 1 (which is the default). For Winds, which are characterized by u- and v- components, this attribute has the value of 2. | ||
<!ATTLIST parameter Name CDATA #REQUIRED %Units; ComponentCount NMTOKEN '1' > |
This element specifies an atmospheric, depth, surface, cloud,
etc. level of a geophysical quantity described by the parent
parameter element. Level's description, an identifier to use in the
request language, units for additional parameters if any, etc. are
factored out into a
level-desc element. The content of a
le element are values of the level parameters, for example,
the pressure value for an isobar layer. The content may be empty if
the level does not require any specialization parameters (e.g., the
surface level).
In an actual MTOC, the element describes the vertical dimension
of the GRDValue represented by the parent element
parameter.
| XML DTD | |
|---|---|
<!ELEMENT le ANY> |
| Id | ||
|---|---|---|
| The identifier of the level | token
IDREF | |
|
The identifier refers to a level-desc element. | ||
| Forecast-time | ||
| The set of forecast times in the model configuration for this level | tokens or omitted
NMTOKENS | |
|
This attribute is present only in a potential MTOC. This attribute specifies forecast times that the model is supposed to produce for this particular level. In general, different levels or sets of levels have their own set of forecast times. Not every model run however will result in the complete set of forecast products: some of them may be missing. | ||
| Forecast-time-units | ||
| The units for the forecast time | tokens
NMTOKENS | |
<!ATTLIST le Id IDREF #REQUIRED Forecast-time NMTOKENS #IMPLIED Forecast-time-units NMTOKENS 'hrs' > |
This child element of
parameter is present only in an
actual MTOC. This element describes the time dimension of the GRDValue
represented by the parent element
parameter.
| XML DTD | |
|---|---|
<!ELEMENT valid-time ANY> |
| Ref | ||
|---|---|---|
| The reference time | datetime
NMTOKENS | |
|
This is the initialization time for the model that produced the data -- which serves as the base time for the computed forecasts. | ||
| TStamp-units | ||
| The units of measure for the values in the content of the element | ||
|
If this attribute is omitted, the valid time is measured in EPOCH seconds. This element may be specified as TStamp-units='hrs since 2002-08-05 1200' in which case the valid
time will be in hours since the base time. | ||
<!ATTLIST valid-time Ref NMTOKENS #REQUIRED %TStamp-units; > |
<!DOCTYPE MTOC SYSTEM "MTOC.dtd">
<!-- HREF here is the main URL of the server -->
<MTOC TStamp='1029557742' HREF='http://zowie/cgi-bin/oleg/server'>
<grids>
&STD-LEVELS;
&STD-PROJECTIONS;
<model Name='NOGAPS' Publisher='US Navy - FNMOC'
Area='global_360x181'>
<projection Id='GCS_North_American_1983' BBox='90 -180 -90 180'
Resolution='1.0 1.0' MaxRows='181'
MaxCols='360'/>
<parameter Name='Geopotential Height' Units='gpm'>
<le Id='isbr_lvl'
Forecast-time='0 3 6 120'> <!-- default units: hrs -->
1013 1000 700</le>
<le Id='isbr_lvl' Forecast-time='0 6 120'>975 500</le>
<le Id='surface' Forecast-time='0 6 120'></le>
</parameter>
</model>
<model Name='COAMPS' Publisher='US Navy - FNMOC, DAMPS'
Area='COAMPS_Eur'>
<projection Id='Africa_Lambert_Conformal_Conic5'
BBox='47.0 -12.0 29.0 40.0'
Resolution='10000 10000'/>
<parameter Name='Geopotential Height' Units='gpm'>
<le Id='isbr_lvl' Forecast-time='0 3 6'>
1013 1000 975 700 500</le>
<le Id='surface' Forecast-time='0 3 6'></le>
</parameter>
<parameter Name='Wind' Units='m/s' ComponentCount='2'>
<le Id='surface' Forecast-time='0 3 6'/>
<le Id='isbr_lvl' Forecast-time='0 3 6'>1000 925</le>
</parameter>
</model>
</grids>
</MTOC>
|
<!DOCTYPE MTOC SYSTEM "MTOC.dtd">
<!-- HREF here is the main URL of the server -->
<MTOC TStamp='1029557742' HREF='http://zowie/cgi-bin/oleg/server'>
<grids>
&STD-LEVELS;
&STD-PROJECTIONS;
<model Name='NOGAPS' Publisher='US Navy - FNMOC'
Area='global_360x181'
>
<projection Id='GCS_North_American_1983' BBox='90 -180 -90 180'
Resolution='1.0 1.0' />
<!-- the parameter below is within one GRDValue -->
<parameter Name='Geopotential Height' Units='gpm'>
<le Id='isbr_lvl'>1013 1000 975 700 500</le>
<valid-time Ref='20020805T1200' TStamp-units='hrs since 2002-08-05 1200'>
3 6 12</valid-time>
</parameter>
<!-- another GRDValue -->
<parameter Name='Geopotential Height' Units='gpm'>
<le Id='surface'></le>
<valid-time Ref='20020805T1200'>
20020805T1500 20020805T1800 20020806T0000</valid-time>
</parameter>
</model>
</grids>
</MTOC>
|
A user can obtain the description of gridded products available
from a Metcast server by submitting a
Describe MBL
request or by fetching a particular URL. The latter method is
particularly appropriate for interactive use: the user may type the
URL into any browser of his choice. The table below lists MBL requests
and URLs. As you may have noticed, there are several ways to get a
description. All the ways converge to the same describer procedure,
however.
We can use the following requests to check to see if a particular
Metcast server supports
grids at all.
http://www.metnet.navy.mil/cgi-bin/oleg/server/grids (descr (products
(Describe (grids (describe-scope short)))))
(descr (products
(Describe (path "grids"))))
If the product
grids is not available the last
MBL request and the URL query return an empty reply (HTTP status code
304) rather than an error reply.
The following group of requests returns the potential table of contents for grids -- the list of all gridded products that are in principle available from a particular Metcast server. However, at any given time some parameters, levels or taus may be missing for various reasons.
http://www.metnet.navy.mil/cgi-bin/oleg/server/grids/ (descr (products
(Describe (grids))))
(descr (products
(Describe (path "grids" ""))))
The full list of available products can be quite large. Therefore, a user may want to request only a subset of the list, for gridded products that: have a particular name or a name pattern; are added to the potential TOC after a specific time moment; cover a particular bounding rectangle; computed by a specified model at a particular originating center.
For example, the following request returns the list of all products produced by a model NOGAPS at FNMOC:
(descr (products
(Describe (grids (model NOGAPS) (publisher "%FNMOC%"))))))
The present group of requests returns the actual MTOC-grids, which describes gridded products with the particular name(s) or name patterns. In addition, we can restrict the returned MTOC to the products of a particular center, given model, describing a particular area of the globe, or valid at a particular time.
http://www.metnet.navy.mil/cgi-bin/oleg/server/grids/Air%20Temperature (descr (products
(Describe (grid "Air Temperature"))))
(descr (products
(Describe (path "grids" "Air Temperature"))))
Air
Temperature products (case matters).
(descr (products
(Describe (grid ("Air Temperature" "Surface Pressure")))))
http://www.metnet.navy.mil/cgi-bin/oleg/server/grids/%25temp%25 (descr (products
(Describe (grid "%temp%"))))
(descr (products
(Describe (path "grids" "%temp%"))))
temp. For these approximate match requests,
case does not matter. Character
% is a SQL wildcard match
character. When used in URL, the percent sign has to be quoted as
%25. The product name pattern must contain at least one
non-wildcard character.
The MBL phrases requesting a description of grids look similar to
the phrases requesting the grids themselves. The analogy goes deeper. When
asking for a grid, we can specify, in addition to the product name,
various other selection keys, for example:
modified-since,
bounding-box,
publisher,
model, and
valid-time. These keys, if present, limit the set
of returned grids to those matching all the keys. Likewise, we can
limit the description of grids by using additional selection keys
-- the keys mentioned above. MBL is better suited for such
complex description queries. We can still use URLs for some
description requests. We should specify additional keys as
name%20value pairs separated by slashes. These URLs quickly
become unwieldy however.
http://www.metnet.navy.mil/cgi-bin/oleg/server/grids/Air%20Temperature/model%20NOGAPS
(descr (products
(Describe (grid "Air Temperature" (model NOGAPS)))))
Air
Temperature products currently in the datablade that are produced by
a NOGAPS model.
http://www.metnet.navy.mil/cgi-bin/oleg/server/grids/Air%20Temperature/model%20NOGAPS/publisher%20\"FNMOC\"
(descr (products
(Describe (grid "Air Temperature"
(model NOGAPS) (publisher "FNMOC")))))
(prod-describe
(products
(Describe
(grid "%Temp%"
(bounding-box 30 -140 10 -100)
(model NOGAPS)
(valid-time 1021906800 1021917000)))))
Temp (case insensitive), which cover the geo-rectangle
30N 140W - 10N 100W, which were computed by a model
NOGAPS, and which are valid either for
2002-05-20 15:00:00 or
Mon May 20 17:50:00 2002.
[ISO8601] ISO 8601. Date and Time formats
<
http://www.mcs.vuw.ac.nz/technical/software/SGML/doc/iso8601/ISO8601.html>
<
http://www.cl.cam.ac.uk/~mgk25/iso-time.html>
[GIEF] Grid Interchange Format (GIEF)
<
http://www.metnet.navy.mil/~hofschnr/>
[MTOC-DTD] MTOC DTD
<
http://www.metnet.navy.mil/Metcast/XML/MTOC.dtd>
[MTOC-sample] A sample actual MTOC document
<
MTOC-grids-act.xml>
[PTOC-sample] A sample potential MTOC document
<
PTOC-sample.xml>
[Metcast-Intro] Introduction to Metcast
<
http://www.metnet.navy.mil/Metcast/Metcast-Intro.html>
[MBL] A Guide to MBL - a Metcast Request Language
<
http://www.metnet.navy.mil/Metcast/Request-Lang.html>
Converted from SXML by SXML->HTML