Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify rules for packing and unpacking in Section 8.1 #456

Merged
merged 4 commits into from
Sep 18, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions ch08.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,10 @@ When scaled data are written, the application should first subtract the offset a
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.
If the **`scale_factor`** and **`add_offset`** attributes are of the same data type as the associated variable, the unpacked data is assumed to be of the same data type as the packed data.
However, if the **`scale_factor`** and **`add_offset`** attributes are of a different data type from the variable (containing the packed data) then the unpacked data should match the type of these attributes, which must both be of type **`float`** or both be of type **`double`**.
An additional restriction in this case is that the variable containing the packed data must be of type **`byte`**, **`short`** or **`int`**.
It is not advised to unpack an **`int`** into a **`float`** as there is a potential precision loss.

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`**.

When packed data is read, it should be unpacked to the type of the **`scale_factor`** and **`add_offset`** attributes, which must have the same type if both are present. For guidance only, we suggest that packed data which does not conform to the rules of this section regarding the types of the data variable and attributes should be unpacked to **`double`** type, in order to minimise the risk of loss of precision.

When data to be packed contains missing values the attributes that indicate missing values (**`_FillValue`**, **`valid_min`**, **`valid_max`**, **`valid_range`**) must be of the same data type as the packed data.
See <<missing-data>> for a discussion of how applications should treat variables that have attributes indicating both missing values and transformations defined by a scale and/or offset.
Expand Down
10 changes: 3 additions & 7 deletions conformance.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -483,13 +483,9 @@ The specified variable must be a node coordinate variable that exists in the fil

*Requirements:*

* The **`scale_factor`** and **`add_offset`** attributes must be the same numeric data type.
* If **`scale_factor`** and **`add_offset`** are a different type than the variable, then they must be either type float or type double.
* If **`scale_factor`** and **`add_offset`** are a different type than the variable, then the variable must be type byte, short or int.

*Recommendations:*

* If **`scale_factor`** and **`add_offset`** are type float, the variable should not be of type int.
* The **`scale_factor`** and **`add_offset`** attributes must be either type **`float`** or type **`double`**, and if both are present they must be the same type.
* If the **`scale_factor`** and **`add_offset`** are type **`float`**, the data variable must be one of these types: **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**.
* If the **`scale_factor`** and **`add_offset`** are type **`double`**, the data variable must be one of these types: **`byte`**, **`unsigned byte`**, **`short`**, **`unsigned short`**, **`int`**, **`unsigned int`**.

[[section-22]]

Expand Down
1 change: 1 addition & 0 deletions history.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@

=== Working version (most recent first)

* {issues}374[Issue #374]: Clarify rules for packing and unpacking in Section 8.1
* {issues}449[Issue #449]: Typo in end-date in Example 7.12
* {issues}266[Issue #266]: Updates to some links in the bibliography
* {issues}286[Issue #286]: Some labels of examples contain "Example" so that their label in the list of examples contains "Example" (affects four examples); corrected captions of three tables and five examples
Expand Down
Loading