Merge pull request #317 from JonathanGregory/sigma-pr317

Sigma pr317

appd.adoc

@@ -382,6 +382,7 @@ been defined for `C` or `depth_c`.
 
 ===  Ocean sigma over z coordinate 
 
+**The description of this type of parametric vertical coordinate is defective in version 1.8 and earlier versions of the standard, in that it does not state what values the vertical coordinate variable should contain. Therefore, in accordance with the rules, all versions of the standard before 1.9 are deprecated for datasets that use the "ocean sigma over z" coordinate.**
 
 ----
 
@@ -395,39 +396,33 @@ Definition:::
 +
 ----
 
-for k <= nsigma:
+for levels k where sigma(k) has a defined value and zlev(k) is not defined:
 
   z(n,k,j,i) = eta(n,j,i) + sigma(k)*(min(depth_c,depth(j,i))+eta(n,j,i))
- 
-for k > nsigma:
+
+for levels k where zlev(k) has a defined value and sigma(k) is not defined:
 
   z(n,k,j,i) = zlev(k)
               
 ----
 
-where `z(n,k,j,i)` is height (positive upwards) relative to the datum (e.g.
-mean sea level) at gridpoint `(n,k,j,i)`, `eta(n,j,i)` is the height of the sea
-surface (positive upwards) relative to the datum at gridpoint `(n,j,i)`,
-`sigma(k)` is the dimensionless coordinate at vertical gridpoint `(k)` for `k
-&lt;= nsigma`, and `depth(j,i)` is the distance (a positive value) from the
-datum to the sea floor at horizontal gridpoint `(j,i)`. Above depth `depth_c`
-there are `nsigma` layers and below this depth the levels are surfaces of
-constant height `zlev` (positive upwards) relative to the datum.
+where `z(n,k,j,i)` is height, positive upwards, relative to ocean datum (e.g. mean sea level) at gridpoint `(n,k,j,i)`, `eta(n,j,i)` is the height of the ocean surface, positive upwards, relative to ocean datum at gridpoint `(n,j,i)`, and `depth(j,i)` is the distance from ocean datum to sea floor (positive value) at horizontal gridpoint `(j,i)`.
+
+The parameter `sigma(k)` is defined only for the `nsigma` layers nearest the ocean surface, while `zlev(k)` is defined for the `nlayer - nsigma` deeper layers, where `0 \<= nsigma \<= nlayer` and `nlayer` is the size of the dimension of the vertical coordinate variable. Both `sigma` and `zlev` must have this dimension. For any `k`, whichever of `sigma(k)` or `zlev(k)` is undefined must contain missing data, while the other must not.
+
+The format for the `formula_terms` attribute is 
 
-The format for the **`formula_terms`** attribute is 
 ----
 
 formula_terms = "sigma: var1 eta: var2 depth: var3 depth_c: var4 nsigma: var5
                 zlev: var6"
         
 ----
 
-The pass:q[`standard_name`]s for `eta`, `depth`, `zlev` 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 `depth_c` or `nsigma`.
+The pass:q[`standard_name`]s for `eta`, `depth`, `zlev` and the `computed_standard_name` must be one of the consistent sets shown in <<table-computed-standard-names, Table D.1>>. The `standard_name` for `sigma` is `ocean_sigma_coordinate`. No `standard_name` has been defined for `depth_c` or `nsigma`. The `nsigma` parameter is deprecated and optional in `formula_terms`; if supplied, it must equal the number of elements of `zlev` which contain missing data. 
+
+The `standard_name` for the vertical coordinate variable is `ocean_sigma_z_coordinate`. This variable should contain `sigma(k)*depth_c` for the layers where `sigma` is defined and `zlev(k)` for the other layers, with units of length. The layers must be arranged so that the vertical coordinate variable contains a monotonic set of indicative values for the heights of the levels relative to the datum, either increasing or decreasing, and the direction must be indicated by the `positive` attribute, in the usual way for a vertical coordinate variable.
 
-
 ===  Ocean double sigma coordinate 
 
 

conformance.adoc

@@ -681,4 +681,13 @@ in the file.
 starting with 0 and going up to the product of the compressed dimension
 sizes minus 1 (CDL index conventions).
 
-
+=== Appendix D Parametric Vertical Coordinates
+
+*Requirements:*
+
+* For each element `k` of a vertical coordinate variable with `**standard_name = "ocean_sigma_z_coordinate"**`, one and only one of the formula terms `**sigma(k)**` and `**zlev(k)**` must be missing data. If the optional formula term `**nsigma**` is supplied, it must equal the number of elements of `**zlev**` which contain missing data.
+
+*Recommendations:*
+
+* For a vertical coordinate variable with `**standard_name = "ocean_sigma_z_coordinate"**`, the formula term `**nsigma**` should be omitted.
+* Versions of the standard before 1.9 should not be used for vertical coordinate variables with `**standard_name = "ocean_sigma_z_coordinate"**` because these versions are defective in their definition of this coordinate.

history.adoc

@@ -278,3 +278,6 @@ node coordinate variables to be one of the dimensions of the data variable.
 
 .10 March 2021
 . link:$$https://github.com/cf-convention/cf-conventions/issues/313$$[Issue #313]: Clarification of the handling of leap seconds
+
+.24 May 2021
+. link:$$https://github.com/cf-convention/cf-conventions/issues/314$$[Issue #314]: Correction to the definition of "ocean sigma over z coordinate" in Appendix D