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?

Creation

Syntax

ptr = dsp.PeakToRMS

ptr = dsp.PeakToRMS(Name,Value)

Description

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

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.

RunningPeakToRMS — Calculation over successive calls to object algorithm

false (default) | true

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

Dimension — Dimension to operate along

'Column' (default) | 'All' | 'Row' | 'Custom'

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.

CustomDimension — Numerical dimension to operate along

1 (default) | positive integer

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

DecibelScaledOutput — Report output in decibels (dB)

true (default) | false

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

ResetInputPort — Enables resetting in running peak-to-RMS mode

false (default) | true

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.

ResetCondition — Reset condition for running peak-to-RMS mode

'Non-zero' (default) | 'Rising edge' | 'Falling edge' | 'Either edge'

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

Syntax

y = ptr(x)

y = ptr(x,r)

Description

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

x — Data input

vector | matrix

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

r — Reset signal

scalar

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

y — Peak-to-RMS value

scalar | vector | matrix

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)

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

Peak-to-RMS Ratio of Vector Input

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

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

y = 
1.6116

Peak-to-RMS Ratio of Matrix Input

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

More About

Peak-magnitude-to-RMS Level

The peak-magnitude-to-RMS level is

$$\frac{\left|\right|X|{|}_{\infty }}{\sqrt{\frac{1}{N}{\displaystyle \sum _{n=1}^N|}{X}_n{|}^2}},$$

where the l-infinity norm and RMS values are computed along the specified dimension.

References

[1] IEEE^® Standard on Transitions, Pulses, and Related Waveforms, IEEE Standard 181, 2003.

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

Version History

Introduced in R2012a