dsp.PhaseExtractor System object

Extract the unwrapped phase of a complex input

Description

The dsp.PhaseExtractor System object™ extracts the unwrapped phase of a real or a complex input.

To extract the unwrapped phase of a signal input:

1. Create the dsp.PhaseExtractor object and set its properties.

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

To learn more about how System objects work, see What Are System Objects? (MATLAB).

Creation

Syntax

phase = dsp.PhaseExtractor

phase = dsp.PhaseExtractor(Name,Value)

Description

phase = dsp.PhaseExtractor returns a phase extractor System object that extracts the unwrapped phase of an input signal.

phase = dsp.PhaseExtractor(Name,Value) returns a phase extractor System object with the specified property name set to the specified value.

Properties

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.

For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).

TreatFramesIndependently — Unwrap phase only within the frame

false (default) | true

Specify if the phase is to be unwrapped only within the frame, as a logical scalar.

When you set this property to:

• false –– The object returns the unwrapped phase while ignoring boundaries between input frames.

• true –– The object treats each frame of input data independently, and resets the initial cumulative unwrapped phase value to zero each time a new input frame is received.

Usage

For versions earlier than R2016b, use the step function to run the System object algorithm. The arguments to step are the object you created, followed by the arguments shown in this section.

For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

Syntax

p = phase(input)

Description

p = phase(input) extracts the unwrapped phase, p, of the input signal. Each column of the input signal is treated as a separate channel. The System object unwraps the phase of each channel of the input signal independently over time.

Input Arguments

input — Data input

vector | matrix

Data input, specified as a vector or a matrix. This object supports variable-size input signals. That is, you can change the input frame size (number of rows) even after calling the algorithm. However, the number of channels (number of columns) must remain constant.

Data Types: single | double
Complex Number Support: Yes

Output Arguments

p — Unwrapped phase

vector | matrix

Unwrapped phase of the input, returned as a vector or a matrix. The size and data type of the unwrapped phase output match the size and data type of the input signal.

Data Types: single | 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)

Common to All System Objects

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

Plot Unwrapped Phase Of a Sine Wave

Note: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent step syntax. For example, myObject(x) becomes step(myObject,x).

Create a dsp.SineWave System object?. Specify that the object generates an exponential output with a complex exponent.

sine = dsp.SineWave('Frequency',10,...
    'ComplexOutput',true,'SamplesPerFrame',128);

Create a dsp.PhaseExtractor System object?. Specify that the object ignores frame boundaries when returning the unwrapped phase.

phase = dsp.PhaseExtractor('TreatFramesIndependently',false);

Extract the unwrapped phase of a sine wave. Plot the phase versus time using a dsp.TimeScope System object?.

timeplot = dsp.TimeScope('PlotType','Line','SampleRate',1000,...
    'TimeSpan',1.5,'YLimits',[0 80],...
    'ShowGrid',true,...
    'YLabel','Unwrapped Phase (rad)');
for ii = 1:10
    sineOutput = sine();
    phaseOutput = phase(sineOutput);
    timeplot(phaseOutput)
end

Plot Phase Response of Third-Order IIR Filter

Note: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent step syntax. For example, myObject(x) becomes step(myObject,x).

Create a dsp.TransferFunctionEstimator System object?.

tfe = dsp.TransferFunctionEstimator('FrequencyRange','centered');

Create a dsp.PhaseExtractor System object?. Specify that the object must treat each frame of data independently.

phase = dsp.PhaseExtractor('TreatFramesIndependently',true);

Create a dsp.IIRFilter System object?. Compute the transfer function of a third-order IIR filter. Use the butter function to generate coefficients for the filter.

[b,a] = butter(3,.3);
iir = dsp.IIRFilter('Numerator',b,'Denominator',a);

Extract the phase response of the transfer function. Plot using a dsp.ArrayPlot System object?.

sampleRate = 1e3;
phaseplot = dsp.ArrayPlot('PlotType','Line','XOffset',-sampleRate/2,...
    'YLimits',[-15 0],...
    'YLabel','Phase Response (rad)',...
    'XLabel','Frequency (Hz)',...
    'Title','System Phase response');
for ii = 1:100
    % Generate input
    input = 0.05*randn(1000,1);
    % Pass through IIR filter
    filterOutput = iir(input);
    % Estimate transfer function
    transferFunction = tfe(input,filterOutput);
    % Plot transfer function phase
    phaseOutput = phase(transferFunction);
    phaseplot(phaseOutput);
end

Algorithms

Consider an input frame of length N:

$$\left(\begin{array}{l}{x}_1\\ x_2\\ ⋮\\ x_N\end{array}\right)$$

The step method acts on this frame and produces this output:

$$\left(\begin{array}{l}{\Phi }_1\\ {\Phi }_2\\ ⋮\\ {\Phi }_N\end{array}\right)$$

where:

$${\Phi }_i={\Phi }_{i-1}+\text{angle}(x_{i-1}^{*}{x}_i)$$

Here, i runs from 1 to N. The angle function returns the phase angle in radians.

If the input signal consists of multiple frames:

• If you set TreatFramesIndependently to true, the step method treats each frame independently. Therefore, in each frame, the step method calculates the phase using the preceding formula where:

  • $${\Phi }_0$$ is 0.

  • $$x_0$$ is 1.

• If you set TreatFramesIndependently to false, the step method ignores boundaries between frames. Therefore, in each frame, the step method calculates the phase using the preceding formula where:

  • $${\Phi }_0$$ is the last unwrapped phase from the previous frame.

  • $$x_0$$ is the last sample from the previous frame.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).