diff --git a/doc/user-guide/io.rst b/doc/user-guide/io.rst index b73d0fdcb51..fd6b7708e48 100644 --- a/doc/user-guide/io.rst +++ b/doc/user-guide/io.rst @@ -416,7 +416,8 @@ read the data. Scaling and type conversions ............................ -These encoding options work on any version of the netCDF file format: +These encoding options (based on `CF Conventions on packed data`_) work on any +version of the netCDF file format: - ``dtype``: Any valid NumPy dtype or string convertible to a dtype, e.g., ``'int16'`` or ``'float32'``. This controls the type of the data written on disk. @@ -427,7 +428,8 @@ These encoding options work on any version of the netCDF file format: output file, unless explicitly disabled with an encoding ``{'_FillValue': None}``. - ``scale_factor`` and ``add_offset``: Used to convert from encoded data on disk to to the decoded data in memory, according to the formula - ``decoded = scale_factor * encoded + add_offset``. + ``decoded = scale_factor * encoded + add_offset``. Please note that ``scale_factor`` + and ``add_offset`` must be of same type and determine the type of the decoded data. These parameters can be fruitfully combined to compress discretized data on disk. For example, to save the variable ``foo`` with a precision of 0.1 in 16-bit integers while @@ -435,6 +437,8 @@ converting ``NaN`` to ``-9999``, we would use ``encoding={'foo': {'dtype': 'int16', 'scale_factor': 0.1, '_FillValue': -9999}}``. Compression and decompression with such discretization is extremely fast. +.. _CF Conventions on packed data: https://cfconventions.org/cf-conventions/cf-conventions.html#packed-data + .. _io.string-encoding: String encoding diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 6a97ceaff00..6e07caedc5a 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -44,6 +44,8 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Add link to CF Conventions on packed data and sentence on type determination in doc/user-guide/io.rst (:issue:`9041`, :pull:`9045`). + By `Kai Mühlbauer `_. Internal Changes