Edits for "conventions" and impersonal form#628
Merged
JonathanGregory merged 3 commits intocf-convention:mainfrom Mar 3, 2026
Merged
Edits for "conventions" and impersonal form#628JonathanGregory merged 3 commits intocf-convention:mainfrom
JonathanGregory merged 3 commits intocf-convention:mainfrom
Conversation
apph.adoc
Outdated
|
|
||
| While an idealized time series is defined at a single, stable point location, there are examples of time series, such as cabled ocean surface mooring measurements, in which the precise position of the observations varies slightly from a nominal fixed point. It is quite common that the deployment position of a station changes after maintenance or repositioning after it drifts. | ||
| In the following example we show how the spatial positions of such a time series should be encoded in CF. In addition, this example shows how lossless compression by gathering <<compression-by-gathering>> has been applied to the deployment coordinate variables, which otherwise would contain a lot of missing or repetitive data. | ||
| In the following example it is shown how the spatial positions of such a time series should be encoded in CF. In addition, this example shows how lossless compression by gathering <<compression-by-gathering>> has been applied to the deployment coordinate variables, which otherwise would contain a lot of missing or repetitive data. |
Contributor
There was a problem hiding this comment.
"In the following example it is shown" could be "The following example shows"
| The extensions include metadata that provides a precise definition of each variable via specification of a standard name, describes the vertical locations corresponding to dimensionless vertical coordinate values, and provides the spatial coordinates of non-rectilinear gridded data. | ||
| Since climate and forecast data are often not simply representative of points in space/time, other extensions provide for the description of coordinate intervals, multidimensional cells and climatological time coordinates, and indicate how a data value is representative of an interval or cell. | ||
| This standard also relaxes the COARDS constraints on dimension order and specifies methods for reducing the size of datasets. | ||
| These conventions also relax the COARDS constraints on dimension order and specifies methods for reducing the size of datasets. |
Contributor
There was a problem hiding this comment.
"and specify methods"
| Our main purpose therefore, is to propose a clear, adequate and flexible definition of the metadata needed for climate and forecast data. | ||
| Although this is specifically a netCDF standard, we feel that most of the ideas are of wider application. | ||
| These conventions are intended for use with climate and forecast data, for atmosphere, surface and ocean, and was designed with model-generated data particularly in mind. | ||
| It is recognised that there are limits to what a set of conventions can practically cover; these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. |
Contributor
There was a problem hiding this comment.
A neater way would be, "Recognising that there ... practically cover, these conventions ...".
Contributor
There was a problem hiding this comment.
climate and forecast data, for atmosphere, surface and ocean, and was designed with model-generated data particularly in mind.
It seems to me that the scope of CF has broadened wuite a bit since it started -- is this statement still true?
Also -- I've always been a bit confused as to what "climate and forecast" means anyway ;-)
I"m not sure I can think of a better way to define the scope, however, but maybe something about:
conventions for oceanographic and meteorological data?
(though we're expanding into hydrologic and ??? as we go...)
Contributor
Author
There was a problem hiding this comment.
This is a topic that would require a broader discussion. Perhaps open a separate issue on this?
Contributor
There was a problem hiding this comment.
I agree that this is a different issue from the present one, but worth considering elsewhere.
| These conventions are intended for use with climate and forecast data, for atmosphere, surface and ocean, and was designed with model-generated data particularly in mind. | ||
| It is recognised that there are limits to what a set of conventions can practically cover; these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. | ||
| The main purpose therefore, is to propose a clear, adequate and flexible definition of the metadata needed for climate and forecast data. | ||
| Although these conventions are specifically targeting the netCDF format, most of the ideas are of wider application. |
Contributor
There was a problem hiding this comment.
"Although these are conventions for netCDF specifically, most of the ideas ..."
| Conversion of the metadata between files of different formats will be facilitated if conventions for all formats are based on similar ideas. | ||
|
|
||
| This convention is designed to be backward compatible with the COARDS conventions <<COARDS>>, by which we mean that a conforming COARDS dataset also conforms to the CF standard. | ||
| These conventions are designed to be backward compatible with the COARDS conventions <<COARDS>>, which implies that a conforming COARDS dataset also conforms to the CF conventions. |
Contributor
There was a problem hiding this comment.
"<>; this means that". I would say it's a definition rather than an implication.
Contributor
There was a problem hiding this comment.
I agree -- it's more than in implication. -- is it still fully backward compatible now? or only mostly?
If it's fully backward compatible then we can simply say that.
These conventions are backward compatible with the COARDS conventions <>; a conforming COARDS dataset also conforms to the CF conventions.
If mosty, we can say that, too.
These conventions are designed to be backward compatible with the COARDS conventions <>; most conforming COARDS datasets also conforms to the CF conventions.
Contributor
There was a problem hiding this comment.
I believe that COARDS-compliant datasets are also compliant with the latest CF version, although there are some COARDS conventions that CF recommends against.
|
|
||
| We have also striven to maximize conformance to the COARDS standard, that is, wherever the COARDS metadata conventions provide an adequate description we require their use. | ||
| Extensions to COARDS are implemented in a manner such that the content that doesn't depend on the extensions is still accessible to applications that adhere to the COARDS standard. | ||
| These conventions also strive to maximize conformance to the COARDS conventions, that is, wherever the COARDS metadata conventions provide an adequate description their use is included here. |
Contributor
There was a problem hiding this comment.
I think that only animate agents can strive, and the conventions have not yet got a life of their own. I suggest we replace this with a simpler sentence which has the same intention. "These conventions uphold the COARDS metadata conventions wherever the latter provide an adequate description."
| No variable or dimension names are standardized by this convention. | ||
| Instead we follow the lead of the <<NUG>> and standardize only the names of attributes and some of the values taken by those attributes. | ||
| No variable or dimension names are standardized by these conventions. | ||
| Instead, the lead of the <<NUG>> is followed and only the names of attributes and some of the values taken by those attributes are standardized. |
Contributor
There was a problem hiding this comment.
"Instead, following the lead of the <>, only the names of attributes ..."
| Four types of coordinates receive special treatment by these conventions: latitude, longitude, vertical, and time. | ||
| Every variable must have associated metadata that allows identification of each such coordinate that is relevant. | ||
| Two independent parts of the convention allow this to be done. | ||
| Two independent parts of the conventions allow this to be done. |
Contributor
There was a problem hiding this comment.
"Two kinds of conventions allow this to be done."
| A major design goal has been to maintain __backward compatibility__ with COARDS. | ||
| Hence applications written to process datasets that conform to these conventions will also be able to process COARDS conforming datasets. | ||
| We have also striven to maximize __conformance__ to the COARDS standard so that datasets that only require the metadata that was available under COARDS will still be able to be processed by COARDS conforming applications. | ||
| The conventions also strive to maximize __conformance__ to the COARDS conventions so that datasets that only require the metadata that was available under COARDS will still be able to be processed by COARDS conforming applications. |
Contributor
There was a problem hiding this comment.
"As far as possible, these conventions maximize ...".
| For instance, a variable containing a two-dimensional probability density function might correlate the temperature at two different vertical levels, and hence would have temperature on both axes. | ||
|
|
||
| If any or all of the dimensions of a variable have the interpretations of "date or time" (**`T`**), "height or depth" (**`Z`**), "latitude" (**`Y`**), or "longitude" (**`X`**) then we recommend, but do not require (see <<coards-relationship>>), those dimensions to appear in the relative order **`T`**, then **`Z`**, then **`Y`**, then **`X`** in the CDL definition corresponding to the file. | ||
| If any or all of the dimensions of a variable have the interpretations of "date or time" (**`T`**), "height or depth" (**`Z`**), "latitude" (**`Y`**), or "longitude" (**`X`**) then it is recommended but not required (see <<coards-relationship>>) that those dimensions to appear in the relative order **`T`**, then **`Z`**, then **`Y`**, then **`X`** in the CDL definition corresponding to the file. |
Contributor
There was a problem hiding this comment.
"that those dimensions appear" [no "to"]
| "area fraction" or "probability") does not belong in the **`units`** attribute, but should be given in the **`long_name`** or **`standard_name`** attributes (see <<long-name>> and <<standard-name>>), in the same way as for physical quantities with dimensional units. | ||
| As an exception, to maintain backwards compatibility with COARDS, the text strings `level`, `layer`, and `sigma_level` are allowed in the **`units`** attribute, in order to indicate dimensionless vertical coordinates. | ||
| This use of **`units`** is not compatible with UDUNITS, and is deprecated by this standard because conventions for more precisely identifying dimensionless vertical coordinates are available (see <<dimensionless-vertical-coordinate>>). | ||
| This use of **`units`** is not compatible with UDUNITS, and is deprecated by these conventions because conventions for more precisely identifying dimensionless vertical coordinates are available (see <<dimensionless-vertical-coordinate>>). |
Contributor
There was a problem hiding this comment.
more simply, "and is deprecated because"
| Four types of coordinates receive special treatment by these conventions: latitude, longitude, vertical, and time. | ||
| We continue to support the special role that the **`units`** and **`positive`** attributes play in the COARDS convention to identify coordinate type. | ||
| As an extension to COARDS, we strongly recommend that a parametric (usually dimensionless) vertical coordinate variable should be associated, via **`standard_name`** and **`formula_terms`** attributes, with its explicit definition, which provides a mapping between its values and dimensional vertical coordinate values that can be uniquely located with respect to a point on the earth's surface. | ||
| The special role that the **`units`** and **`positive`** attributes play in the COARDS conventions to identify coordinate type continues to be supported. |
Contributor
There was a problem hiding this comment.
Maybe easier to read, "These conventions continue to support the special ... to identify coordinate type."
| Application writers should note that the UDUNITS package has limited recognition of the directionality implied by the "east" part of the unit specification. | ||
| It defines **`degrees_east`** to be pi/180 radians, and hence equivalent to **`degrees_north`**. | ||
| We recommend the determination that a coordinate is a longitude type should be done via a string match between the given unit and one of the acceptable forms of **`degrees_east`**. | ||
| Hence, determination that a coordinate is a longitude type should be done via a string match between the given unit and one of the acceptable forms of **`degrees_east`**. |
Contributor
There was a problem hiding this comment.
"Hence, a string match between the given unit and one of the acceptable forms of degrees_east is the recommended method to determine whether a coordinate is of longitude type."
|
|
||
| When data is representative of geographic regions which can be identified by names but which have complex boundaries that cannot practically be specified using longitude and latitude boundary coordinates, a labeled axis should be used to identify the regions. | ||
| We recommend that the names be chosen from the list of link:$$https://cfconventions.org/Data/cf-standard-names/docs/standardized-region-names.html$$[standardized region names] whenever possible. | ||
| WIt is recommended that the names be chosen from the list of link:$$https://cfconventions.org/Data/cf-standard-names/docs/standardized-region-names.html$$[standardized region names] whenever possible. |
| However, a calendar year is not a well-defined unit of time, because it differs between leap years and other years, and among calendars. | ||
| Nonetheless for practical purposes we wish to compare statistics for months or seasons from different calendars, and to make climatologies from a mixture of leap years and other years. | ||
| Hence we provide special conventions for indicating dates within the climatological year. | ||
| Nonetheless for practical purposes it may be desirable to compare statistics for months or seasons from different calendars, and to make climatologies from a mixture of leap years and other years. |
Contributor
There was a problem hiding this comment.
or "there may be a need to compare"
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), we describe a general convention for anomalies over any type of coordinate, including details about how the norm was calculated. | ||
| In <<temporal-anomalies>>, we describe a legacy convention that depends on special standard names. | ||
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), a general convention for anomalies over any type of coordinate is described, including details about how the norm was calculated. | ||
| In <<temporal-anomalies>>, a legacy convention is described that depends on special standard names. |
Contributor
There was a problem hiding this comment.
The remainder of this section and the following two (<> and <>) describe a general convention for anomalies over any type of coordinate, including details about how the norm was calculated.
<> describes a legacy convention that depends on special standard names.
| The first time coordinate of __A__ is June 2023, and the first value of the auxiliary coordinate variable is 5, indicating that timestep 0 of __A__ (June 2023) is the anomaly with respect to the timestep 5 of __N__ (climatological June). | ||
|
|
||
| Since only June, July, and August climatological means are needed in this example, we could alternatively give the climatological time axis of __N__ a dimension of 3, with elements for those three months alone. | ||
| Since only June, July, and August climatological means are needed in this example, alternatively the climatological time axis of __N__ could be given a dimension of 3, with elements for those three months alone. |
Contributor
There was a problem hiding this comment.
I think it would read better as "example, the climatological time axis of N could alternatively be given"
| It indicates that **`delta_tas(0,:,:)`**, where **`:`** means the entire range of the dimension, is the difference between **`tas(0,:,:)`** and **`climatological_tas(5,:,:)`**. | ||
|
|
||
| If we chose instead to show the climatological time axis with only the three months needed in this example (June, July, and August), the following lines would replace the corresponding ones in the example above: | ||
| If instead the climatological time axis is shown with only the three months needed in this example (June, July, and August), the following lines would replace the corresponding ones in the example above: |
Contributor
There was a problem hiding this comment.
I suggest, "If instead the climatological time axis comprised only"
pvanlaake
commented
Feb 4, 2026
pvanlaake
commented
Feb 4, 2026
Contributor
Author
pvanlaake
left a comment
pvanlaake
left a comment
There was a problem hiding this comment.
Incorporated all suggestions made by Jonathan
| The extensions include metadata that provides a precise definition of each variable via specification of a standard name, describes the vertical locations corresponding to dimensionless vertical coordinate values, and provides the spatial coordinates of non-rectilinear gridded data. | ||
| Since climate and forecast data are often not simply representative of points in space/time, other extensions provide for the description of coordinate intervals, multidimensional cells and climatological time coordinates, and indicate how a data value is representative of an interval or cell. | ||
| This standard also relaxes the COARDS constraints on dimension order and specifies methods for reducing the size of datasets. | ||
| These conventions also relax the COARDS constraints on dimension order and specifies methods for reducing the size of datasets. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| These conventions also relax the COARDS constraints on dimension order and specifies methods for reducing the size of datasets. | |
| These conventions also relax the COARDS constraints on dimension order and specify methods for reducing the size of datasets. |
| Our main purpose therefore, is to propose a clear, adequate and flexible definition of the metadata needed for climate and forecast data. | ||
| Although this is specifically a netCDF standard, we feel that most of the ideas are of wider application. | ||
| These conventions are intended for use with climate and forecast data, for atmosphere, surface and ocean, and was designed with model-generated data particularly in mind. | ||
| It is recognised that there are limits to what a set of conventions can practically cover; these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. |
Contributor
Author
There was a problem hiding this comment.
This is a topic that would require a broader discussion. Perhaps open a separate issue on this?
| Our main purpose therefore, is to propose a clear, adequate and flexible definition of the metadata needed for climate and forecast data. | ||
| Although this is specifically a netCDF standard, we feel that most of the ideas are of wider application. | ||
| These conventions are intended for use with climate and forecast data, for atmosphere, surface and ocean, and was designed with model-generated data particularly in mind. | ||
| It is recognised that there are limits to what a set of conventions can practically cover; these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| It is recognised that there are limits to what a set of conventions can practically cover; these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. | |
| Recognising that there are limits to what a set of conventions can practically cover, these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. |
| These conventions are intended for use with climate and forecast data, for atmosphere, surface and ocean, and was designed with model-generated data particularly in mind. | ||
| It is recognised that there are limits to what a set of conventions can practically cover; these conventions are restricted to issues that are considered to be of common and frequent concern in the design of climate and forecast metadata. | ||
| The main purpose therefore, is to propose a clear, adequate and flexible definition of the metadata needed for climate and forecast data. | ||
| Although these conventions are specifically targeting the netCDF format, most of the ideas are of wider application. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| Although these conventions are specifically targeting the netCDF format, most of the ideas are of wider application. | |
| Although these are conventions for netCDF specifically, most of the ideas are of wider application. |
| Conversion of the metadata between files of different formats will be facilitated if conventions for all formats are based on similar ideas. | ||
|
|
||
| This convention is designed to be backward compatible with the COARDS conventions <<COARDS>>, by which we mean that a conforming COARDS dataset also conforms to the CF standard. | ||
| These conventions are designed to be backward compatible with the COARDS conventions <<COARDS>>, which implies that a conforming COARDS dataset also conforms to the CF conventions. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| These conventions are designed to be backward compatible with the COARDS conventions <<COARDS>>, which implies that a conforming COARDS dataset also conforms to the CF conventions. | |
| These conventions are designed to be backward compatible with the COARDS conventions <<COARDS>>, meaning that a conforming COARDS dataset also conforms to the CF conventions. |
| However, a calendar year is not a well-defined unit of time, because it differs between leap years and other years, and among calendars. | ||
| Nonetheless for practical purposes we wish to compare statistics for months or seasons from different calendars, and to make climatologies from a mixture of leap years and other years. | ||
| Hence we provide special conventions for indicating dates within the climatological year. | ||
| Nonetheless for practical purposes it may be desirable to compare statistics for months or seasons from different calendars, and to make climatologies from a mixture of leap years and other years. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| Nonetheless for practical purposes it may be desirable to compare statistics for months or seasons from different calendars, and to make climatologies from a mixture of leap years and other years. | |
| Nonetheless for practical purposes there may be a need to compare statistics for months or seasons from different calendars, and to make climatologies from a mixture of leap years and other years. |
| CF offers two conventions for describing anomaly data. | ||
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), we describe a general convention for anomalies over any type of coordinate, including details about how the norm was calculated. | ||
| In <<temporal-anomalies>>, we describe a legacy convention that depends on special standard names. | ||
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), a general convention for anomalies over any type of coordinate is described, including details about how the norm was calculated. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), a general convention for anomalies over any type of coordinate is described, including details about how the norm was calculated. | |
| The remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>) describe a general convention for anomalies over any type of coordinate, including details about how the norm was calculated. |
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), we describe a general convention for anomalies over any type of coordinate, including details about how the norm was calculated. | ||
| In <<temporal-anomalies>>, we describe a legacy convention that depends on special standard names. | ||
| In the remainder of this section and the following two (<<anomalies-norm-data>> and <<anomalies-norm-metadata>>), a general convention for anomalies over any type of coordinate is described, including details about how the norm was calculated. | ||
| In <<temporal-anomalies>>, a legacy convention is described that depends on special standard names. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| In <<temporal-anomalies>>, a legacy convention is described that depends on special standard names. | |
| <<temporal-anomalies>> describes a legacy convention that depends on special standard names. |
| The first time coordinate of __A__ is June 2023, and the first value of the auxiliary coordinate variable is 5, indicating that timestep 0 of __A__ (June 2023) is the anomaly with respect to the timestep 5 of __N__ (climatological June). | ||
|
|
||
| Since only June, July, and August climatological means are needed in this example, we could alternatively give the climatological time axis of __N__ a dimension of 3, with elements for those three months alone. | ||
| Since only June, July, and August climatological means are needed in this example, alternatively the climatological time axis of __N__ could be given a dimension of 3, with elements for those three months alone. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| Since only June, July, and August climatological means are needed in this example, alternatively the climatological time axis of __N__ could be given a dimension of 3, with elements for those three months alone. | |
| Since only June, July, and August climatological means are needed in this example, the climatological time axis of __N__ could alternatively be given a dimension of 3, with elements for those three months alone. |
| It indicates that **`delta_tas(0,:,:)`**, where **`:`** means the entire range of the dimension, is the difference between **`tas(0,:,:)`** and **`climatological_tas(5,:,:)`**. | ||
|
|
||
| If we chose instead to show the climatological time axis with only the three months needed in this example (June, July, and August), the following lines would replace the corresponding ones in the example above: | ||
| If instead the climatological time axis is shown with only the three months needed in this example (June, July, and August), the following lines would replace the corresponding ones in the example above: |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| If instead the climatological time axis is shown with only the three months needed in this example (June, July, and August), the following lines would replace the corresponding ones in the example above: | |
| If instead the climatological time axis comprised only the three months needed in this example (June, July, and August), the following lines would replace the corresponding ones in the example above: |
Contributor
Author
|
Dear Jonathan @JonathanGregory, Thank you for your careful read of the proposed changes and your suggestions. I have applied all your suggestions and they are now pending approval of my review. Patrick |
Contributor
|
Thanks, Patrick @pvanlaake. This looks fine to me. Should I do anything in GitHub? |
Contributor
Author
|
I suppose the next step would be to merge the PR in the main branch. But as per the rules for changing the conventions "at least three contributors have expressed support for it, including at least two members of the conventions committee". Counting yourself and myself as expressing support, the wait is for another conventions committee member to join the consensus. @ChrisBarker-NOAA are you ready to join the consensus? |
Contributor
|
Yes -- I confess I only gave it a quick once-over but it all looks good to me. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR contains changes to the conventions text to remedy two issues:
See issue #623 for discussion of these changes.
Release checklist
history.adocup to date?For maintainers
After the merge remember to delete the source branch.
Tags are set at the conclusion of the annual meeting; until then,
mainalways is a draft for the next version.