# Re: 2D coordinate variables

John Sheldon (jps@gfdl.gov)
Mon, 2 Jun 1997 17:59:21 -0400 (EDT)

Hi again,

I've been away for a while, but this thread seems to have run out of
steam without being resolved. Let me comment (for what it's worth) on
the last entry and maybe we can reach some stable (if unfinished)
conclusion.  (Pardon the inclusion of old mail contents, but it's
probably necessary for continuity...)

Brian Eaton wrote:

> The concept of "referential attributes" is not well defined.  In recent
> postings to the netCDF group I have seen them used in the following
> ways.
> The first 2 examples are from the document
> http://www.unidata.ucar.edu/software/netcdf/NUWG/draft.html.
>
> EXAMPLE 1.
>
> > The referential concept is also useful in the second problem with hybrid
> > grids which contain a relative vertical coordinate "z". An example is where
> > a vertical level of a grid point value may be related to pressure, in
> > variable "p", or to the virtual potential temperature in variable "vpt". So
> > the referential attribute can be used as follows:
> >
> >         float u(record, z, x, y);
> >                 u:z = "vpt, p";
> >
> > This defines for grid value u(1,2,1,1) that the value for the "z" dimension
> > of "u" can be found in p(1,2,1,1) or vpt(1,2,1,1).
>
> Assuming that p and vpt have been defined by
>
>         float p(record, z, x, y);
>         float vpt(record, z, x, y);
>
> then it is implicit that u, p, and vpt are defined on the same grid (this
> is one reason for having named dimensions in netCDF) and hence that the
> values of p and vpt corresponding to u at gridpoint (1,2,1,1) are given by
> p(1,2,1,1) and vpt(1,2,1,1).  The referential attribute z does not provide
> any information about the relative vertical coordinate z, e.g., how is it
> defined, what are its values, and how are these values related to some
> physical variable like pressure.

The point here was that referential attributes provide a *mechanism*
for associating variables.  The referential attribute z *does* provide
information about the relative vertical position of the data points,
but it is given in terms of "p" and "vpt", which are simply two
alternate ways of specifying the vertical position of meteorological
data.  Your objection to the lack of an actual "z" cooridinate is
solved by specifying the attribute as 'u:z = "vpt, p, alt" ', where a
variable "alt" could be provided to document the actual altitude of the
points.  The variable "alt" would carry along its own metadata
documenting how it was calculated (eg, hypsometric equation, virtual
temperature correction, etc...).

> EXAMPLE 2.
>
> > In a simpler case, where the grid is defined for set levels, we can define
> > such referential attributes as:
> >
> >         dimensions:
> >                 z = 3;
> >
> >         variables:
> >                 float u(record,z,x,y);
> >                       u:z = "levels";
> >
> >                 float levels(z);
> >
> >         data:
> >                 levels = 1000.0, 850.0, 500.0;
>
> This is exactly the case that 1D coordinate variables handle so well.  This
> file should be set up as follows:
>
...
This example is simply the trivial case, provided as an illustration
of how the indirection works, in case somebody didn't catch on to the
somewhat more complicated earlier example.

> I have recently seen two other examples of how referential attributes are
> supposed to work.  In response to a question about representing the
> longitudes and latitudes at a collection of points John Sheldon
> suggested:
>
> EXAMPLE 3.
>         dimensions:
>                 npoint = 10;
>         variables:
>                 float lon(npoint);
>                          lon:long_name = "longitude" ;
>                          lon:units = "degrees_east" ;
>                 float lat(npoint);
>                          lat:long_name = "latitude" ;
>                          lat:units = "degrees_north" ;
>                 float data(npoint);
>                          data:npoint = "lon,lat";
>
> And John Caron has pointed out that the problem the NUWG was attempting to
> solve with referential attributes was:
>
> EXAMPLE 4.
>         dimensions:
>                 ntime = 10;
>         variables:
>                 float ref_time(ntime);
>                          ref_time:long_name = "reference time" ;
>                          ref_time:units = "hours since 1970-01-01 00:00:00" ;
>                 float fcst_time(ntime);
>                          fcst_time:long_name = "forecast time" ;
>                          fcst_time:units = "hours since 1970-01-01 00:00:00" ;
>                 float data(ntime);
>                          data:ntime = "ref_time,fcst_time";
>
> Examples 1 (just considering the z dimension), 3 and 4 use the same syntax
> to describe quite different data relationships.

Yup. Pretty powerful, huh?

> Finally there was the recent suggestion by John Sheldon for using
> referential attributes to describe 2D coordinates.  Essentially we have
>
> EXAMPLE 5.
>
> > dimensions:
> >         ni = 4 ;
> >         nj = 3 ;
> > variables:
> >         float mydata(nj,ni) ;
> >            mydata:nj = "latarr";
> >            mydata:ni = "lonarr";
> >         float latarr(ni,nj) ;
> >         float lonarr(ni,nj) ;
>
> The data relationships being expressed here are quite different from the
> preceeding examples, AND the syntax is different so there is a possibility
> of making an unambiguous definition of what is meant by the referential

This is, indeed, an extension of the examples already given, but only
in that the rank of the referenced variable is larger than in the
previous examples.  In all cases, one still has to know how to
interpret the referenced variable (a bit complicated, but one could,
conceivably, infer a relationship base on the shape of the referenced
variable).  There are no established conventions here - we're just
suggesting some alternatives that fit within the conventions that have

> attributes.  But consider John Caron's suggestion for the same problem:
>
> EXAMPLE 6.
>
> > dimensions:
> >         lat = 4 ;
> >         lon = 3 ;
> > variables:
> >         float lat(lat,lon) ;
> >         float lon(lat,lon) ;
> >         float mydata(lat,lon) ;
>
> I believe this is a natural generalization of the coordinate variable
> concept.  I don't see what the extra level of indirection inherent in
> referential attributes buys us, especially in light of the current state of
> confusion about what a referential attribute is supposed to represent.

I see where you're going, but this is one solution that does *not* fit
within the conventions that have already been established, because
there is a long-standing convention that variables with the same name
as a dimension are "coordinate variables", and should be one-
dimensional vectors containing the coordinates of the points along that
dimension.  This is not to say that you couldn't write your own
application to use such data - all the information you need is, indeed,
present.  But you will have some difficulty getting any existing

Note that, in Example 6, there is also no explicit metatdata linking
"mydata" with the variables "lat" and "lon".  Assuming that an
application could ignore the problem of violating the "coordinate
variable" convention, for all it knows, the 3 variables "lat", "lon",
and "mydata" could be temperature, humidity, and wind speed.  However,
if you rename the "lat" and "lon" variables slightly (say, to "lat1"
and "lon1") to avoid violating the convention regarding coordinate
variables, then add the attribute 'mydata:lat = "lat1,lon1"' you've
accomplished your goal without commiting a foul.  All you've done is
make explicit the connection you were merely implying in your example.
is supposed to represent" is no different than the confusion over how
an application is supposed to figure out that "lat(lat,lon)" is really
a 4x3 array of latitudes.

BTW, I've already heard (off-line) from the FERRET authors that FERRET
chokes on the style given in Example 6, but accepts Example 5.  Perhaps
other application developers out there could comment on this.  Also,
would anyone at Unidata, NUWG, or COARDS care to throw in their \$0.02?

John P. Sheldon
(jps@gfdl.gov)
Geophysical Fluid Dynamics Laboratory/NOAA
Princeton University/Forrestal Campus/Rte. 1
P.O. Box 308
Princeton, NJ, USA  08542

(609) 987-5053 office
(609) 987-5063 fax
---
"For every problem, there is one solution which is simple,
neat, and wrong."
-- H.L. Mencken --
---