•         advanced

_Coordinate Attribute Convention (Reference)

Coordinate Systems UML

For an overview, see: Coordinate System Object Model. The Coordinate Axes for a Variable must use a subset of the Variables's dimensions.

Goals of _Coordinate Attribute Convention

1. Encode the above coordinate system information into both netcdf-3 and netcdf-4 files.
2. Easily retrofit existing files with coordinate info using NcML.
3. use the existing "Coordinate Variable" Convention to infer Coordinate Systems for legacy files
4. allow minimum annotation to existing datasets to fully specify Coordinate Systems and Transforms

Proposal

1. Add the following "standard attributes" as an endorsed way of encoding coordinate system information.
2. Create an API in both C and Java libraries to make it easy for users to follow these standards. The APIs will be optional, and built on top of the core APIs.
3. Use the attributes and APIs in Unidata software when appropriate.

See also :

• _Coordinate Attribute Examples

Contents

1. Coordinate Attributes Definition
2. Coordinate Transform Variables
3. Summary of Rules for Processing Coordinate Attributes

Coordinate Attributes Definition

_CoordinateAxes

This attribute lists (in any order) names of Coordinate Axis Variables. When a Variable is listed in a _CoordinateAxes attribute, it is made into a CoordinateAxis.

The attribute value must be a space-separated list of names of Coordinate Axis Variables in the same dataset:

    _CoordinateAxes = "time lev lat lon"; 

_CoordinateAxisType

This attribute is used on a Coordinate Axis variable to specify that it is a space or time coordinate, such as lat, lon, altitude or time. Currently the valid values are Lat, Lon, Height, Pressure, Time, GeoX, GeoY, GeoZ, RadialElevation, RadialAzimuth, or RadialDistance. This is the preferred way to make a Variable into a CoordinateAxis (the other way is to list the variable in a _CoordinateAxes attribute).

The attribute value must be one of the valid Axis types (see ucar.nc2.dataset.AxisType):

   _CoordinateAxisType = "Lat";

_CoordinateAxisTypes

This attribute is used on a Coordinate Transform variable to specify that the Transform applies to any Coordinate System with the specified list of Axis types.

The attribute value must be a list of the valid Axis types (see ucar.nc2.dataset.AxisType):

   _CoordinateAxisTypes = "GeoZ Time";

_CoordinateSystems

When many data Variables use the same Coordinate System it is convenient to factor out the information into one place. We create a dummy Variable which holds all of the information, called the Coordinate System Variable .The _CoordinateSystems attribute is used on a data Variable to point to its Coordinate System Variable(s). This is the only way to indicate multiple Coordinate Systems for the same data Variable.

The attribute value must be a space-separated list of names of Coordinate System Variables in the same dataset:

    _CoordinateSystems = "ProjectionCoordinateSystem LatLonCoordinateSystem";

   char ProjectionCoordinateSystem;
     ProjectionCoordinateSystem:_CoordinateAxes = "time depth_below_surface y x";
     ProjectionCoordinateSystem:_CoordinateTransforms = "Lambert_Conformal_Projection";

_CoordinateTransforms

The _CoordinateTransforms attribute is used only on Coordinate System Variables and is used to indicate how to transform the Coordinate System to a Reference Coordinate System. A Reference Coordinate System is one that uses Latitude, Longitude for the horizontal axes, and Height or Pressure for the vertical axes. To hold the transform information, create a dummy Variable called the Coordinate Transform Variable. This Coordinate Transform variable always has a name that identifies the transform, and any attributes needed for the transformation.

The attribute value must be a space-separated list of names of Coordinate Transform Variables in the same dataset.

   _CoordinateTransforms = "LambertProjection HybridSigmaVerticalTransform";

   char LambertProjection;
     LambertProjection:transform_name = "lambert_conformal_conic";
     LambertProjection:standard_parallel = 25.0;
     LambertProjection:longitude_of_central_meridian = 265.0;
     LambertProjection:latitude_of_projection_origin = 25.0;

This is a general mechanism for any transformation a file writer wants to define. The nj22 library has a set of transforms that it recognizes, mostly based on the CF-1 conventions. Attributes should be String, integer, or double valued.

_CoordinateTransformType

This attribute is used to unambiguously indicate that a variable is a Coordinate Transform Variable (the other way is to list the variable in a _CoordinateTransforms attribute).

