Documentation

# dsp.ScalarQuantizerEncoder

Associate input value with index value of quantization region

## Description

The `dsp.ScalarQuantizerEncoder` object encodes each input value by associating that value with the index value of the quantization region. Then, the object outputs the index of the associated region.

To encode an input value by associating it with an index value of the quantization region:

1. Create the `dsp.ScalarQuantizerEncoder` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``sqenc = dsp.ScalarQuantizerEncoder``
``sqenc = dsp.ScalarQuantizerEncoder(Name,Value)``

### Description

example

````sqenc = dsp.ScalarQuantizerEncoder` returns a scalar quantizer encoder System object™, `sqenc`. This object maps each input value to a quantization region by comparing the input value to the user-specified boundary points.```
````sqenc = dsp.ScalarQuantizerEncoder(Name,Value)` returns a scalar quantizer encoder object, `sqenc`, with each specified property set to the specified value.```

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

Specify how to determine the boundary points and codebook values as `'Property'` or `'Input port'`.

Specify the quantizer as `'Bounded'` or `'Unbounded'`.

Specify the boundary points of quantizer regions as a vector. The vector values must be in ascending order. Let `[p0 p1 p2 p3 ... pN]` denote the boundary points property in the quantizer. If the quantizer is bounded, the object uses this property to specify `[p0 p1 p2 p3 ... pN]`. If the quantizer is unbounded, the object uses this property to specify ```[p1 p2 p3 ... p(N-1)]``` and sets `p0 = -Inf` and ```pN = +Inf```.

Tunable: Yes

#### Dependencies

This property applies when you set the `BoundaryPointsSource` property to `Property`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Specify whether to find the appropriate quantizer index using a linear search or a binary search as one of `'Linear'` or `'Binary'`. The computational cost of the linear search method is of the order P and the computational cost of the binary search method is of the order

`${\text{log}}_{\text{2}}\text{(}P\text{)}$`

where P is the number of boundary points.

Specify whether the input value is assigned to the lower indexed region or higher indexed region when the input value equals boundary point by selecting ```'Choose the lower index'``` or `'Choose the higher index'`.

Set this property to `true` to output the codeword values that correspond to each index value.

Set this property to `true` to output the quantization error for each input value. The quantization error is the difference between the input value and the quantized output value.

Specify the codebook as a vector of quantized output values that correspond to each region. If the `Partitioning` property is `'Bounded'` and the boundary points vector has length N, you must set this property to a vector of length N-1. If the `Partitioning` property is `'Unbounded'` and the boundary points vector has length N, you must set this property to a vector of length N+1.

Tunable: Yes

#### Dependencies

This property applies when you set the `BoundaryPointsSource` property to `'Property'` and either the `CodewordOutputPort` property or the `QuantizationErrorOutputPort` property is `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Set this property to `true` to output the clipping status. The output is a 1 when an input value is outside the range defined by the `BoundaryPoints` property. When the value is inside the range, the exception output is a 0.

#### Dependencies

This property applies when you set the `Partitioning` property to `'Bounded'`.

Specify the data type of the index output from the object as: `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`.

### Fixed-Point Properties

Specify the rounding method.

Specify the overflow action.

## Usage

### Syntax

``index = sqenc(input)``
``[index] = sqenc(input,bpoints)``
``[index] = sqenc(input,bpoints,cBook)``
``[index,codeword] = sqenc(___)``
``[___,qerr] = sqenc(___)``
``[___,cStatus] = sqenc(___)``

### Description

example

````index = sqenc(input)` returns the `index` of the quantization region to which the `input` belongs. The input data, boundary points, codebook values, quantized output values, and the quantization error must have the same data type whenever they are present.```
````[index] = sqenc(input,bpoints)` uses input `bpoints` as the boundary points when the `BoundaryPointsSource` property is ```Input port```.```
````[index] = sqenc(input,bpoints,cBook)` uses input `bpoints` as the boundary points and input `cBook` as the codebook when the `BoundaryPointsSource` property is `'Input port'` and either the `CodewordOutputPort` property or the `QuantizationErrorOutputPort` property is `true`.```
````[index,codeword] = sqenc(___)` outputs the `codeword` values that corresponds to each index value when the `CodewordOutputPort` property is `true`.```
````[___,qerr] = sqenc(___)` outputs the quantization error `qerr` for each input value when the `QuantizationErrorOutputPort` property is `true`.```
````[___,cStatus] = sqenc(___)` also returns output `cStatus` as the clipping status output port for each input value when the `Partitioning` property is `'Bounded'` and the `ClippingStatusOutputPort` property is `true`. If an input value is outside the range defined by the `BoundaryPoints` property, `cStatus` is `true`. If an input value is inside the range, `cStatus` is `false`.```

### Input Arguments

expand all

Input data, specified as a vector or a matrix. If the input is fixed point, it must be signed fixed point with power-of-two slope and zero bias.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `fi`

Boundary points of the quantizer regions, specified as a vector. The vector values must be in ascending order. Let `[p0 p1 p2 p3 ... pN]` denote the boundary points in the quantizer. If the quantizer is bounded, the object uses this input to specify `[p0 p1 p2 p3 ... pN]`. If the quantizer is unbounded, the object uses this input to specify ```[p1 p2 p3 ... p(N-1)]``` and sets `p0 = -Inf` and ```pN = +Inf```.

#### Dependencies

This input applies when you set the `BoundaryPointsSource` property to `Input port`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Codebook, specified as a vector of quantized output values that correspond to each region. If the `Partitioning` property is `'Bounded'` and the boundary points vector has length N, this input must be a vector of length N-1. If the `Partitioning` property is `'Unbounded'` and the boundary points vector has length N, this input must be a vector of length N+1.

#### Dependencies

This input applies when you set the `BoundaryPointsSource` property is `'Input port'` and either the `CodewordOutputPort` property or the `QuantizationErrorOutputPort` property is `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

### Output Arguments

expand all

Index of the quantization region to which the `input` belongs, returned as a vector or a matrix of the same size as the `input`.

Data Types: `int32`

Codeword values that correspond to each index value, returned as a vector or a matrix of the same size as the `input`.

#### Dependencies

This output is available when the `CodewordOutputPort` property is set to `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `fi`

Quantization error for each input value, returned as a vector or a matrix of the same size as the `input`.

#### Dependencies

This output is available when the `QuantizationErrorOutputPort` property is set to `true`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `fi`

Clipping status for each input value, returned as a vector or a matrix. If an input value is outside the range defined by the `BoundaryPoints` property, `cStatus` is `true`. If an input value is inside the range, `cStatus` is `false`.

#### Dependencies

This output is available when the `Partitioning` property is `'Bounded'` and the `ClippingStatusOutputPort` property is set to `true`.

Data Types: `logical`

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

## Examples

expand all

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent `step` syntax. For example, `obj(x)` becomes `step(obj,x)`.

Quantize the varying fractional inputs between zero and five to the closest integers, and then plot the results.

```sqenc = dsp.ScalarQuantizerEncoder; sqenc.BoundaryPoints = [-.001 .499 1.499 ... 2.499 3.499 4.499 5.001]; sqenc.CodewordOutputPort = true; sqenc.Codebook = [0 1 2 3 4 5]; input = (0:0.02:5)'; [index, quantizedValue] = sqenc(input); plot(1:length(input), [input quantizedValue]);```

## Algorithms

This object implements the algorithm, inputs, and outputs described on the Scalar Quantizer Encoder block reference page. The object properties correspond to the block parameters.