From e8a6dc5ea3119c48bdc07a538e9ef8ddc5636725 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20B=C3=A4rring?= Date: Thu, 14 Nov 2024 20:31:08 +0100 Subject: [PATCH] Harmonised links to NUG --- ch01.adoc | 12 ++++++------ ch02.adoc | 15 +++++++-------- ch03.adoc | 2 +- ch08.adoc | 4 ++-- 4 files changed, 16 insertions(+), 17 deletions(-) diff --git a/ch01.adoc b/ch01.adoc index e3cc269f..f9667645 100644 --- a/ch01.adoc +++ b/ch01.adoc @@ -59,7 +59,7 @@ Some of those definitions are repeated below for convenience. ancestor group:: A group from which the referring group is descended via direct parent-child relationships -auxiliary coordinate variable:: Any netCDF variable that contains coordinate data, but is not a coordinate variable (in the sense of that term defined by the NUG and used by this standard - see below). +auxiliary coordinate variable:: Any netCDF variable that contains coordinate data, but is not a coordinate variable (in the sense of that term defined by the <> and used by this standard - see below). Unlike coordinate variables, there is no relationship between the name of an auxiliary coordinate variable and the name(s) of its dimension(s). boundary variable:: A boundary variable is associated with a variable that contains coordinate data. @@ -131,18 +131,18 @@ vertical dimension:: A dimension of a netCDF variable that has an associated ver === Overview 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. +Instead we follow the lead of the <> and standardize only the names of attributes and some of the values taken by those attributes. Variable or dimension names can either be a single variable name or a path to a variable. The overview provided in this section will be followed with more complete descriptions in following sections. <> contains a summary of all the attributes used in this convention. -Files using this version of the CF Conventions must set the NUG defined attribute **`Conventions`** to contain the string value "**`CF-{current-version-as-attribute}`**" to identify datasets that conform to these conventions. +Files using this version of the CF Conventions must set the <> defined attribute **`Conventions`** to contain the string value "**`CF-{current-version-as-attribute}`**" to identify datasets that conform to these conventions. The general description of a file's contents should be contained in the following attributes: **`title`**, **`history`**, **`institution`**, **`source`**, **`comment`** and **`references`** (<>). For backwards compatibility with COARDS none of these attributes is required, but their use is recommended to provide human readable documentation of the file contents. Each variable in a netCDF file has an associated description which is provided by the attributes **`units`**, **`long_name`**, and **`standard_name`**. -The **`units`**, and **`long_name`** attributes are defined in the NUG and the **`standard_name`** attribute is defined in this document. +The **`units`**, and **`long_name`** attributes are defined in the <> and the **`standard_name`** attribute is defined in this document. The **`units`** attribute is required for all variables that represent dimensional quantities (except for boundary variables defined in <>). The values of the **`units`** attributes are character strings that are recognized by UNIDATA's UDUNITS package <> (with exceptions allowed as discussed in <>). @@ -157,7 +157,7 @@ Two independent parts of the convention allow this to be done. There are conventions that identify the variables that contain the coordinate data, and there are conventions that identify the type of coordinate represented by that data. There are two methods used to identify variables that contain coordinate data. -The first is to use the NUG-defined "coordinate variables." +The first is to use the <>-defined "coordinate variables." __The use of coordinate variables is required for all dimensions that correspond to one dimensional space or time coordinates__. In cases where coordinate variables are not applicable, the variables containing coordinate data are identified by the **`coordinates`** attribute. @@ -179,7 +179,7 @@ An important application of this attribute is to describe climatological and diu Methods for reducing the total volume of data include both packing and compression. Packing reduces the data volume by reducing the precision of the stored numbers. -It is implemented using the attributes **`add_offset`** and **`scale_factor`** which are defined in the NUG. +It is implemented using the attributes **`add_offset`** and **`scale_factor`** which are defined in the <>. Compression on the other hand loses no precision, but reduces the volume by not storing missing data. The attribute **`compress`** is defined for this purpose. diff --git a/ch02.adoc b/ch02.adoc index a0e569bf..ad616b66 100644 --- a/ch02.adoc +++ b/ch02.adoc @@ -1,6 +1,6 @@ == NetCDF Files and Components -The components of a netCDF file are described in section 2 of the NUG <>. +The components of a netCDF file are described in section 2 of the <>. In this section we describe conventions associated with filenames and the basic components of a netCDF file. We also introduce new attributes for describing the contents of a file. @@ -15,7 +15,7 @@ Data variables must be one of the following data types: **`string`**, **`char`** 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`** 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. +It is possible to treat the **`byte`** and **`short`** types as unsigned by using the <> 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 phrase "integer type" is used in this document, it should be understood to mean **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**, **`int`**, **`unsigned int`**, **`int64`**, or **`unsigned int64`**. @@ -50,7 +50,7 @@ It is recommended that variable, dimension, attribute and group names begin with By the word _letters_ we mean the standard ASCII letters uppercase `A` to `Z` and lowercase `a` to `z`. By the word _digits_ we mean the standard ASCII digits `0` to `9`, and similarly _underscores_ means the standard ASCII underscore `_`. Note that this is in conformance with the COARDS conventions, but is more restrictive than the netCDF interface which allows almost all Unicode characters encoded as multibyte UTF-8 characters (link:$$https://docs.unidata.ucar.edu/nug/current/file_format_specifications.html$$[NUG Appendix B]). -The netCDF interface also allows leading underscores in names, but the NUG states that this is reserved for system use. +The netCDF interface also allows leading underscores in names, but the <> states that this is reserved for system use. ASCII period (.) and ASCII hyphen (-) are also allowed in attribute names only. Case is significant in netCDF names, but it is recommended that names should not be distinguished purely by case, i.e., if case is disregarded, no two names should be the same. @@ -92,8 +92,7 @@ NetCDF variables that contain coordinate data are referred to as __coordinate va [[missing-data, Section 2.5.1, "Missing data, valid and actual range of data"]] ==== Missing data, valid and actual range of data -The NUG conventions -(link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, Attribute Conventions]) +link:$$https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, Attribute Conventions] provide the **`_FillValue`**, **`missing_value`**, **`valid_min`**, **`valid_max`**, and **`valid_range`** attributes to indicate missing data. Missing data is allowed in data variables and auxiliary coordinate variables. Generic applications should treat the data as missing where any auxiliary coordinate variables have missing values; special-purpose applications might be able to make use of the data. @@ -139,7 +138,7 @@ See <> for a list of attributes described by this standard. [[identification-of-conventions]] ==== Identification of Conventions -Files that follow this version of the CF Conventions must indicate this by setting the NUG defined global attribute **`Conventions`** to a string value that contains "**`CF-{current-version-as-attribute}`**". +Files that follow this version of the CF Conventions must indicate this by setting the <> defined global attribute **`Conventions`** to a string value that contains "**`CF-{current-version-as-attribute}`**". The Conventions version number contained in that string can be used to find the web based versions of this document are from the link:$$https://cfconventions.org/$$[netCDF Conventions web page]. Subsequent versions of the CF Conventions will not make invalid a compliant usage of this or earlier versions of the CF terms and forms. @@ -162,7 +161,7 @@ The attribute values are all character strings. For readability in ncdump outputs it is recommended to embed newline characters into long strings to break them into lines. For backwards compatibility with COARDS none of these global attributes is required. -The NUG defines **`title`** and **`history`** to be global attributes. +The <> defines **`title`** and **`history`** to be global attributes. We wish to allow the newly defined attributes, i.e., **`institution`**, **`source`**, **`references`**, and **`comment`**, to be either global or assigned to individual variables. When an attribute appears both globally and as a variable attribute, the variable's version has precedence. @@ -236,7 +235,7 @@ A special case exists for coordinate variables. Because coordinate variables must share dimensions with the variables that reference them, the ancestor search is executed only until the local apex group is reached. For coordinate variables that are not found in the referring group or its ancestors, a further strategy is provided, called lateral search. The lateral search proceeds downwards from the local apex group width-wise through each level of groups until the sought coordinate is found. -The lateral search algorithm may only be used for NUG coordinate variables; it shall not be used for auxiliary coordinate variables. +The lateral search algorithm may only be used for <> coordinate variables; it shall not be used for auxiliary coordinate variables. [NOTE] ==== diff --git a/ch03.adoc b/ch03.adoc index abcf2fcf..91cb8641 100644 --- a/ch03.adoc +++ b/ch03.adoc @@ -148,7 +148,7 @@ If a variable has no **`long_name`** attribute then an application may use, as a === Standard Name A fundamental requirement for exchange of scientific data is the ability to describe precisely the physical quantities being represented. -To some extent this is the role of the **`long_name`** attribute as defined in the NUG. +To some extent this is the role of the **`long_name`** attribute as defined in the <>. However, usage of **`long_name`** is completely ad-hoc. For many applications it is desirable to have a more definitive description of the quantity, which allows users of data from different sources (some of which might be models and others observational) to determine whether quantities are in fact comparable. For this reason each variable may optionally be given a "standard name", whose meaning is defined by this convention. diff --git a/ch08.adoc b/ch08.adoc index ab5b2611..9d5946bc 100644 --- a/ch08.adoc +++ b/ch08.adoc @@ -17,13 +17,13 @@ The disadvantage is that generic utilities that don't recognize the CF conventio === Packed Data At the current time the netCDF interface does not provide for packing data. -However a simple packing may be achieved through the use of the optional NUG <> defined attributes **`scale_factor`** and **`add_offset`**. +However a simple packing may be achieved through the use of the optional <> defined attributes **`scale_factor`** and **`add_offset`**. After the data values of a variable have been read, they are to be multiplied by the **`scale_factor`**, and have **`add_offset`** added to them. If both attributes are present, the data are scaled before the offset is added. When scaled data are written, the application should first subtract the offset and then divide by the scale factor. The units of a variable should be representative of the unpacked data. -This standard is more restrictive than the NUG with respect to the use of the **`scale_factor`** and **`add_offset`** attributes; ambiguities and precision problems related to data type conversions are resolved by these restrictions. +This standard is more restrictive than the <> with respect to the use of the **`scale_factor`** and **`add_offset`** attributes; ambiguities and precision problems related to data type conversions are resolved by these restrictions. When packed data is written, the **`scale_factor`** and **`add_offset`** attributes must be of the same type as the unpacked data, which must be either **`float`** or **`double`**. Data of type **`float`** must be packed into one of these types: **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**. Data of type **`double`** must be packed into one of these types: **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**, **`int`**, **`unsigned int`**.