Sets up the use of the scale-offset filter

##### Procedure:

H5P_SET_SCALEOFFSET ( plist_id, scale_type,scale_factor )

##### Signature:

```
herr_t H5Pset_scaleoffset(
hid_t plist_id,
H5Z_SO_scale_type_t scale_type,
int scale_factor
)
```

```
Fortran90 Interface: h5pset_scaleoffset_f
Signature:
SUBROUTINE h5pset_scaleoffset_f(plist_id, scale_type, scale_factor, hdferr)
INTEGER(HID_T), INTENT(IN) :: plist_id
INTEGER , INTENT(IN) :: scale_type
INTEGER , INTENT(IN) :: scale_factor
INTEGER , INTENT(OUT) :: hdferr
Inputs:
plist_id - Dataset creation property list identifier.
scale_type - Flag indicating compression method. Valid values:
H5Z_SO_FLOAT_DSCALE_F
H5Z_SO_FLOAT_ESCALE_F
H5Z_SO_INT_F
scale_factor - Parameter related to scale.
Outputs:
hdferr - Returns 0 if successful and -1 if fails
```

##### Parameters:

*hid_t* `plist_id` | IN: Dataset creation property list identifier |

*H5Z_SO_scale_type_t* `scale_type ` | IN: Flag indicating compression method |

*int* `scale_factor` | IN: Parameter related to scale. Must be non-negative |

##### Description:

H5P_SET_SCALEOFFSET sets the scale-offset filter, `H5Z_FILTER_SCALEOFFSET`

, for a dataset.

Generally speaking, scale-offset compression performs a scale and/or offset operation on each data value and truncates the resulting value to a minimum number of bits (MinBits) before storing it. The current scale-offset filter supports integer and floating-point datatypes.

For an integer datatype, the parameter `scale_type`

should be set to `H5Z_SO_INT (2)`

. The parameter `scale_factor`

denotes MinBits. If the user sets it to `H5Z_SO_INT_MINBITS_DEFAULT (0)`

, the filter will calculate MinBits. If `scale_factor`

is set to a positive integer, the filter does not do any calculation and just uses the number as MinBits. However, if the user gives a MinBits that is less than what would be generated by the filter, the compression will be lossy. Also, the MinBits supplied by the user cannot exceed the number of bits to store one value of the dataset datatype.

For a floating-point datatype, the filter adopts the GRiB data packing mechanism, which offers two alternate methods: E-scaling and D-scaling. Both methods are lossy compression. If the parameter `scale_type`

is set to `H5Z_SO_FLOAT_DSCALE (0)`

, the filter will use the D-scaling method; if it is set to `H5Z_SO_FLOAT_ESCALE (1)`

, the filter will use the E-scaling method. Since only the D-scaling method is implemented, `scale_type`

should be set to `H5Z_SO_FLOAT_DSCALE`

or 0.

When the D-scaling method is used, the original data is "D" scaled — multiplied by 10 to the power of `scale_factor`

, and the "significant" part of the value is moved to the left of the decimal point. Care should be taken in setting the decimal `scale_factor`

so that the integer part will have enough precision to contain the appropriate information of the data value. For example, if `scale_factor`

is set to 2, the number 104.561 will be 10456.1 after "D" scaling. The last digit 1 is not "significant" and is thrown off in the process of rounding. The user should make sure that after "D" scaling and rounding, the data values are within the range that can be represented by the integer (same size as the floating-point type).

Valid values for `scale_type`

are as follows:

`H5Z_SO_FLOAT_DSCALE (0)` | Floating-point type, using variable MinBits method |

`H5Z_SO_FLOAT_ESCALE (1)` | Floating-point type, using fixed MinBits method |

`H5Z_SO_INT (2)` | Integer type |

The meaning of `scale_factor`

varies according to the value assigned to `scale_type`

:

`scale_type` value | `scale_factor` description |
---|

`H5Z_SO_FLOAT_DSCALE` | Denotes the decimal scale factor for D-scaling and can be positive, negative or zero. This is the current implementation of the library. |

`H5Z_SO_FLOAT_ESCALE` | Denotes MinBits for E-scaling and must be a positive integer. This is not currently implemented by the library. |

`H5Z_SO_INT` | Denotes MinBits and it should be a positive integer or `H5Z_SO_INT_MINBITS_DEFAULT (0).` If it is less than 0, the library will reset it to 0 since it is not implemented. |

Like other I/O filters supported by the HDF5 library, an application using the scale-offset filter must store data with chunked storage.

##### Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

##### Example:

##### History:

**Release** | **Change** |
---|

1.8.8 | Fortran90 subroutine introduced in this release. |

1.8.0 | C function introduced in this release. |

--- Last Modified: July 19, 2019 | 10:23 AM