The attribute value must be one of the valid Transform types (see ucar.nc2.dataset.TransformType) Currently the valid values are Projection or Vertical.

   _CoordinateTransformType = "Projection";

_CoordinateAliasForDimension

A one-dimensional variable with monotonic values can act as a coordinate variable for its dimension, even when it doesnt have the same name as the dimension. To indicate this, add an attribute to the variable called _CoordinateAliasForDimension, whose value must be the name of its single dimension. A dimension may have multiple coordinate variables in this way, for example if the data is a trajectory.

   double valtime(record);
     :long_name = "valid time";
     :units = "hours since 1992-1-1";
     :_CoordinateAliasForDimension = "record";
     :_CoordinateAxisType = "Time";

_CoordinateZisPositive

Only used for vertical coordinate axes to disambiguate direction up or down of increasing coordinate values.

The attribute value must equal "up" or "down".

  _CoordinateZisPositive = "down";

Summary of Rules for Processing Coordinate Attributes

Coordinate Axis Variable

May have attributes:

• _CoordinateAxisType
• _CoordinateAliasForDimension
• _CoordinateZisPositive

A Variable is made into a Coordinate Axis if one of these is true:

1. It has any of the _CoordinateAxisType, _CoordinateAliasForDimension, or _CoordinateZisPositive attributes.
2. It is a coordinate variable
3. It is listed in a _CoordinateAxes attribute from any variable in the file.

A Variable is a coordinate variable if it is one dimensional and one of these is true:

1. It has the same name as its dimension.
2. It has the _CoordinateAliasForDimension attribute.

Coordinate System Variable

May have attributes:

• _CoordinateAxes (required, must be a complete list of axes, must have at least one axis).
• _CoordinateTransforms

A variable is a Coordinate System Variable if one of these is true:

1. It has a _CoordinateTransforms attribute.
2. It is listed in a _CoordinateSystems attribute from any variable in the file.

Coordinate Transform Variable

May have attributes:

• _CoordinateTransformType
• _CoordinateSystems apply to these Coordinate Systems
• _CoordinateAxes apply to any Coordinate Systems that contain all these axes
• _CoordinateAxisTypes apply to any Coordinate Systems that contain all these types of axes

A variable is a Coordinate Transform Variable if one of these is true:

1. It has a _CoordinateTransformType or _CoordinateAxisTypes attribute.
2. It is listed in a _CoordinateTransforms attribute from any variable in the file.

Data Variables

May have attributes:

• _CoordinateSystems
• _CoordinateAxes

You should use one or the other. If both are present, _CoordinateSystems is used.

A Data Variable is assigned one or more Coordinate Systems in the following way:

1. If it has a _CoordinateSystems attribute, it is assigned the listed Coordinate Systems, and no further processing is done.
2. If it has a _CoordinateAxes attribute, it will have one Coordinate System consisting of the listed _CoordinateAxes plus any Coordinate Variables that it uses which are not listed. Must have at least 2 axes.
3. Otherwise it will have one Coordinate System consisting of the Coordinate Variables that it uses.
4. If CoordSysBuilder.useMaximalCoordSys is true (default is true), and all the following conditions are true:
   1. A Data Variable has none or one implicit Coordinate System.
   2. Its implicit Coordinate System (if it exists) has fewer axes than the rank of the Variable.
   Then all Coordinate Axes are examined, and a Coordinate System is made out of all that fit the Variable. If this Coordinate System has 2 or more axes, then it is assigned to the Variable. This is called the maximal algorithm.

Notes

1. Data Variable _CoordinateAxes may be partial listing, Coordinate variables will be added. ??
2. Variables of type Structure cannot be a coordinate axis.
3. A Coordinate System is defined by its list of Coordinate Axes, so two Coordinate System can't have same list of axes.
4. _Coordinate attributes will take precedence over Conventions in our own decoding. Other software may implement differently.
5. When Coordinate Systems have been added, to prevent adding again, NcML writing adds the global attribute :Conventions = "_Coordinates". ??

This document is maintained by John Caron and was last updated on Apr 11, 2007

Contact Us   •   Site Map   •   Search   •   Terms and Conditions   •   Privacy Policy   •   Participation Policy

Unidata is a member of the UCAR Office of 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