# dsp.Autocorrelator

Autocorrelation sequence

## Description

The `Autocorrelator` object returns the autocorrelation sequence for a discrete-time, deterministic input, or the autocorrelation sequence estimate for a discrete-time, wide-sense stationary (WSS) random process at positive lags.

To obtain the autocorrelation sequence:

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

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

## Creation

### Syntax

``ac = dsp.Autocorrelator``
``ac = dsp.Autocorrelator(Name,Value)``

### Description

example

````ac = dsp.Autocorrelator` returns an autocorrelator, `ac`, that computes the autocorrelation along the first dimension of an N-D array. By default, the autocorrelator computes the autocorrelation at lags from zero to N – 1, where N is the length of the input vector or the row dimension of the input matrix. Inputting a row vector results in a row of zero-lag autocorrelation sequence values, one for each column of the row vector. The default autocorrelator returns the unscaled autocorrelation and performs the computation in the time domain.```

example

````ac = dsp.Autocorrelator(Name,Value)` returns an autocorrelator, `ac`, with each 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 range of lags for the autocorrelation as `Auto` or `Property`. If the value of `MaximumLagSource` is `Auto`, the autocorrelator computes the autocorrelation over all nonnegative lags in the interval `[0, N-1]`, where N is the length of the first dimension of the input. Otherwise, the object computes the autocorrelation using lags in the range `[0,MaximumLag]`.

Specify the maximum lag as an integer greater than or equal to 0. The `MaximumLag` must be less than the length of the input data.

#### Dependencies

This property applies only when the `MaximumLagSource` property is `Property`.

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

Specify the scaling to apply to the output as `None`, `Biased`, `Unbiased`, or ```Unity at zero-lag```. Set this property to `None` to generate the autocorrelation function without scaling. This option is appropriate if you are computing the autocorrelation of a nonrandom (deterministic) input.

The `Biased` option scales the autocorrelation by 1/N, where N is the length of the input data. Scaling by 1/N yields a biased, finite-sample approximation to the theoretical autocorrelation of a WSS random process. In spite of the bias, scaling by 1/N has the desirable property that the sample autocorrelation matrix is nonnegative definite, a property possessed by the theoretical autocorrelation matrices of all wide-sense stationary random processes. The Fourier transform of the biased autocorrelation estimate is the periodogram, a widely used estimate of the power spectral density of a WSS process.

The `Unbiased` option scales the estimate of the autocorrelation by 1/N – 1. Scaling by N – 1 produces an unbiased estimate of the theoretical autocorrelation. However, using the unbiased option, you can obtain an estimate of the autocorrelation function that fails to have the nonnegative definite property.

Use the `Unity at zero-lag` option to normalize the autocorrelation estimate as identically one at lag zero. The default is `None`.

Specify the domain for computing autocorrelations as `Time Domain` or `Frequency Domain`. You must set this property to ```Time Domain``` for fixed-point signals.

### Fixed-Point Properties

Specify whether to use full precision rules. If you set `FullPrecisionOverride` to `true`, which is the default, the object computes all internal arithmetic and output data types using full precision rules. These rules provide the most accurate fixed-point numerics. It also turns off the display of other fixed-point properties because they do not apply individually. These rules guarantee that no quantization occurs within the object. Bits are added, as needed, to ensure that no roundoff or overflow occurs. If you set `FullPrecisionOverride` to `false`, fixed-point data types are controlled through individual fixed-point property settings. For more information, see Full Precision for Fixed-Point System Objects.

Specify the rounding method as `Ceiling`, `Convergent`, `Floor`, `Nearest`, `Round`, `Simplest`, or `Zero`.

#### Dependencies

This property applies only when you set the `Method` property to `Time Domain` and the object is not in full precision mode.

Specify the overflow action as `Wrap` or `Saturate`.

#### Dependencies

This property applies only when you set the `Method` property to `Time Domain` and the object is not in full precision mode.

Specify the product fixed-point data type as one of ```Full precision```, `Same as input`, or `Custom`.

#### Dependencies

This property applies only when you set the `Method` property to `Time Domain`.

Specify the product fixed-point type as a scaled `numerictype` (Fixed-Point Designer) object with a `Signedness` of `Auto`.

#### Dependencies

This property applies only when you set the `Method` property to `Time Domain` and the `ProductDataType` property to `Custom`.

Specify the accumulator fixed-point data type as one of ```Full precision```, `Same as product`, ```Same as input```, or `Custom`.

#### Dependencies

This property applies only when the `Method` property is `Time Domain`.

Specify the accumulator fixed-point type as a scaled `numerictype` (Fixed-Point Designer) object with a `Signedness` of `Auto`.

#### Dependencies

This property applies only when you set the `Method` property to `Time Domain` and the `AccumulatorDataType` property to `Custom`.

Specify the output fixed-point data type as ```Same as accumulator```, `Same as product`, ```Same as input```, or `Custom`.

#### Dependencies

This property applies only when the `Method` property is `Time Domain`.

Specify the output fixed-point type as a scaled `numerictype` (Fixed-Point Designer) object with a `Signedness` of `Auto`.

#### Dependencies

This property applies only when you set the `Method` property to `Time Domain` and the `OutputDataType` property to `Custom`.

## Usage

### Syntax

``y = ac(x)``

### Description

example

````y = ac(x)` computes the autocorrelation sequence `y` for the columns of the input `x`.```

### Input Arguments

expand all

Data input, specified as a vector, matrix, or an N-D array. The object accepts real-valued or complex-valued multichannel and multidimensional inputs. The input can be a fixed-point signal when you set the `Method` property to `'Time Domain'`. When the input signal is complex, the output signal is complex.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `fi`
Complex Number Support: Yes

### Output Arguments

expand all

Autocorrelated output of the two input signals. The size, data type, and complexity of the output matches that of the input signal.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `fi`
Complex Number Support: Yes

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

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

```ac1 = dsp.Autocorrelator; % x is a column vector x = (1:100)'; y = ac1(x);```

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

Compute the autocorrelation of a sine wave in white Gaussian noise with approximate 95% upper and lower confidence limits.

```S = rng('default'); % Sine wave with period N=4 x = 1.4*cos(pi/2*(1:100))'+randn(100,1); MaxLag = 20; ac = dsp.Autocorrelator('MaximumLagSource',... 'Property','MaximumLag',MaxLag,'Scaling','Unity at zero-lag'); SigAutocorr = ac(x); stem(SigAutocorr,'b','markerfacecolor',[0 0 1]); line(1:MaxLag+1,1.96/sqrt(100)*ones(MaxLag+1,1),... 'linestyle','-.','linewidth',2); line(1:MaxLag+1,-1.96/sqrt(100)*ones(MaxLag+1,1),... 'linestyle','-.','linewidth',2); axis([1 20 -1 1]); title('Sine Wave + Noise Autocorrelation'); xlabel('Lag');```

As this figure shows, the autocorrelation estimate demonstrates the four sample periodic sine wave with excursions outside the 95% white Gaussian noise confidence limits every two samples.

expand all

expand all