Conformance changes (including bounds) (#21)

* added example 6.1.2 to the list of examples; fixed cf-convention#284 * updated changes in history.adoc * removed fourth lines of third table in sect 9.3.1; fixed cf-convention#288 * updated history * Bring conformance doc in line with clarification to use of region names/area_types to allow use of flag_values and flag_meanings as per discussion in cf-convention#198 * Add support for variables of type string to conformance doc. See issue cf-conventions#139 * Revert "Bring conformance doc in line with clarification to use of region names/area_types to allow use of flag_values and flag_meanings as per discussion in cf-convention#198" This reverts commit f754457. * first draft of section 5.8 * format typo * rewording * rewording * rewording * New 'Do' Use value, and 'dimensions' entry * Domain construct * rewording * rewording * rewording * formatting of computed_standard_name entry * rewording * rewording * rewording * top-level * rewording * move fig 3 * rewording * span * rewording * data * rewording * rewording * rewording * conformance * recommended attributes * typo * dimensions * dimensions * format * typo * domain independence * domain optional * format * format * format * format * empty dimensions * long_name * UML * Update ch01.adoc * Update history.adoc * Add static assets to HTML check build * Add static assets to Travis upload job * Fix order of i/j in lon/lat bnds figure correct indices of neighbour cells in @d case * update/correct order of indices i/j in Fig 2 (2D lon/lat bounds) * update/correct order of indices i/j in caption of Fig 2 * rename "figure 1" to "figure 3" in Appendix i * correct indices of neighbour cells in @d case * update history Figures are generated from: https://github.com/neumannd/cell_bounds_figures_for_cf_conventions * updates arising from cf-convention#301 up to 2020-09-28 * correct label for 1.2 * format correction * reword empty dimensions example * comma * example links * long_name * formatting * missing 'construct' * term units * term units * standard names * typo * units conformance requirement * remove requirement for identical units * Copyedit * fixed typos * History * more text following 2020-11-27 discussions * bounds * tidy * tidy * tidy * tidy * reproducability * offset * indices * indices * indices * super * tie_point_dimension (1) * tie_point_dimension (2) * tie_point_dimension (3) * tie_point_dimension (4) * tie point * tie_point_dimension (5) * corrected interpolation_configuration description * zone/area rewording * zone/area rewording * multiple mappings * multiple mappings * multiple mappings * typos and some minor rewording suggestions * format * spell check * markup style * example formatting * example formatting * example formatting * example formatting * minor typesetting * interpolation_parameters * interpolation parameters variable dimensions * interpolation parameters variable dimensions * non-standard provision * interpolation parameters variable dimensions * captions, cdl * tidy * minumum size of interpolation zones * Appendix A attributes * interpolation -> sampling * Conformance - first draft * 2nd draft: better descriptions of allowed dimensions * typos * Correct 'is list' to 'is a list' * history cf-convention#304 * check on interpolation zone dimension size * Clarification of the handling of leap seconds This is the suggested initial wording from cf-convention#313 as authored by @JonathanGregory. * leap seconds: added the word "count" in some places The purpose of this change is to slightly highlight the difference between when seconds are used within the coordinate value for counting and the seconds which are part of the date-time. * leap seconds: minor wording extension * leap seconds: added reference to cf-convention#313 to history.adoc * add myself to the end of the list of additional authors * leap seconds: updated conformance text This change excludes values larger or equal to 60 for seconds in reference date-times in time unit attributes. Additionally, the reference time has been changed to reference date-time to agree with the wording in the proposed conventions text. * leap seconds: small rewording as discussed with @JonathanGregory Reasoning: counting may be associated with integral numbers, which is was not intended. We still like the idea of a little more separation between seconds as a unit of the value and seconds as in the date-times. * replace date-time with date/time * conformance changes for new interpolation variable * conformance changes for new interpolation variable * conformance changes for new interpolation variable * conformance changes for new interpolation variable * appendix A changes for new interpolation variable * appendix A changes for new interpolation variable * lat lon tie point definition * spelling * URI -> URL * lower resolution -> sampled * Use on domain variable * typo * Move 'interpolation dimension' definition to first occurence * Minor re-wording * Fix cross-reference * Re-wording * typesetting * tie point index re-wording * Rotation of interpolation axes for two dimensional methods and mino corrections * terminology: interpolation variable and tie point variable * typo * examples in toc * Replace expression for gsqr with equivalent, but numerically more accurate version * Update authors * Update history * Rename attribute tie_points to coordinate_interpolation (Change 2) * Reword section Interpolation and Non-Interpolation Dimensions (Cahnge 10) * Rename tie_point_dimensions attribute to tie_point_mapping (Change 2) * Change term 'tie point variable' to 'tie point coordinate variable' (Change 4) * Reword first paragraph of Section 8 (Change 6) * Remove sentence "This form of compression may also be..." (Change 7) * Update sentence: "A single interpolation dimension may be associated..." (Change 9) * Reword section "Interpolation and non-interpolation dimension" (Change 10) * Improve sentence "An interpolation zone must span at least two points..." (Change 11) * Correct sentence "....must be a subset of zero or more of the ..." (Change 12) * Reword text about the dimensions of interpolation parameter (Change 13) * Improve sentence "The bounds of a tie point must be the same..." (Change 14) * Reduce number of data variables in Example 8.5 (Change 16) * Rename "terms to continuous area" and "interpolation subarea" (Change 5) * Improve wording of "An interpolation subarea must span..." (Change 11) * Remove paragraph "The same interpolation variable may be multiply mapped ...." no longer relevant * Rename terms to: subsampled dimension, interpolated dimension and non-interpolated dimension * Combine the tie_point_dimensions and tie_point_indices attributes (Change 1) * Update figures to match new terms * Improve description of non-overlapping interpolation subareas * Improve description of non-overlapping interpolation subareas * Update Example 8.6 to correctly specify one dimension interpolation for X and Y * Improve wording of Tie Point Index Mapping (Change 8) * Clarify interpolation subarea size * Clarify dimensions in Figure 2 * Add new section 8.3.9, "Computational Precision" * Combine the tie_point_dimensions and tie_point_indices attributes (Change 1) * Remove paragraph "A single interpolated dimension may be associated with multiple ...." no longer relevant * Update ch08.adoc Co-authored-by: David Hassell <[email protected]> * Update ch08.adoc Co-authored-by: David Hassell <[email protected]> * Update ch08.adoc Co-authored-by: David Hassell <[email protected]> * Update ch08.adoc Co-authored-by: David Hassell <[email protected]> * Change sampl... to subsampl... * Rewrite section Interpolation of Cell Boundaries (Change 15) * Constrain interpolation parameters to support bounds interpolation * Update <<link>> names and figure names to new terms * Require tie points to be numeric type and have no missing values * Update Appendix J with new terms and names * Correct spelling mistake in Appendix J * Correct numbering mistake in Appendix J * Change "iz" (interpolation zone) to "is" (interpolation subarea) in App J (Change 3) * Correct "target dimension" to "interpolated dimension" (Change 17) * Introduce section numbering and remove table captions in Appendix J * Include interpolation argument s in figure 1 and 2 * Move Figure 1 and 2 in Appendix J futher down * State tht for linear interpolation, the coordinates of the interpolated points are evenly spaced. * Change "equivalently" to "similarly" in explanation of s1 and s2 in App J * Rename cofficeint "c" to "w" in Appendix J to avoid confusion with point C * Move "Common Conversions and Formulas" in front of "Interpolation Methods" in Appendix J * Add "s" to "each of the interpolated dimension" in Appendix J * Minor wording improvements arising from review * Conformance for bounds tie points * computational_precision conformance Co-authored-by: Daniel Neumann <[email protected]> Co-authored-by: Rosalyn Hatcher <[email protected]> Co-authored-by: JonathanGregory <[email protected]> Co-authored-by: Daniel Lee <[email protected]> Co-authored-by: Daniel Lee <[email protected]> Co-authored-by: David Blodgett <[email protected]> Co-authored-by: AndersMS <[email protected]> Co-authored-by: Tobias Kölling <[email protected]> Co-authored-by: Tobias Kölling <[email protected]>
AndersMS · Aug 3, 2021 · a276717 · a276717
1 parent cab79eb
commit a276717
Show file tree

Hide file tree

Showing 30 changed files with 1,154 additions and 1,245 deletions.
diff --git a/.github/workflows/check_adoc_build.yml b/.github/workflows/check_adoc_build.yml
@@ -28,7 +28,7 @@ jobs:
     - name: Build cf-conventions.html
       uses: Analog-inc/[email protected]
       with:
-        shellcommand: 'asciidoctor --verbose cf-conventions.adoc -D conventions_build'
+        shellcommand: 'asciidoctor --verbose cf-conventions.adoc -D conventions_build; cp -r images conventions_build'
     # Build cf-conventions.pdf using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.pdf
       uses: Analog-inc/[email protected]

diff --git a/.travis.yml b/.travis.yml
@@ -24,6 +24,7 @@ script:
 after_success:
     # Always update the "gh-pages" branch, but tag build goes into
     # tag directory and normal build goes into the root directory.
+    - mv images/ images~
     - git fetch origin gh-pages:gh-pages
     - git checkout gh-pages
     - if [[ $TRAVIS_TAG ]]; then
@@ -32,10 +33,12 @@ after_success:
         TARGET_DIR='.';
       fi
     - mkdir -p $TARGET_DIR
+    - mv images~ $TARGET_DIR/images
     - cp build/cf-conventions.html $TARGET_DIR/
     - cp build/cf-conventions.pdf $TARGET_DIR/
     - cp build/conformance.html $TARGET_DIR/
     - cp build/conformance.pdf $TARGET_DIR/
+    - git add $TARGET_DIR/images
     - git add $TARGET_DIR/cf-conventions.html
     - git add $TARGET_DIR/cf-conventions.pdf
     - git add $TARGET_DIR/conformance.html

diff --git a/appa.adoc b/appa.adoc
@@ -4,9 +4,19 @@
 [appendix]
 == Attributes
 
-All CF attributes are listed here except for those that are used to describe grid mappings. See Appendix F for the grid mapping attributes.
-
-The "Type" values are **S** for string, **N** for numeric, and **D** for the type of the data variable. The "Use" values are **G** for global, **Gr** for applying to groups, **C** for variables containing coordinate data, **D** for variables containing non-coordinate data, **M** for geometry container variables, and **-** for variables with a special purpose. "Links" indicates the location of the attribute"s original definition (first link) and sections where the attribute is discussed in this document (additional links as necessary).
+All CF attributes are listed here except for those that are used to
+describe grid mappings. See Appendix F for the grid mapping
+attributes.
+
+The "Type" values are **S** for string, **N** for numeric, and **D**
+for the type of the data variable. The "Use" values are **G** for
+global, **Gr** for applying to groups, **C** for variables containing
+coordinate data, **D** for data variables, **M** for geometry
+container variables, **Do** for domain variables, and **-** for
+variables with a special purpose. "Links" indicates the location of
+the attribute"s original definition (first link) and sections where
+the attribute is discussed in this document (additional links as
+necessary).
 
 [[table-attributes]]
 .Attributes
@@ -57,7 +67,7 @@ Attribute
 
 | **`cell_measures`**
 | S
-| D
+| D, Do
 | <<cell-measures>>
 | Identifies variables that contain cell areas or volumes.
 
@@ -91,7 +101,7 @@ Attribute
 | <<compression-by-gathering>>, <<reduced-horizontal-grid>>
 | Records dimensions which have been compressed by gathering.
 
-| `computed_standard_name`
+| **`computed_standard_name`**
 | S
 | C
 | <<parametric-vertical-coordinate>>
@@ -107,10 +117,15 @@ formula in the definition.
 
 | **`coordinates`**
 | S
-| D, M
+| D, M, Do
 | <<coordinate-system>>, <<labels>>, <<alternative-coordinates>>
 | Identifies auxiliary coordinate variables, label variables, and alternate coordinate variables.
 
+|**`dimensions`**
+| S
+| Do
+| <<domain-variables>>
+| Identifies the dimensions that define a domain variable.
 
 |**`external_variables`**
 | S
@@ -158,7 +173,7 @@ formula in the definition.
 
 | **`geometry`**
 | S
-| C, D
+| C, D, Do
 | <<geometries>>
 | Identifies a variable that defines geometry.
 
@@ -170,7 +185,7 @@ formula in the definition.
 
 | **`grid_mapping`**
 | S
-| D, M
+| D, M, Do
 | <<grid-mappings-and-projections>>
 | Identifies a variable that defines a grid mapping.
 
@@ -212,7 +227,7 @@ formula in the definition.
 
 | **`long_name`**
 | S
-| C, D
+| C, D, Do
 | link:$$http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"], and <<long-name>>
 | A descriptive name that indicates a variable"s content. This name is not standardized.
 

diff --git a/appd.adoc b/appd.adoc
@@ -306,6 +306,8 @@ is the dimensionless coordinate at vertical gridpoint `(k)`, and `depth(j,i)`
 is the distance (a positive value) from the datum to the sea floor at
 horizontal gridpoint `(j,i)`. The constants `a`, `b`, and `depth_c` control the
 stretching.
+The constants `a` and `b` are dimensionless, and `depth_c` must have
+units of length.
 
 The format for the **`formula_terms`** attribute is 
 ----
@@ -342,7 +344,12 @@ The format for the **`formula_terms`** attribute is
 ----
 formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"
 ----
-
+
+The pass:q[`standard_name`]s for `eta` and `depth` and the
+`computed_standard_name` must be one of the consistent sets shown in
+<<table-computed-standard-names, Table D.1>>. No `standard_name` has
+been defined for `C` or `depth_c`.
+
 
 === Ocean s-coordinate, generic form 2
 ----
@@ -368,6 +375,10 @@ The format for the **`formula_terms`** attribute is
 formula_terms = "s: var1 C: var2 eta: var3 depth: var4 depth_c: var5"
 ----      
 
+The pass:q[`standard_name`]s for `eta` and `depth` and the
+`computed_standard_name` must be one of the consistent sets shown in
+<<table-computed-standard-names, Table D.1>>. No `standard_name` has
+been defined for `C` or `depth_c`.
 
 ===  Ocean sigma over z coordinate 
 
@@ -448,7 +459,7 @@ where `z(k,j,i)` is height (positive upwards) relative to the datum (e.g. mean
 sea level) at gridpoint `(k,j,i)`, `sigma(k)` is the dimensionless coordinate
 at vertical gridpoint `(k)` for `k &lt;= k_c`, and `depth(j,i)` is the distance
 (a positive value) from the datum to sea floor at horizontal gridpoint `(j,i)`.
-`z1`, `z2`, `a`, and `href` are constants.
+`z1`, `z2`, `a`, and `href` are constants with units of length.
 
 The format for the **`formula_terms`** attribute is 
 ----

diff --git a/appi.adoc b/appi.adoc
@@ -85,7 +85,7 @@ information about the dataset as a whole. NetCDF library software has
 functions to define dimensions, variables and attributes, and write
 and read data.
 
-[[img-netCDF, figure 1]]
+[[img-netCDF, figure 3]]
 [.text-center]
 .Key components of the netCDF classic data model. Files consist of global attributes, dimensions and variables. Variables contain attributes and data, and attributes also contain data. Variables, attributes and dimensions all contain properties, such as a "name" which identifies them in the file. A data array has a data type for all of its elements (e.g. "double" for 64-bit floating point numbers).
 image::images/cfdm_netcdf_classic_data_model.png[,50%,pdfwidth=50vw,align="center"]
@@ -100,7 +100,6 @@ encoding, and reducing the number of elements, whilst retaining the
 ability to describe the CF conventions fully, in order to meet the
 design criteria.
 
-
 [[table-cf-concepts, table 1]]
 .The elements of the CF-netCDF conventions. The relationships to netCDF entities are shown in <<img-cf-concepts>>.
 [options="header",cols="2",caption="Table 1. "]
@@ -163,7 +162,6 @@ be programming language-neutral (i.e. as opposed to "object" or
 related to CF-netCDF entities (<<img-cf-concepts>>), which in turn
 relate to the components of netCDF file (<<img-netCDF>>).
 
-
 [[table-cf-constructs, table 2]]
 .The constructs of the CF data model. The relationships between the constructs and CF-netCDF entities are shown in in <<img-field>>, <<img-dim-aux>> and <<img-coordinate-reference>>.
 [options="header",cols="2",caption="Table 2. "]
@@ -175,6 +173,9 @@ CF construct
 | Field
 | Scientific data discretised within a domain
 
+| Domain
+| Describes a domain
+
 | Domain axis
 | Independent axes of the domain
 
@@ -200,30 +201,45 @@ CF construct
 | Describes how data represents variation within cells
 |===============
 
+The field construct and domain construct are central to the CF data
+model in that all the other constructs are included in one or other of
+them (<<img-field>>). The constructs contained by the field and domain
+constructs cannot exist independently, with the exception of the
+domain construct itself that may be part of a field construct or exist
+on its own, as is indicated by the nature of the class associations
+shown in <<img-field>>. All CF-netCDF elements are mapped to field
+constructs, domain constructs or their components; and the field and
+domain constructs completely contain all the data and metadata which
+can be extracted from the file using the CF conventions.
+
+[[img-field, figure 3]]
+[.text-center]
+.The constructs of the CF data model. The field construct corresponds to a CF-netCDF data variable (defined in <<img-cf-concepts>> and identified here with the "CN" prefix). Relationships between other constructs and CF-netCDF are given in <<img-dim-aux>> and <<img-coordinate-reference>>. The domain construct provides the linkage between the field construct and the constructs which describe measurement locations and cell properties. It is useful to define an abstract generic coordinate construct that can be used to refer to coordinates when the their type (dimension or auxiliary coordinate construct) is not an issue.
+image::images/cfdm_field.png[,50%,pdfwidth=50vw,align="center"]
+
 === Field construct
 
-The field construct is central to the CF data model and includes all
-the other constructs (<<img-field>>). A field corresponds to a
-CF-netCDF data variable with all of its metadata. All CF-netCDF
-elements are mapped to some component of the CF field construct and
-the field constructs completely contain all the data and metadata
-which can be extracted from the file using the CF conventions. Note
-that the constructs contained by the field construct cannot exist
-independently, as is indicated by the nature of the class associations
-shown in <<img-field>>.
-
-The field construct consists of a data array and the definition of its
-domain, ancillary metadata defined over the same domain, metadata to
-describe how the cell values represent the variation of the physical
-quantity within the cells of the domain (<<img-field>>), and
-properties to describe aspects of the data that are independent of the
-domain. All of the constructs contained by the field construct are
-optional (as indicated by "0..*" in <<img-field>>). The only component
-of the field which is mandatory is the data array. Because the CF
-conventions do not mention the concept of the domain, it is not
-regarded as a construct of the data model. Instead, the domain is
-defined collectively by various other constructs included in the
-field.
+A field construct (<<img-field>>) corresponds to a CF-netCDF data
+variable with all of its metadata. The field construct consists of
+
+* A data array.
+
+* A domain construct containing metadata defining the domain that
+  provides measurement locations and cell properties for the data.
+
+* Field ancillary constructs containing ancillary metadata defined
+  over the same domain.
+
+* Cell method constructs containing metadata to describe how the cell
+  values represent the variation of the physical quantity within the
+  cells of the domain.
+
+* Properties to describe aspects of the data that are independent of
+  the domain.
+
+All of the constructs contained by the field construct are optional
+(as indicated by "0.." in <<img-field>>). The only component of the
+field which is mandatory is the data array.
 
 The properties of the field construct correspond to some netCDF
 attributes of variables (e.g. the **`units`**, **`long_name`**, and
@@ -243,25 +259,47 @@ file attributes is not stated in the CF conventions, but for the data
 model it is necessary because there is no notion of a file. Hence,
 metadata stored in attributes of the file as a whole have to be
 transferred to the field construct. If present, the global file
-attribute featureType applies to every data variable in the file with
-a discrete sampling geometry. Hence, the feature type is regarded as a
-property of the field construct.
-
-The standard_name property constrains the units property (i.e. only
-certain units are consistent with each standard name) and in some
-cases also the dimensions that a data variable must have. These
-constraints, however, do not supply any further information--they are
-just for self consistency. Similarly the featureType property imposes
-some requirements on the axes the domain must have. Following the aim
-of constructing a minimal data model, the standard name and
-featureType are not regarded as separate constructs within the field,
-because they do not depend on any other construct for their
-interpretation.
+attribute **`featureType`** applies to every data variable in the file
+with a discrete sampling geometry. Hence, the feature type is regarded
+as a property of the field construct.
 
-[[img-field, figure 3]]
-[.text-center]
-.The constructs of the CF data model. The field construct corresponds to a CF-netCDF data variable (defined in <<img-cf-concepts>> and identified here with the "CN" prefix). Relationships between other constructs and CF-netCDF are given in <<img-dim-aux>> and <<img-coordinate-reference>>. The domain provides the linkage between the field construct and the constructs which describe measurement locations and cell properties. It is not a construct of the data model, but is an abstract concept that is useful for understanding it. Similarly, it is useful to define an abstract generic coordinate construct that can be used to refer to coordinates when the their type (dimension or auxiliary coordinate construct) is not an issue.
-image::images/cfdm_field.png[,50%,pdfwidth=50vw,align="center"]
+The **`standard_name`** property constrains the **`units`** property
+(i.e. only certain units are consistent with each standard name) and
+in some cases also the dimensions that a data variable must
+have. These constraints, however, do not supply any further
+information--they are just for self consistency. Similarly the
+**`featureType`** property imposes some requirements on the axes the
+domain must have. Following the aim of constructing a minimal data
+model, the standard name and feature type are not regarded as separate
+constructs within the field, because they do not depend on any other
+construct for their interpretation.
+
+=== Domain construct
+
+The domain construct (<<img-field>>) describes a domain comprising
+measurement locations and cell properties. The domain construct is the
+only metadata construct that may also exist independently of a field
+construct. The domain construct contains properties to describe the
+domain (in the same sense as for the field construct) and relates the
+following metadata constructs
+
+* Domain axis constructs.
+
+* Dimension coordinate and auxiliary coordinate constructs.
+
+* Coordinate reference constructs.
+
+* Domain ancillary constructs.
+
+* Cell measure constructs.
+
+All of the constructs contained by the domain construct are optional
+(as indicated by "0.." in <<img-field>>).
+
+In CF-netCDF, domain information is stored either implicitly via data
+variable attributes (such as `coordinates`), or explicitly in a domain
+variable. In the latter case, the domain exists without reference to a
+data array.
 
 === Domain axis construct and the data array