Coordinate Systems UML

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

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

- Add the following "standard attributes" as an endorsed way of encoding coordinate system information.
- 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.
- Use the attributes and APIs in Unidata software when appropriate.

- _Coordinate Attribute Examples

- Summary of the CDM _Coordinate Conventions
- Coordinate Attributes Definition
- Summary of Rules for Processing Coordinate Attributes

A Transform is defined by creating a Coordinate Transform Variable (see Example and Reference). The attributes of the Coordinate Transform Variable become the parameters of the transform. A variable is a Coordinate Transform Variable if one (or both) of these is true:

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

Any Variable can be a Coordinate Transform Variable, as it is just a container for attributes, i.e. the data values of the Variable are not used by the
transform. It is common to use a vertical coordinate to be a Coordinate Transform Variable. Using a *dummy variable* (with no useful data in it) is
also common. The example here are done with dummy variables.

The CF CoordSysBuilder will add the **_CoordinateTransformType** attribute upon recognizing a standard_name, so adding that is optional if you
are using CF Conventions. CF also requires that you use the vertical coordinate as the Coordinate Transform Variable, so that the transform will be added to
any Coordinate System that uses that vertical coordinate. The CF CoordSysBuilder will thus add the **_CoordinateAxes =
"vertCoordName"** attribute to indicate this.

A Transform is defined by creating a Coordinate Transform Variable (see Example and Reference). The attributes of the Coordinate Transform Variable become the parameters of the transform. A variable is a Coordinate Transform Variable if one (or both) of these is true:

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

Any Variable can be a Coordinate Transform Variable, as it is just a container for attributes, i.e. the data values of the Variable are not used by the
transform. It is common to use a vertical coordinate to be a Coordinate Transform Variable. Using a *dummy variable* (with no useful data in it) is
also common. The example here are done with dummy variables.

The CF CoordSysBuilder will add the **_CoordinateTransformType** attribute upon recognizing a standard_name, so adding that is optional if you
are using CF Conventions. CF also requires that you use the vertical coordinate as the Coordinate Transform Variable, so that the transform will be added to
any Coordinate System that uses that vertical coordinate. The CF CoordSysBuilder will thus add the **_CoordinateAxes =
"vertCoordName"** attribute to indicate this.

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";

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";

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**,

The attribute value must be one of the valid Axis Types, for example:

_CoordinateAxisType = "Lat";

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";

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

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";

This is a way to assign explicit Coordinate System to a set of variables, without having to name each variable. The value of the attribute is a list of dimensions. A data variable that does not have an explicit _CoordinateSystem or CoordinateAxes attribute will be assigned this CoordinateSystem, if it contains exactly the listed dimensions.

<variable name="coordSysVar4D" type="int" shape=""> <attribute name="_CoordinateAxes" value="x y zpos time"/> <attribute name="_CoordinateTransforms" value="zpos"/> <attribute name="_CoordinateSystemFor" value="xpos ypos zpos time"/> </variable>

<variable name="coordSysVar3D" type="int" shape=""> <attribute name="_CoordinateAxes" value="x y time"/> <attribute name="_CoordinateSystemFor" value="xpos ypos time"/> </variable>

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

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.

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

_CoordinateTransformType = "Projection";

Only used for vertical coordinate axes to disambiguate direction * up* or

The attribute value must equal * "up"* or

_CoordinateZisPositive = "down";

May have attributes:

**_CoordinateAxisType****_CoordinateAliasForDimension****_CoordinateZisPositive**

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

- It has any of the
**_CoordinateAxisType**,**_CoordinateAliasForDimension**, or**_CoordinateZisPositive**attributes. - It is a coordinate variable
- 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:

- It has the same name as its dimension.
- It has the
**_CoordinateAliasForDimension**attribute.

May have attributes:

**_CoordinateAxes**(required, must be a complete list of axes, must have at least one axis).**_CoordinateSystemFor**(list of dimensions) will be assigned to any Variable which contains exactly these dimensions.**_CoordinateTransforms**

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

- It has a
**_CoordinateTransforms**attribute. - Its has a
**_CoordinateSystemFor**attribute**.** - It is listed in a
**_CoordinateSystems**attribute from any variable in the file.

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:

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

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:

- If it has a
**_CoordinateSystems**attribute, it is assigned the listed Coordinate Systems, and no further processing is done. - 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. - Otherwise it will have one Coordinate System consisting of the Coordinate Variables that it uses.
- If
**CoordSysBuilder.useMaximalCoordSys**is true (default is true), and all the following conditions are true:- A Data Variable has none or one implicit Coordinate System.
- Its implicit Coordinate System (if it exists) has fewer axes than the rank of the Variable.

*maximal algorithm*.

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

(see * ucar.nc2.constants.AxisType*)

AxisType | description | order |
---|---|---|

RunTime | model run time | 0 |

Ensemble | model ensemble | 1 |

Time | valid time | 2 |

GeoZ | vertical coordinate | 3 |

Height | vertical height, convertible to meters | 3 |

Pressure | vertical pressure, converrtible to hPa | 3 |

GeoY | projection y coordinate | 4 |

Lat | geodesic latitude | 4 |

GeoX | projection x coordinate | 5 |

Lon | geodesic longitude | 5 |

RadialAzimuth | polar azimuth | 6 |

RadialDistance | polar distance | 7 |

RadialElevation | polar elevation | 8 |

This document last updated on Jan 2015