# dsp.StateLevels

State-level estimation for bilevel rectangular waveform

## Description

The `dsp.StateLevels` object estimates the state levels of a bilevel rectangular waveform.

To estimate the state levels of a bilevel waveform:

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

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

## Creation

### Syntax

``sl = dsp.StateLevels``
``sl = dsp.StateLevels(Name,Value)``

### Description

example

````sl = dsp.StateLevels` creates a state-level estimation System object™, `sl`, that estimates state levels in a bilevel rectangular waveform using the histogram method with 100 bins.```
````sl = dsp.StateLevels(Name,Value)` returns a `StateLevels` System object, `sl`, 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.

Minimum and maximum levels of the histogram. Specify the range of the histogram as a two-element real-valued row vector. Signal values outside the range defined by this property are ignored.

#### Dependencies

This property applies when you set the `Method` property to `'Histogram mode'` or `'Histogram mean'`, and either `RunningStateLevels` is `true`, or the `HistogramBoundsSource` property is set to `'Property'`.

Data Types: `double`

Source of histogram bounds. Specify how to determine the histogram bounds as one of `'Auto'` or `'Property'`. When you set this property to `'Auto'`, the histogram bounds are determined by the minimum and maximum input values. When you set this property to `'Property'`, the histogram bounds are determined by the value of the `HistogramBounds` property.

#### Dependencies

This property applies when you set the `Method` property to `'Histogram mode'` or `'Histogram mean'`, and the `RunningStateLevels` property is `false`.

Number of bins in the histogram. Specify the number of bins in the histogram.

#### Dependencies

This property applies when you set the `Method` property to `'Histogram mode'` or `'Histogram mean'`.

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

Enable histogram output. Set this property to `true` to output the histogram used in the computation of the state levels.

#### Dependencies

This property applies when you set the `Method` property to `'Histogram mode'` or `'Histogram mean'`.

Algorithm used to compute state levels. Specify the method used to compute state levels as one of `'Histogram mean'`, ```'Histogram mode'```, or `'Peak to peak'`.

Calculation over successive calls to the algorithm. Set this property to `true` to enable computation of the state levels over successive calls to the algorithm. Otherwise, the object computes the state levels of only the current input. When you set the `RunningStateLevels` property to `false` and you are using a histogram to compute your state levels, you must set the `HistogramBoundsSource` property to `'Property'`.

## Usage

### Syntax

``levels = sl(x)``
``[levels,histogram] = sl(x)``

### Description

example

````levels = sl(x)` returns a two-element row vector, `levels`, containing the estimated state levels for the input, `x`.```
``` `[levels,histogram] = sl(x)` returns a double-precision column vector, `histogram`, containing the histogram of the sample values in `x`. You can obtain this output only when you set the `Method` property to either ```'Histogram mean'``` or `'Histogram mode'`, and you set the `HistogramOutputPort` property to `true`.```

### Input Arguments

expand all

Input data, specified as a real-valued column vector.

Data Types: `double`

### Output Arguments

expand all

State levels, returned as a two-element row vector.

Data Types: `double`

## 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

 `plot` Plot signal, state levels, and histogram
 `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

collapse all

Compute and plot the state levels of a 2.3 V underdamped noisy clock. Load the clock data in the variable, `x`, and the sampling instants in the variable `t`.

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

`load('clockex.mat','x','t');`

Estimate the state levels.

```sl = dsp.StateLevels; levels = sl(x);```

Plot the clock data along with the estimated state levels and histograms.

`plot(sl)`

expand all

## Algorithms

The `dsp.StateLevels` System object uses the histogram method to estimate the states of a bilevel waveform. The histogram method is described in [1]. To summarize the method:

1. Determine the maximum and minimum amplitudes and amplitude range of the data.

2. For the specified number of histogram bins, determine the bin width as the ratio of the amplitude range to the number of bins.

3. Sort the data values into the histogram bins.

4. Identify the lowest-indexed histogram bin, ilow, and highest-indexed histogram bin, ihigh, with nonzero counts.

5. Divide the histogram into two subhistograms. The lower-histogram bins are ilowi ≤ 1/2(ihighilow).

The upper-histogram bins are ilow + 1/2(ihighilow) ≤ iihigh.

6. Compute the state levels by determining the mode or mean of the lower and upper histograms.

## References

[1] IEEE® Standard on Transitions, Pulses, and Related Waveforms, IEEE Standard 181, 2003, pp. 15–17.