Documentation

dsp.PeakToRMS

Peak-to-root-mean-square value of vector

Description

The dsp.PeakToRMS System object™ calculates the peak-to-root-mean-square ratio of a vector.

To compute the peak-to-root-mean-square ratio:

1. Create the dsp.PeakToRMS 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

Description

example

ptr = dsp.PeakToRMS creates a peak-to-root-mean-square System object, ptr, that returns the ratio of the maximum magnitude (peak) to the root-mean-square (RMS) value in an input or a sequence of inputs.

ptr = dsp.PeakToRMS(Name,Value) returns an peak-to-root-mean-square System object, ptr, with each specified property set to the specified value. Enclose each property name in single quotes. Unspecified properties have default values.

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.

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

Set this property to true to enable the calculation of the peak-to-RMS ratio over successive calls to the object algorithm.

Specify the dimension along which to calculate the peak-to-RMS ratio as one of 'All', 'Row', 'Column', or 'Custom'. If you set this property to 'Custom', specify the dimension using the CustomDimension property.

Dependencies

This property applies when the RunningPeakToRMS property is false.

Specify the dimension as a positive integer along which the peak-to-RMS ratio is computed. The value of this property cannot exceed the number of dimensions in the input signal.

Dependencies

This property applies when the Dimension property is 'Custom'.

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

Set this property to true to enable output in dB. Set this property to false to report output as a ratio.

Set this property to true to enable resetting. When the property is set to true, a reset input must be specified in the call of object algorithm to reset the running peak-to-RMS ratio.

Dependencies

This property applies when the RunningPeakToRMS property is true.

Specify the event to reset the running peak-to-RMS as 'Rising edge', 'Falling edge', 'Either edge', or 'Non-zero'.

Dependencies

This property applies when the ResetInputPort property is true.

Usage

Description

example

y = ptr(x) computes the peak-to-RMS ratio, y, of the floating-point input vector x.

y = ptr(x,r) computes the peak-to-RMS ratio of the input elements over successive calls to the object algorithm. The object optionally resets its state based on the reset input signal, r, and the value of the ResetCondition property. To enable reset, set both the RunningPeakToRMS and the ResetInputPort properties to true.

Input Arguments

expand all

Data input, specified as a vector or a matrix. If x is a matrix, each column is treated as an independent channel. The peak-to-RMS value is computed along each channel.

Data Types: single | double

Reset signal, specified as a scalar value. The reset signal resets the object state based on the reset input signal and the value of the ResetCondition property.

Dependencies

To enable this signal, set both the RunningPeakToRMS and the ResetInputPort properties to true.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | logical

Output Arguments

expand all

Peak-to-RMS value of the input signal, returned as a scalar, vector, or matrix. If RunningPeakToRMS is set to:

• false –– The object computes the peak-to-RMS value of each input channel. If the input is a column vector, the output is a scalar. If the input is a multichannel signal, the output signal is a 1-by-N vector, where N is the number of input channels.

• true –– The object computes the running peak-to-RMS value of the signal. The size of the output signal matches the size of the input signal.

When the RunningPeakToRMS property is true, y corresponds to the peak-to-RMS ratio of the input elements over successive calls to the object algorithm.

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)

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

Determine the peak-to-RMS ratio of a vector input.

in = (1:10)';
ptr = dsp.PeakToRMS;
y = ptr(in)
y = 1.6116

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

Determine the peak-to-RMS ratio of a matrix input.

in = magic(4);
ptr = dsp.PeakToRMS;
ptr.Dimension = 'All';
y = ptr(in)
y = 1.6547