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.

## Creation

### Syntax

``ptr = dsp.PeakToRMS``
``ptr = dsp.PeakToRMS(Name,Value)``

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

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

### Syntax

``y = ptr(x)``
``y = ptr(x,r)``

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

expand all

## References

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