diff --git a/.github/workflows/check_adoc_build.yml b/.github/workflows/check_adoc_build.yml new file mode 100644 index 00000000..c3e1382a --- /dev/null +++ b/.github/workflows/check_adoc_build.yml @@ -0,0 +1,68 @@ +# +# GitHub Actions Workflow for pull request events against the master branch to +# make sure Asciidoctor still builds. If successful, the resulting html and +# pdf files are uploaded as artifacts to make it easier to preview the results +# of a PR. +# +# For more information on the actions used in this workflow, please see: +# https://github.com/actions/checkout +# https://github.com/Analog-inc/asciidoctor-action +# https://github.com/actions/upload-artifact +# +name: Check Asciidoctor Build +on: + pull_request: + branches: [ master ] + +jobs: + # Job to build cf-conventions.html, cf-conventions.pdf + build_conventions: + name: Build cf-conventions html and pdf + runs-on: ubuntu-latest + steps: + # Check out PR + - uses: actions/checkout@v2 + # Create build directory + - run: mkdir conventions_build + # Build cf-conventions.html using the Analog-inc asciidoctor-action + - name: Build cf-conventions.html + uses: Analog-inc/asciidoctor-action@v1.2 + with: + shellcommand: 'asciidoctor --verbose cf-conventions.adoc -D conventions_build' + # Build cf-conventions.pdf using the Analog-inc asciidoctor-action + - name: Build cf-conventions.pdf + uses: Analog-inc/asciidoctor-action@v1.2 + with: + shellcommand: 'asciidoctor-pdf --verbose -d book cf-conventions.adoc -D conventions_build' + # Upload artifact containing cf-conventions.html, cf-conventions.pdf + - name: Upload cf-conventions doc preview + uses: actions/upload-artifact@v1 + with: + name: conventions docs + path: conventions_build/ + + # Job to build conformance.html, conformance.pdf + build_conformance: + name: Build conformance html and pdf + runs-on: ubuntu-latest + steps: + # Checkout PR + - uses: actions/checkout@v2 + # Create build directory + - run: mkdir conformance_build + # Build conformance.html using the Analog-inc asciidoctor-action + - name: Build conformance.html + uses: Analog-inc/asciidoctor-action@v1.2 + with: + shellcommand: 'asciidoctor --verbose conformance.adoc -D conformance_build' + # Build conformance.pdf using the Analog-inc asciidoctor-action + - name: Build conformance.pdf + uses: Analog-inc/asciidoctor-action@v1.2 + with: + shellcommand: 'asciidoctor-pdf --verbose -d book conformance.adoc -D conformance_build' + # Upload artifact containing conformance.html, conformance.pdf + - name: Upload conformance doc preview + uses: actions/upload-artifact@v1 + with: + name: conformance docs + path: conformance_build/ diff --git a/README.md b/README.md index a9d9f22d..11023bda 100644 --- a/README.md +++ b/README.md @@ -19,3 +19,13 @@ To convert the AsciiDoc files into the resulting HTML file: 4. Build the HTML: `asciidoctor cf-conventions.adoc` See the [GitHub help](https://help.github.com/) pages and plethora of other git/GitHub guides for more details on how to work with repos, forks, pull requests, etc. + +### Latest Spec Build + +Whenever a [pull request](https://github.com/cf-convention/cf-conventions/pulls) is merged, a [travis-ci build](https://travis-ci.org/github/cf-convention/cf-conventions) generates the latest specification draft and adds it to the [gh-pages branch here](https://github.com/cf-convention/cf-conventions/tree/gh-pages). The gh-pages branch is deployed to github pages at the following documents: +- http://cfconventions.org/cf-conventions/cf-conventions.html +- http://cfconventions.org/cf-conventions/cf-conventions.pdf +- http://cfconventions.org/cf-conventions/conformance.html +- http://cfconventions.org/cf-conventions/conformance.pdf + +These documents are linked in the cf-conventions web site. [source here](https://github.com/cf-convention/cf-convention.github.io) which is published to: http://cfconventions.org/. The latest spec documents are linked from those web pages here: http://cfconventions.org/latest.html. \ No newline at end of file diff --git a/appf.adoc b/appf.adoc index cd5f3014..3d5dc9e6 100644 --- a/appf.adoc +++ b/appf.adoc @@ -27,12 +27,12 @@ grid_mapping_name = albers_conical_equal_area ---- -__Map parameters:__:: +__Map parameters:__:: * **`standard_parallel`** - There may be 1 or 2 values. * **`longitude_of_central_meridian`** * **`latitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -46,14 +46,14 @@ link:$$http://geotiff.maptools.org/proj_list/albers_equal_area_conic.html$$[http ---- grid_mapping_name = azimuthal_equidistant - + ---- __Map parameters:__:: * **`longitude_of_projection_origin`** * **`latitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -67,29 +67,43 @@ link:$$http://proj4.org/projections/aeqd.html$$[http://proj4.org/projections/aeq ---- grid_mapping_name = geostationary - + ---- __Map parameters:__:: * **`latitude_of_projection_origin`** * **`longitude_of_projection_origin`** * **`perspective_point_height`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) * **`sweep_angle_axis`** * **`fixed_angle_axis`** -__Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. In the case of this projection, the projection coordinates in this projection are directly related to the scanning angle of the satellite instrument, and their units are radians. +__Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_angular_coordinate`** and **`projection_y_angular_coordinate`**, respectively. +CF specified the standard names **`projection_x_coordinate`** and **`projection_y_coordinate`** for these coordinates prior to version 1.9, but that use is deprecated. +In the case of this projection, the projection coordinates in this projection are directly related to the scanning angle of the satellite instrument. -__Notes:__:: The algorithm for computing the mapping may be found at link:$$http://www.cgms-info.org/documents/pdf_cgms_03.pdf$$[http://www.cgms-info.org/documents/pdf_cgms_03.pdf]. This document assumes the point of observation is directly over the equator, and that the **`sweep_angle_axis`** is y. +__Notes:__:: The algorithm for computing the mapping may be found at link:$$http://www.cgms-info.org/documents/pdf_cgms_03.pdf$$[http://www.cgms-info.org/documents/pdf_cgms_03.pdf]. +This document assumes the point of observation is directly over the equator, and that the **`sweep_angle_axis`** is y. ++ Notes on using the PROJ.4 software packages for computing the mapping may be found at link:$$http://proj4.org/$$[http://proj4.org/] and link:$$https://trac.osgeo.org/geotiff/$$[https://trac.osgeo.org/geotiff/] . -The **`perspective_point_height`** is the distance to the surface of the ellipsoid. Adding the earth major axis gives the distance from the centre of the earth. ++ +The **`perspective_point_height`** is the distance to the surface of the ellipsoid. +Adding the earth major axis gives the distance from the centre of the earth. -The **`sweep_angle_axis`** attribute indicates which axis the instrument sweeps. The value = "y" corresponds to the spin-stabilized Meteosat satellites, the value = "x" to the GOES-R satellite. ++ +The **`sweep_angle_axis`** attribute indicates which axis the instrument sweeps. +The value = "y" corresponds to the spin-stabilized Meteosat satellites, the value = "x" to the GOES-R satellite. -The **`fixed_angle_axis`** attribute indicates which axis the instrument is fixed. The values are opposite to **`sweep_angle_axis`**. Only one of those two attributes is mandatory. ++ +The **`fixed_angle_axis`** attribute indicates which axis the instrument is fixed. +The values are opposite to **`sweep_angle_axis`**. Only one of those two attributes is mandatory. + ++ +The use of `projection_x_coordinate` and `projection_y_coordinate` was deprecated in version 1.9 of the CF Conventions. +The initial definition of this projection used these standard names to identify the projection coordinates even though their canonical units (meters) do not match those required for this projection (radians). [[lambert-azimuthal-equal-area]] @@ -98,14 +112,14 @@ The **`fixed_angle_axis`** attribute indicates which axis the instrument is fixe ---- grid_mapping_name = lambert_azimuthal_equal_area - + ---- __Map parameters:__:: * **`longitude_of_projection_origin`** * **`latitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -120,15 +134,15 @@ link:$$http://geotiff.maptools.org/proj_list/lambert_azimuthal_equal_area.html$$ ---- grid_mapping_name = lambert_conformal_conic - + ---- __Map parameters:__:: * **`standard_parallel`** - There may be 1 or 2 values. * **`longitude_of_central_meridian`** * **`latitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -144,14 +158,14 @@ link:$$http://geotiff.maptools.org/proj_list/lambert_conic_conformal_2sp.html$$[ ---- grid_mapping_name = lambert_cylindrical_equal_area - + ---- __Map parameters:__:: * **`longitude_of_central_meridian`** * Either **`standard_parallel`** or **`scale_factor_at_projection_origin`** (deprecated) -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -165,16 +179,14 @@ link:$$http://geotiff.maptools.org/proj_list/cylindrical_equal_area.html$$[http: ---- grid_mapping_name = latitude_longitude - + ---- This grid mapping defines the canonical 2D geographical coordinate system based upon latitude and longitude coordinates on a spherical Earth. It is included so that the figure of the Earth can be described. __Map parameters:__:: None. -__Map coordinates:__:: The rectangular coordinates are longitude and latitude -identified by the usual conventions -(<> and <>). +__Map coordinates:__:: The rectangular coordinates are longitude and latitude identified by the usual conventions (<> and <>). === Mercator @@ -182,14 +194,14 @@ identified by the usual conventions ---- grid_mapping_name = mercator - + ---- __Map parameters:__:: * **`longitude_of_projection_origin`** * Either **`standard_parallel`** (EPSG 9805) or **`scale_factor_at_projection_origin`** (EPSG 9804) -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -201,7 +213,7 @@ link:$$http://geotiff.maptools.org/proj_list/mercator_1sp.html$$[http://geotiff. or link:$$http://geotiff.maptools.org/proj_list/mercator_2sp.html$$[http://geotiff.maptools.org/proj_list/mercator_2sp.html] ("Mercator (2SP)" or EPSG 9805). - + + More information on formulas available in <>. @@ -211,7 +223,7 @@ More information on formulas available in <>. ---- grid_mapping_name = oblique_mercator - + ---- __Map parameters:__:: @@ -219,8 +231,8 @@ __Map parameters:__:: * **`latitude_of_projection_origin`** * **`longitude_of_projection_origin`** * **`scale_factor_at_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -236,14 +248,14 @@ The Rotated Mercator projection is an Oblique Mercator projection with azimuth = ---- grid_mapping_name = orthographic - + ---- __Map parameters:__:: * **`longitude_of_projection_origin`** * **`latitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -252,7 +264,7 @@ link:$$http://proj4.org/projections/ortho.html$$[http://proj4.org/projections/or and link:$$http://geotiff.maptools.org/proj_list/orthographic.html$$[http://geotiff.maptools.org/proj_list/orthographic.html] ("Orthographic" or EPSG 9840). - + + More information on formulas available in <>. @@ -264,15 +276,15 @@ More information on formulas available in <>. ---- grid_mapping_name = polar_stereographic - + ---- __Map parameters:__:: * **`straight_vertical_longitude_from_pole`** * **`latitude_of_projection_origin`** - Either +90. or -90. * Either **`standard_parallel`** (EPSG 9829) or **`scale_factor_at_projection_origin`** (EPSG 9810) -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -288,17 +300,17 @@ As PROJ.4 requires the standard parallel, [Snyder] formula 21-7 can be used to c ---- grid_mapping_name = rotated_latitude_longitude - + ---- __Map parameters:__:: * **`grid_north_pole_latitude`** * **`grid_north_pole_longitude`** -* **`north_pole_grid_longitude`** - This parameter is option (default is 0). +* **`north_pole_grid_longitude`** - This parameter is optional (default is 0). __Map coordinates:__:: The rotated latitude and longitude coordinates are identified by the **`standard_name`** attribute values **`grid_latitude`** and **`grid_longitude`** respectively. -__Notes:__:: +__Notes:__:: {nbsp} @@ -307,13 +319,13 @@ __Notes:__:: ---- grid_mapping_name = sinusoidal - + ---- __Map parameters:__:: * **`longitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -329,15 +341,15 @@ Detailed formulas can be found in <>, pages 243-248. ---- grid_mapping_name = stereographic - + ---- __Map parameters:__:: * **`longitude_of_projection_origin`** * **`latitude_of_projection_origin`** * **`scale_factor_at_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -353,15 +365,15 @@ See the section "Polar stereographic" for the special case when the projection o ---- grid_mapping_name = transverse_mercator - + ---- __Map parameters:__:: * **`scale_factor_at_central_meridian`** * **`longitude_of_central_meridian`** * **`latitude_of_projection_origin`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute values **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. @@ -377,21 +389,21 @@ link:$$http://geotiff.maptools.org/proj_list/transverse_mercator.html$$[http://g ---- grid_mapping_name = vertical_perspective - + ---- __Map parameters:__:: * **`latitude_of_projection_origin`** * **`longitude_of_projection_origin`** * **`perspective_point_height`** -* **`false_easting`** -* **`false_northing`** +* **`false_easting`** - This parameter is optional (default is 0) +* **`false_northing`** - This parameter is optional (default is 0) __Map coordinates:__:: The x (abscissa) and y (ordinate) rectangular coordinates are identified by the **`standard_name`** attribute value **`projection_x_coordinate`** and **`projection_y_coordinate`** respectively. - + __Notes:__:: A general description of vertical perspective projection is given in <>, pages 169-181. @@ -400,8 +412,7 @@ The corresponding projection in PROJ.4 is nsper. This should not be confused with the PROJ.4 geos projection. -In the following table the "Type" values are **S** for string and **N** -for numeric. +In the following table the "Type" values are **S** for string and **N** for numeric. [[table-grid-mapping-attributes]] .Grid Mapping Attributes @@ -433,7 +444,8 @@ to a reference direction. | Applied to all abscissa values in the rectangular coordinates for a map projection in order to eliminate negative numbers. Expressed in the unit of the coordinate variable identified by the - standard name **`projection_x_coordinate`**. + standard name **`projection_x_coordinate`**. + If **`false_easting`** is not provided it is assumed to be 0. The formula to convert from the coordinate value as written in the **`projection_x_coordinate`** (xf) to a value (x0) used in a transformation without **`false_easting`**, i.e. **`false_easting`**= 0, is: x0 = xf -**`false_easting`** @@ -444,7 +456,8 @@ to a reference direction. | Applied to all ordinate values in the rectangular coordinates for a map projection in order to eliminate negative numbers. Expressed in the unit of the coordinate variable identified by the - standard name **`projection_y_coordinate`**. + standard name **`projection_y_coordinate`**. + If **`false_northing`** is not provided it is assumed to be 0. The formula to convert from the coordinate value as written in the **`projection_y_coordinate`** (yf) to a value (y0) used in a transformation without **`false_northing`**, i.e. **`false_northing`**= 0, is: y0 = yf -**`false_northing`** diff --git a/apph.adoc b/apph.adoc index dafdd83d..1fc0026d 100644 --- a/apph.adoc +++ b/apph.adoc @@ -357,7 +357,13 @@ where    rowStart(i) = rowStart(i-1) + row_size(i-1) if i > 0 ---- -The variable, **`row_size`** , is the count variable containing the length of each time series feature.   It is identified by having an attribute with name `**sample_dimension**` whose value is name of the sample dimension ( **`obs`** in this example). The sample dimension could optionally be the netCDF unlimited dimension. The variable bearing the `**sample_dimension**` attribute must have the instance dimension ( **`station`** in this example) as its single dimension, and must be of type integer.   This variable implicitly partitions into individual instances all variables that have the sample dimension. The auxiliary coordinate variables **`lat`** , **`lon`** , **`alt`** and **`station_name`** are station variables. +The variable, **`row_size`** , is the count variable containing the length of each time series feature. +It is identified by having an attribute with name `**sample_dimension**` whose value is name of the sample dimension ( **`obs`** in this example). +The sample dimension could optionally be the netCDF unlimited dimension. +The variable bearing the `**sample_dimension**` attribute must have the instance dimension ( **`station`** in this example) +as its single dimension, and must have an integer type. +This variable implicitly partitions into individual instances all variables that have the sample dimension. +The auxiliary coordinate variables **`lat`** , **`lon`** , **`alt`** and **`station_name`** are station variables. ==== @@ -418,7 +424,12 @@ When time series with different lengths are written incrementally, the indexed r ---- The humidity(o) and temp(o) data are associated with the coordinate values time(o), lat(i), lon(i), and alt(i), where i = stationIndex(o) is a zero-based index indicating which time series. Thus, time(0), humidity(0) and temp(0) belong to the element of the **`station`** dimension that is indicated by **`stationIndex(0)`** ; time(1), humidity(1) and temp(1) belong to element **`stationIndex(1)`** of the **`station`** dimension, etc. -The variable, **`stationIndex`** , is identified as the index variable by having an attribute with name of `**instance_dimension**` whose value is the instance dimension ( **`station`** in this example).  The variable bearing the `**instance_dimension**` attribute must have the sample dimension ( **`obs`** in this example) as its single dimension, and must be type integer. This variable implicitly assigns the station to each value of any variable having the sample dimension. The sample dimension need not be the netCDF unlimited dimension, though it commonly is. +The variable, **`stationIndex`** , is identified as the index variable by having an attribute with name of `**instance_dimension**` whose value is the instance dimension ( **`station`** in this example). +The variable bearing the `**instance_dimension**` attribute +must have the sample dimension ( **`obs`** in this example) as its single dimension, +and must have an integer type. +This variable implicitly assigns the station to each value of any variable having the sample dimension. +The sample dimension need not be the netCDF unlimited dimension, though it commonly is. ==== @@ -617,7 +628,9 @@ When the number of vertical levels for each profile varies, and one can control ---- The pressure(o), temperature(o), and humidity(o) data is associated with the coordinate values time(i), z(o), lat(i), and lon(i), where i indicates which profile. All elements for one profile are contiguous along the sample dimension. The sample dimension (obs) may be the unlimited dimension or not. All variables that have the instance dimension (profile) as their single dimension are considered to be information about the profiles. -The count variable (row_size) contains the number of elements for each profile, and is identified by having an attribute with name "sample_dimension" whose value is the sample dimension being counted. It must have the profile dimension as its single dimension, and must be type integer. The elements are associated with the profile using the same algorithm as in H.2.4. +The count variable (row_size) contains the number of elements for each profile, and is identified by having an attribute with name "sample_dimension" whose value is the sample dimension being counted. +It must have the profile dimension as its single dimension, and must have an integer type. +The elements are associated with the profile using the same algorithm as in H.2.4. ==== @@ -682,7 +695,9 @@ When the number of vertical levels for each profile varies, and one cannot write attributes:    :featureType = "profile"; ---- -The pressure(o), temperature(o), and humidity(o) data are associated with the coordinate values time(i), z(o), lat(i), and lon(i), where i indicates which profile. The sample dimension (obs) may be the unlimited dimension or not. The profile index variable (parentIndex) is identified by having an attribute with name of "instance_dimension" whose value is the profile dimension name. It must have the sample dimension as its single dimension, and must be type integer. Each value in the profile index variable is the zero-based profile index that the element belongs to. The elements are associated with the profiles using the same algorithm as in H.2.5. +The pressure(o), temperature(o), and humidity(o) data are associated with the coordinate values time(i), z(o), lat(i), and lon(i), where i indicates which profile. The sample dimension (obs) may be the unlimited dimension or not. The profile index variable (parentIndex) is identified by having an attribute with name of "instance_dimension" whose value is the profile dimension name. +It must have the sample dimension as its single dimension, and must have an integer type. +Each value in the profile index variable is the zero-based profile index that the element belongs to. The elements are associated with the profiles using the same algorithm as in H.2.5. ==== @@ -868,7 +883,9 @@ When the number of elements for each trajectory varies, and one can control the ---- The O3(o) and NO3(o) data are associated with the coordinate values time(o), lat(o), lon(o), and alt(o). All elements for one trajectory are contiguous along the sample dimension. The sample dimension (obs) may be the unlimited dimension or not. All variables that have the instance dimension (trajectory) as their single dimension are considered to be information about that trajectory. -The count variable (row_size) contains the number of elements for each trajectory, and is identified by having an attribute with name "sample_dimension" whose value is the sample dimension being counted. It must have the trajectory dimension as its single dimension, and must be type integer. The elements are associated with the trajectories using the same algorithm as in H.2.4. +The count variable (row_size) contains the number of elements for each trajectory, and is identified by having an attribute with name "sample_dimension" whose value is the sample dimension being counted. +It must have the trajectory dimension as its single dimension, and must have an integer type. +The elements are associated with the trajectories using the same algorithm as in H.2.4. ==== @@ -929,7 +946,9 @@ When the number of elements at each trajectory vary, and the elements cannot be ---- The O3(o) and NO3(o) data are associated with the coordinate values time(o), lat(o), lon(o), and alt(o). All elements for one trajectory will have the same trajectory index value. The sample dimension (obs) may be the unlimited dimension or not. -The index variable (trajectory_index) is identified by having an attribute with name of "instance_dimension" whose value is the trajectory dimension name. It must have the sample dimension as its single dimension, and must be type integer. Each value in the trajectory_index variable is the zero-based trajectory index that the element belongs to. The elements are associated with the trajectories using the same algorithm as in H.2.5. +The index variable (trajectory_index) is identified by having an attribute with name of "instance_dimension" whose value is the trajectory dimension name. +It must have the sample dimension as its single dimension, and must have an integer type. +Each value in the trajectory_index variable is the zero-based trajectory index that the element belongs to. The elements are associated with the trajectories using the same algorithm as in H.2.5. ==== @@ -1196,9 +1215,13 @@ When the number of profiles and levels for each station varies, one can use a ra ---- The pressure(o), temperature(o), and humidity(o) data for element o of profile p at station i are associated with the coordinate values time(p), z(o), lat(i), and lon(i). -The index variable (station_index) is identified by having an attribute with name of instance_dimension whose value is the instance dimension name (station in this example). The index variable must have the profile dimension as its sole dimension, and must be type integer. Each value in the index variable is the zero-based station index that the profile belongs to i.e. profile p belongs to station i=station_index(p), as in section H.2.5. +The index variable (station_index) is identified by having an attribute with name of instance_dimension whose value is the instance dimension name (station in this example). +The index variable must have the profile dimension as its sole dimension, and must have an integer type. +Each value in the index variable is the zero-based station index that the profile belongs to i.e. profile p belongs to station i=station_index(p), as in section H.2.5. -The count variable (row_size) contains the number of elements for each profile, which must be written contiguously. The count variable is identified by having an attribute with name sample_dimension whose value is the sample dimension (obs in this example) being counted. It must have the profile dimension as its sole dimension, and must be type integer. The number of elements in profile p is recorded in row_size(p), as in section H.2.4. The sample dimension need not be the netCDF unlimited dimension,  though it commonly is. +The count variable (row_size) contains the number of elements for each profile, which must be written contiguously. The count variable is identified by having an attribute with name sample_dimension whose value is the sample dimension (obs in this example) being counted. +It must have the profile dimension as its sole dimension, and must have an integer type. +The number of elements in profile p is recorded in row_size(p), as in section H.2.4. The sample dimension need not be the netCDF unlimited dimension,  though it commonly is. ==== @@ -1408,7 +1431,11 @@ When the number of profiles and levels for each trajectory varies, one can use a ---- The pressure(o), temperature(o), and humidity(o) data for element o of profile p along trajectory i are associated with the coordinate values time(p), z(o), lat(p), and lon(p). -The index variable (trajectory_index) is identified by having an attribute with name of instance_dimension whose value is the instance dimension name (trajectory in this example). The index variable must have the profile dimension as its sole dimension, and must be type integer. Each value in the index variable is the zero-based trajectory index that the profile belongs to i.e. profile p belongs to trajectory i=trajectory_index(p), as in section H.2.5. +The index variable (trajectory_index) is identified by having an attribute with name of instance_dimension whose value is the instance dimension name (trajectory in this example). +The index variable must have the profile dimension as its sole dimension, and must have an integer type. +Each value in the index variable is the zero-based trajectory index that the profile belongs to i.e. profile p belongs to trajectory i=trajectory_index(p), as in section H.2.5. -The count variable (row_size) contains the number of elements for each profile, which must be written contiguously. The count variable is identified by having an attribute with name sample_dimension whose value is the sample dimension (obs in this example) being counted. It must have the profile dimension as its sole dimension, and must be type integer. The number of elements in profile p is recorded in row_size(p), as in section H.2.4. The sample dimension need not be the netCDF unlimited dimension,  though it commonly is. +The count variable (row_size) contains the number of elements for each profile, which must be written contiguously. The count variable is identified by having an attribute with name sample_dimension whose value is the sample dimension (obs in this example) being counted. +It must have the profile dimension as its sole dimension, and must have an integer type. +The number of elements in profile p is recorded in row_size(p), as in section H.2.4. The sample dimension need not be the netCDF unlimited dimension,  though it commonly is. ==== diff --git a/bibliography.adoc b/bibliography.adoc index 9351302e..80c5e48d 100644 --- a/bibliography.adoc +++ b/bibliography.adoc @@ -3,7 +3,7 @@ [bibliography] === References -- [[[COARDS]]] link:$$http://www.ferret.noaa.gov/noaa_coop/coop_cdf_profile.html$$[ Conventions for the standardization of NetCDF Files ] . +- [[[COARDS]]] link:$$https://ferret.pmel.noaa.gov/Ferret/documentation/coards-netcdf-conventions$$[ Conventions for the standardization of NetCDF Files ] . Sponsored by the "Cooperative Ocean/Atmosphere Research Data Service," a NOAA/university diff --git a/cf-conventions.adoc b/cf-conventions.adoc index 18f066c2..08f8e80c 100644 --- a/cf-conventions.adoc +++ b/cf-conventions.adoc @@ -1,6 +1,6 @@ = NetCDF Climate and Forecast (CF) Metadata Conventions Brian{nbsp}Eaton; Jonathan{nbsp}Gregory; Bob{nbsp}Drach; Karl{nbsp}Taylor; Steve{nbsp}Hankin; Jon{nbsp}Blower; John{nbsp}Caron; Rich{nbsp}Signell; Phil{nbsp}Bentley; Greg{nbsp}Rappa; Heinke{nbsp}Höck; Alison{nbsp}Pamment; Martin{nbsp}Juckes; Martin{nbsp}Raspaud; Randy{nbsp}Horne; Timothy{nbsp}Whiteaker; David{nbsp}Blodgett; Charlie{nbsp}Zender; Daniel{nbsp}Lee -Version 1.8 (draft) +Version 1.9 (draft) :doctype: book :pdf-folio-placement: physical :sectanchors: diff --git a/ch02.adoc b/ch02.adoc index 630aec9b..f99f3699 100644 --- a/ch02.adoc +++ b/ch02.adoc @@ -13,16 +13,21 @@ NetCDF files should have the file name extension "**`.nc`**". === Data Types -The netCDF data types **`string`**, **`char`**, **`byte`**, **`short`**, -**`int`**, **`float`** or **`real`**, and **`double`** are all acceptable. +The netCDF data types **`string`**, **`char`**, **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**, +**`int`**, **`unsigned int`**, **`int64`**, **`unsigned int64`**, +**`float`** or **`real`**, and **`double`** are all acceptable. The **`string`** type is only available in files using the netCDF version 4 (netCDF-4) format. The **`char`** and **`string`** types are not intended for numeric data. -One byte numeric data should be stored using the **`byte`** data type. -All integer types are treated by the netCDF interface as signed. -It is possible to treat the **`byte`** type as unsigned by using the NUG +One byte numeric data should be stored using the **`byte`** or **`unsigned byte`** data types. +It is possible to treat the **`byte`** and **`short`** types as unsigned by using the NUG convention of indicating the unsigned range using the **`valid_min`**, **`valid_max`**, or **`valid_range`** attributes. +In many situations, any integer type may be used. +When the phrases "an integer type" or "any integer type" are used in this document, +it should be understood to mean **`byte`**, **`unsigned byte`**, +**`short`**, **`unsigned short`**, +**`int`**, **`unsigned int`**, **`int64`**, or **`unsigned int64`**. Strings in variables may be represented one of two ways - as atomic strings or as character arrays. diff --git a/ch03.adoc b/ch03.adoc index f814b1b9..dd8acd0c 100644 --- a/ch03.adoc +++ b/ch03.adoc @@ -1,5 +1,5 @@ -== Description of the Data +== Description of the Data The attributes described in this section are used to provide a description of the content and the units of measurement for each variable. We continue to support the use of the **`units`** and **`long_name`** attributes as defined in COARDS. We extend COARDS by adding the optional **`standard_name`** attribute which is used to provide unique identifiers for variables. This is important for data exchange since one cannot necessarily identify a particular variable based on the name assigned to it by the institution that provided the data. @@ -19,7 +19,7 @@ The units `level`, `layer`, and `sigma_level` are allowed for dimensionless vert The Udunits syntax that allows scale factors and offsets to be applied to a unit is not supported by this standard. The application of any scale factors or offsets to data should be indicated by the **`scale_factor`** and **`add_offset`** attributes. Use of these attributes for data packing, which is their most important application, is discussed in detail in <>. -Udunits recognizes the following prefixes and their abbreviations. +Udunits recognizes the following prefixes and their abbreviations. [[table-supported-units]] .Supported Units [options="header",caption="Table 3.1. "] @@ -59,7 +59,7 @@ standard name:: The name used to identify the physical quantity. A standard name canonical units:: Representative units of the physical quantity. Unless it is dimensionless, a variable with a **`standard_name`** attribute must have units which are physically equivalent (not necessarily identical) to the canonical units, possibly modified by an operation specified by the standard name modifier (see below and <>) or by the **`cell_methods`** attribute (see <> and <>) or both. description:: The description is meant to clarify the qualifiers of the fundamental quantities such as which surface a quantity is defined on or what the flux sign conventions are. We don't attempt to provide precise definitions of fundumental physical quantities (e.g., temperature) which may be found in the literature. -The description may define rules on the variable type, attributes and coordinates which must be complied with by any variable carrying that standard name (such as in example 3.4). +The description may define rules on the variable type, attributes and coordinates which must be complied with by any variable carrying that standard name (such as in example 3.4). When appropriate, the table entry also contains the corresponding GRIB parameter code(s) (from ECMWF and NCEP) and AMIP identifiers. @@ -107,7 +107,7 @@ When one data variable provides metadata about the individual values of another [[instrument-data-ex]] [caption="Example 3.2. "] -.Instrument data +.Ancillary instrument data ==== ---- @@ -122,13 +122,60 @@ When one data variable provides metadata about the individual values of another float q_detection_limit(time) q_detection_limit:standard_name = "specific_humidity detection_minimum" ; q_detection_limit:units = "g/g" ; - ----- +---- ==== +Alternatively, **`ancillary_variables`** may be used as status flags indicating the operational status of an instrument producing the data or as quality flags indicating the results of a quality control test, or some other quantitative quality assessment, performed against the measurements contained in the source variable. In these cases, the flag variable will include a standard name that differs from that of the source variable and indicates the specific type of flag the variable represents. + +The standard names table includes many names intended to be used in this situation, both general names meant to be used to flexibly represent any type of status or quality assessment, as well as names for specific quality control tests commonly applied to geophysical phenomena timeseries data. Several examples are listed below: +<<<<<<< HEAD + +.Sample flag variable standard names: +- **`status_flag`** and **`quality_flag`**: general flag categories for instrument status or quality assessment +- **`climatology_test_quality_flag`**, **`flat_line_test_quality_flag`**, **`gap_test_quality_flag`**, **`spike_test_quality_flag`**: subset of standard name flags for indicating the results of commonly-used geophysical timeseries data quality control tests +- **`aggregate_quality_flag`**: flag indicating an aggregate summary of multiple individual quality control test flags that use the same flagging scheme (i.e. a master quality flag for a particular variable) + +The following example illustrates the use of three of these flags to represent two independent quality control tests and an aggregate flag that combines the results of the two tests (assuming each test uses a common encoding scheme according to techniques defined in <> and therefore can be aggregated). + +======= + +.Sample flag variable standard names: +- **`status_flag`** and **`quality_flag`**: general flag categories for instrument status or quality assessment +- **`climatology_test_quality_flag`**, **`flat_line_test_quality_flag`**, **`gap_test_quality_flag`**, **`spike_test_quality_flag`**: subset of standard name flags for indicating the results of commonly-used geophysical timeseries data quality control tests +- **`aggregate_quality_flag`**: flag indicating an aggregate summary of multiple individual quality control test flags that use the same flagging scheme (i.e. a master quality flag for a particular variable) + +The following example illustrates the use of three of these flags to represent two independent quality control tests and an aggregate flag that combines the results of the two tests (assuming each test uses a common encoding scheme according to techniques defined in <> and therefore can be aggregated). +>>>>>>> origin/chap_34_update +[[quality-flag-ex]] +[caption="Example 3.2.1 "] +.Ancillary quality flag data +==== + +---- +float salinity(time, z); + salinity:units = "1"; + salinity:long_name = "Salinity"; + salinity:standard_name = "sea_water_practical_salinity"; + salinity:ancillary_variables = "salinity_qc_generic salinity_qc_flat_line_test salinity_qc_agg"; + + int salinity_qc_generic(time, z); + salinity_qc_generic:long_name = "Salinity Generic QC Process Flag"; + salinity_qc_generic:standard_name = "quality_flag"; + + int salinity_qc_flat_line_test(time, z); + salinity_qc_flat_line_test:long_name = "Salinity Flat Line Test Flag"; + salinity_qc_flat_line_test:standard_name = "flat_line_test_quality_flag"; + + int salinity_qc_agg(time, z); + salinity_qc_agg:long_name = "Salinity Aggregate Flag"; + salinity_qc_agg:standard_name = "aggregate_quality_flag"; +---- +Note that the ancillary variables in this example are simplified to exclude **`flag_values`**, **`flag_masks`** and +**`flag_meanings`** attributes described in <> that they would ordinarily require +==== [[flags, Section 3.5, "Flags"]] @@ -165,30 +212,25 @@ enumerated status code. current_speed_qc:_FillValue = -128b ; current_speed_qc:valid_range = 0b, 2b ; current_speed_qc:flag_values = 0b, 1b, 2b ; - current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional + current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional outside_valid_range" ; ---- -Note that the data variable containing current speed has an ancillary_variables +Note that the data variable containing current speed has an ancillary_variables attribute with a value containing current_speed_qc. ==== -The **`flag_masks`** and **`flag_meanings`** attributes describe a -number of independent Boolean conditions using bit field notation by -setting unique bits in each **`flag_masks`** value. **`The -flag_masks`** attribute is the same type as the variable to which it is -attached, and contains a list of values matching unique bit fields. The -**`flag_meanings`** attribute is defined as above, one for each -**`flag_masks`** value. A flagged condition is identified by performing -a bitwise AND of the variable value and each **`flag_masks`** value; a -non-zero result indicates a **`true`** condition. Thus, any or all of -the flagged conditions may be **`true`**, depending on the variable bit -settings. The following example illustrates the use of **`flag_masks`** -to express six sensor status conditions. +<<<<<<< HEAD +The flag_masks and flag_meanings attributes describe a number of independent Boolean conditions using bit field notation by setting unique bits in each flag_masks value. The flag_masks attribute is the same type as the variable to which it is attached, and contains a list of values matching unique bit fields. The flag_meanings attribute is defined as above, one for each flag_masks value. A flagged condition is identified by performing a bitwise AND of the variable value and each flag_masks value; a non-zero result indicates a true condition. Thus, any or all of the flagged conditions may be true, depending on the variable bit settings. The following example illustrates the use of flag_masks to express six sensor status conditions. + +======= + +A variable with standard name of `region`, `area_type` or any other standard name which requires string-valued values from a defined list may use flags together with `flag_values` and `flag_meanings` attributes to record the translation to the string values. Example 3.4 illustrates this using integer flag values for a variable with standard name `region` and `flag_values` selected from the link:$$http://cfconventions.org/Data/cf-standard-names/docs/standardized-region-names.html$$[standardized region names] (see section 6.1.1). -[[region-variable-flag-masks-ex]] + +[[region-variable-flag-values-ex]] [caption="Example 3.4. "] .A region variable, using **`flag_values`** ==== @@ -204,16 +246,29 @@ data: ==== -A variable with standard name of `region`, `area_type` or any other standard name which requires string-valued values from a defined list may use flags together with `flag_values` and `flag_meanings` attributes to record the translation to the string values. Example 3.4 illustrates this using integer flag values for a variable with standard name `region` and `flag_values` selected from the link:$$http://cfconventions.org/Data/cf-standard-names/docs/standardized-region-names.html$$[standardized region names] (see section 6.1.1). +The **`flag_masks`** and **`flag_meanings`** attributes describe a +number of independent Boolean conditions using bit field notation by +setting unique bits in each **`flag_masks`** value. **`The +flag_masks`** attribute is the same type as the variable to which it is +attached, and contains a list of values matching unique bit fields. The +**`flag_meanings`** attribute is defined as above, one for each +**`flag_masks`** value. A flagged condition is identified by performing +a bitwise AND of the variable value and each **`flag_masks`** value; a +non-zero result indicates a **`true`** condition. Thus, any or all of +the flagged conditions may be **`true`**, depending on the variable bit +settings. The following example illustrates the use of **`flag_masks`** +to express six sensor status conditions. +>>>>>>> origin/chap_34_update [[flag-variable-flag-masks-ex]] -[caption="Example 3.5. "] +[caption="Example 3.4. "] .A flag variable, using **`flag_masks`** ==== ---- byte sensor_status_qc(time, depth, lat, lon) ; sensor_status_qc:long_name = "Sensor Status" ; + sensor_status_qc:standard_name = "status_flag" ; sensor_status_qc:_FillValue = 0b ; sensor_status_qc:valid_range = 1b, 63b ; sensor_status_qc:flag_masks = 1b, 2b, 4b, 8b, 16b, 32b ; @@ -223,6 +278,23 @@ A variable with standard name of `region`, `area_type` or any other standard nam maintenance_required" ; ---- +==== + +A variable with standard name of `region`, `area_type` or any other standard name which requires string-valued values from a defined list may use flags together with `flag_values` and `flag_meanings` attributes to record the translation to the string values. Example 3.5 illustrates this using integer flag values for a variable with standard name `region` and `flag_values` selected from the link:$$http://cfconventions.org/Data/cf-standard-names/docs/standardized-region-names.html$$[standardized region names] (see section 6.1.1). + +[[region-variable-flag-values-ex]] +[caption="Example 3.5. "] +.A region variable, using **`flag_values`** +==== + +---- +int basin(lat, lon); + standard_name: region; + flag_values: 1, 2, 3; + flag_meanings:"atlantic_arctic_ocean indo_pacific_ocean global_ocean"; +data: + basin: 1, 1, 1, 1, 2, ..... ; +---- ==== @@ -250,6 +322,7 @@ conditions and one enumerated status code. ---- byte sensor_status_qc(time, depth, lat, lon) ; sensor_status_qc:long_name = "Sensor Status" ; + sensor_status_qc:standard_name = "status_flag" ; sensor_status_qc:_FillValue = 0b ; sensor_status_qc:valid_range = 1b, 15b ; sensor_status_qc:flag_masks = 1b, 2b, 12b, 12b, 12b ; @@ -284,7 +357,7 @@ The remaining bits (Bit 2 and Bit 3) are decoded as follows: .Flag Variable Bit 2 and Bit 3 (from Example) [options="header",caption="Table 3.3. "] |=============== -| Bit 3 | Bit 2 | Mode +| Bit 3 | Bit 2 | Mode | 0 | 1 | offline_mode | 1 | 0 | calibration_mode | 1 | 1 | maintenance_mode @@ -300,5 +373,3 @@ with the variable. When a result is equal to the corresponding **`flag_values`** element, that condition is **`true`**. The repeated **`flag_masks`** enable a simple mechanism for clients to detect all possible conditions. - - diff --git a/ch05.adoc b/ch05.adoc index 5ebbe4c1..60d13ff8 100644 --- a/ch05.adoc +++ b/ch05.adoc @@ -207,11 +207,15 @@ The grid mapping variables are associated with the data and coordinate variables **`grid_mapping`** attribute. This attribute is attached to data variables so that variables with different mappings may be present in a single file. The attribute takes a string value with two possible formats. In the first format, it is a single word, which names a grid mapping variable. In -the second format, it is a blank-separated list of words "grid_mapping_variable: coordinate_variable -[coordinate_variable ...] [grid_mapping_variable: ...]", which identifies one or more grid mapping -variables, and with each grid mapping associates one or more coordinate_variables, i.e. coordinate +the second format, it is a blank-separated list of words +": [ ...] [: ...]" +, which identifies one or more grid mapping variables, and with each grid mapping associates one or more coordinatesVariables, i.e. coordinate variables or auxiliary coordinate variables. +Where an extended ": []" entity is defined, then the order of the references within the definition provides an explicit order for these coordinate value variables, which is used if they are to be combined into individual coordinate tuples. + +This order is only significant if crs_wkt is also specified within the referenced grid mapping variable. Explicit 'axis order' is important when the grid_mapping_variable contains an attribute crs_wkt as it is mandated by the OGC CRS-WKT standard that coordinate tuples with correct axis order are provided as part of the reference to a Coordinate Reference System. + Using the simple form, where the **`grid_mapping`** attribute is only the name of a grid mapping variable, 2D latitude and longitude coordinates for a projected coordinate reference system use the same geographic coordinate reference system (ellipsoid and prime meridian) as the projection is @@ -465,6 +469,12 @@ attribute typically will be a single line of text, one intended primarily for ma processing. Other than the requirement to be a valid WKT string, the CF convention does not prescribe the content of the **`crs_wkt`** attribute since it will necessarily be context-dependent. +Where a **`crs_wkt`** attribute is added to a grid_mapping, the extended syntax for the grid_mapping attribute enables the list of variables containing coordinate values being referenced to be explicitly stated and the CRS WKT Axis order to be explicitly defined. The explicit definition of WKT CRS Axis order is expected by the OGC standards for referencing by coordinates. Software implementing these standards are likely to expect to receive coordinate value tuples, with the correct coordinate value order, along with the coordinate reference system definition that those coordinate values are defined with respect to. + +The order of the references within the grid_mapping attribute definition defines the order of elements within a derived coordinate value tuple. This enables an application reading the data from a file to construct an array of coordinate value tuples, where each tuple is ordered to match the specification of the coordinate reference system being used whilst the array of tuples is structured according to the netCDF definition. It is the responsibility of the data producer to ensure that the list is consistent with the CRS WKT definition of CS AXIS, with the correct number of entries in the correct order (note: this is not a conformance requirement as CF conformance is not dependent on CRS WKT parsing). + +For example, a file has two coordinate variables, lon and lat, and a grid mapping variable crs with an associated crs_wkt attribute; the WKT definition defines the AXIS order as ["latitude", "longitude"]. The grid_mapping attribute is thus given a value crs:lat lon to define that where coordinate pairs are required, these shall be ordered (lat, lon), to be consistent with the provided crs_wkt string (and not order inverted). A 2-D array of (lat, lon) tuples can then be explicitly derived from the combination of the lat and lon variables. + The **`crs_wkt`** attribute is intended to act as a _supplement_ to other single-property CF grid mapping attributes (as described in Appendix F); it is not intended to replace those attributes. If data producers omit the single-property grid mapping attributes in favour of the compound @@ -514,9 +524,14 @@ specify CRS properties not covered by existing CF grid mapping attributes, inclu ---- ... + float data(latitude, longitude) ; + data:grid_mapping = "crs: latitude, longitude" ; + ... int crs ; crs:grid_mapping_name = "latitude_longitude"; - ... + crs:longitude_of_prime_meridian = 0.0 ; + crs:semi_major_axis = 6378137.0 ; + crs:inverse_flattening = 298.257223563 ; crs:crs_wkt = GEODCRS["WGS 84", DATUM["World Geodetic System 1984", @@ -531,6 +546,12 @@ specify CRS properties not covered by existing CF grid mapping attributes, inclu ---- ==== +Note: To enhance readability of these examples, the WKT value has been split across multiple lines and embedded +quotation marks (") left unescaped - in real netCDF files such characters would need to be escaped. +In CDL, within the CRS WKT definition string, newlines would need to be encoded within the string as `\n` and double quotes as `\"`. +Also for readability, we have dropped the quotation marks which would delimit the entire crs_wkt string. +This pseudo CDL will not parse directly. + [[british-national-grid-newlyn-datum-in-crs-wkt-format]] [caption="Example 5.12. "] .British National Grid + Newlyn Datum in CRS WKT format @@ -549,13 +570,11 @@ variables: double y(y) ; y:standard_name = "projection_y_coordinate" ; y:units = "m" ; - double lat(y, x) ; - double lon(y, x) ; float temp(y, x) ; temp:long_name = "temperature" ; temp:units = "K" ; temp:coordinates = "lat lon" ; - temp:grid_mapping = "crs" ; + temp:grid_mapping = "crs: x y" ; int crs ; crs:grid_mapping_name = "transverse_mercator" ; crs:longitude_of_central_meridian = -2. ; @@ -615,13 +634,46 @@ variables: ==== -Note: To enhance readability the WKT value has been split across multiple lines and embedded -quotation marks (") left unescaped - in real netCDF files such characters would need to be -escaped. Also for clarity, we have dropped the quotation marks which would delimit the entire crs_wkt -string. +Note: There are unescaped double quotes and newlines and the quotation marks which would delimit the entire crs_wkt string are missing in this example. This is to enhance readability, but it means that this pseudo CDL will not parse directly. +The preceding two example (5.11 and 5.12) may be combined, if the data provider desires to provide explicit latitude and longitude coordinates as well as projection coordinates and to provide CRS WKT referencing for both sets of coordinates. This is demonstrated in example 5.13 +[[british-national-grid-newlyn-datum-with-wgs84-in-crs-wkt-format]] +[caption="Example 5.13. "] +.British National Grid + Newlyn Datum + referenced WGS84 Geodetic in CRS WKT format +==== +---- +... + double x(x) ; + x:standard_name = "projection_x_coordinate" ; + x:units = "m" ; + double y(y) ; + y:standard_name = "projection_y_coordinate" ; + y:units = "m" ; + double lat(y, x) ; + lat_standard_name = "latitude" ; + lat:units = "degrees_north" ; + double lon(y, x) ; + lon_standard_name = "longitude" ; + lon:units = "degrees_east" ; + float temp(y, x) ; + temp:long_name = "temperature" ; + temp:units = "K" ; + temp:coordinates = "lat lon" ; + temp:grid_mapping = "crs_osgb: x y crs_wgs84: latitude longitude" ; + ... + int crs_wgs84 ; + crs_wgs84:grid_mapping_name = "latitude_longitude"; + crs_wgs84:crs_wkt = ... + int crs_osgb ; + crs_osgb:grid_mapping_name = "transverse_mercator" ; + crs_osgb:crs_wkt = ... + ... +---- + +==== +Note: There are unescaped double quotes and newlines and the quotation marks which would delimit the entire crs_wkt string are missing in this example. This is to enhance readability, but it means that this pseudo CDL will not parse directly. [[scalar-coordinate-variables, Section 5.7, "Scalar Coordinate Variables"]] @@ -653,7 +705,7 @@ time and forecast period, or vertical coordinate and model level number, of the same size one dimension, not as scalar coordinate variables. [[multiple-forecasts-from-single-analysis,Example 5.13, "Multiple forecasts from a single analysis"]] -[caption="Example 5.13. "] +[caption="Example 5.14. "] .Multiple forecasts from a single analysis ==== ---- diff --git a/ch09.adoc b/ch09.adoc index bb5d17c3..32eb8124 100644 --- a/ch09.adoc +++ b/ch09.adoc @@ -321,7 +321,8 @@ Table 9.4. The storage of data using the contiguous ragged representation (subsc -In this representation, the file contains a **count variable** , which must be of type integer and +In this representation, the file contains a **count variable** , +which must be an integer type and @@ -462,7 +463,11 @@ Table 9.4 The storage of data using the indexed ragged representation (subscript -In this representation, the file contains an **index variable** , which must be of type integer, and must have the sample dimension as its single dimension. The index variable contains the zero-based index of the feature to which each element belongs. This representation is identifiable by the presence of an attribute, **`instance_dimension`** , on the index variable, which names the dimension of the instance variables. For those indices of the sample dimension, into which data have not yet been written, the index variable should be pre-filled with missing values. +In this representation, the file contains an **index variable** , +which must be an integer type, and must have the sample dimension as its single dimension. +The index variable contains the zero-based index of the feature to which each element belongs. +This representation is identifiable by the presence of an attribute, **`instance_dimension`** , on the index variable, which names the dimension of the instance variables. +For those indices of the sample dimension, into which data have not yet been written, the index variable should be pre-filled with missing values. diff --git a/conformance.adoc b/conformance.adoc index d2072dfe..a7c18cdf 100644 --- a/conformance.adoc +++ b/conformance.adoc @@ -36,13 +36,11 @@ material required for completeness or clarity. [[naming-conventions]] === 2.3 Naming Conventions -*Requirements:* +*Recommendations:* -* Variable, dimension and attribute names must begin with a letter and +* Variable, dimension and attribute names should begin with a letter and be composed of letters, digits, and underscores. -*Recommendations:* - * No two variable names should be identical when case is ignored. [[section-2]] diff --git a/history.adoc b/history.adoc index 7ac79914..cc0d457e 100644 --- a/history.adoc +++ b/history.adoc @@ -196,13 +196,59 @@ Replaced first para in Section 9.6. "Missing Data". Added verbiage to Section 2. .25 June 2018 . Ticket #164, Add bounds attribute to first geometry CDL example. +.14 November 2018 +. link:$$https://github.com/cf-convention/cf-conventions/pull/146$$[Pull request #146]: Typos (plural dimensions) in section H + .15 May 2019 -. GitHub Issue #155, #156. Allow alternate grid mappings for geometry +. link:$$https://github.com/cf-convention/cf-conventions/issues/155$$[Issues #155], link:$$https://github.com/cf-convention/cf-conventions/issues/156$$[#156]: Allow alternate grid mappings for geometry containers. When node_count attribute is missing, require the dimension of the node coordinate variables to be one of the dimensions of the data variable. .17 July 2019 -. #144 - Add <>. +. link:$$https://github.com/cf-convention/cf-conventions/pull/142$$[Pull request #142]: Fix bad reference to an example in section 6.1 "Labels". + +.17 July 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/128$$[Issue #128]: Add definition of 'name_strlen' dimension where missing in Appendix H CDL examples. + +.17 July 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/144$$[Issue #144]: Add <>. + +.22 July 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/136$$[Issue #136]: Missing trajectory dimension in H.22 + +.22 August 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/186$$[Issue #186]: Minor corrections to Example 5.10, Section 9.5 & Appendix F + +.10 September 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/139$$[Issue #139]: Added support for variables of type string. .10 September 2019 . Issue #139: Added support for variables of type string. + +.10 September 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/179$$[Issue #179]: Don't require longitude and Latitude for projected coordinates. + +.10 September 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/198$$[Issue #198]: Clarification of use of standard region names in "region" variables. + +.10 September 2019 +. link:$$https://github.com/cf-convention/cf-conventions/pull/202$$[Pull request #202]: Fix Section 7 examples numbering in the list of examples + +.28 December 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/213$$[Issue #213]: Missing `s`s in grid mapping description texts. + +.29 December 2019 +. link:$$https://github.com/cf-convention/cf-conventions/issues/203$$[Issue #203]: Clarifications to use of groups. + +.11 January 2020 +. link:$$https://github.com/cf-convention/cf-conventions/issues/218$$[Issue #218]: Taxon Names and Identifiers. + +.28 January 2020 +. link:$$https://github.com/cf-convention/cf-conventions/issues/212$$[Issue #212]: Inconsistent usage of false_easting and false_northing in grid mappings definitions and in examples + +.30 January 2020 +. link:$$https://github.com/cf-convention/cf-conventions/issues/223$$[Issue #223]: Axis Order for CRS-WKT grid mappings + +.20 February 2020 +. #230 - Correct inconsistency in units or geostationary projection + diff --git a/toc-extra.adoc b/toc-extra.adoc index f847618d..3494b1b2 100644 --- a/toc-extra.adoc +++ b/toc-extra.adoc @@ -15,9 +15,15 @@ F.1. <> [%hardbreaks] 3.1. <> 3.2. <> +3.2.1. <> 3.3. <> +<<<<<<< HEAD 3.4. <> +3.5. <> +======= +3.4. <> 3.5. <> +>>>>>>> origin/chap_34_update 3.6. <> 4.1. <> 4.2. <>