Learn more about Signal Processing Toolbox

dspdata - DSP data parameter information

Syntax

Hs = dspdata.dataobj(input1,...)

Description

Hs = dspdata.dataobj(input1,...) returns a dspdata object Hs of type dataobj. This object contains all the parameter information needed for the specified type of dataobj. Each dataobj takes one or more inputs, which are described on the individual reference pages. If you do not specify any input values, the returned object has default property values appropriate for the particular dataobj type.

Note You must use a dataobj with dspdata.

Data Objects

A data object (dataobj) for dspdata specifies the type of data stored in the object. Available dataobj types for dspdata are shown below.

dspdata.dataobj	Description
`dspdata.msspectrum`	Mean-square spectrum data (power)
`dspdata.psd`	Power spectral density data (power/frequency)
`dspdata.pseudospectrum`	Pseudospectrum data (power)

For more information on each dataobj type, use the syntax help dspdata.dataobj at the MATLAB prompt or refer to its reference page.

Methods

Methods provide ways of performing functions directly on your dspdata object. You can apply these methods directly on the variable you assigned to your dspdata object.

Method	Description
`avgpower`	Note that this method applies only to `dspdata.psd` objects. `avgpower(Hs)` computes the average power in a given frequency band. The technique uses a rectangle approximation of the integral of the `Hs` signal's power spectral density (PSD). If the signal is a matrix, the computation is done on each column. The average power is the total signal power and the `SpectrumType` property determines whether the total average power is contained in the one-sided or two-sided spectrum. For aa one-sided spectrum, the range is [0,pi] for even number of frequency points and [0,pi) for odd. For a two-sided spectrum the range is [0,2pi). `avgpower(Hs,freqrange)` specifies the frequency range over which to calculate the average power. `freqrange` is a two-element vector of the frequencies between which to calculate. If a frequency value does not match exactly the frequency in `Hs`, the next closest value is used. Note that the first frequency value in `freqrange` is included in the calculation and the second value is excluded.
`centerdc`	`centerdc(Hs)` or `centerdc(Hs,true)` shifts the data and frequency values so that the DC component is at the center of the spectrum. If the `SpectrumType` property is `'onesided'`, it is changed to `'twosided'` and then the DC component is centered. `centerdc(Hs,'false')` shifts the data and frequency values so that the DC component is at the left edge of the spectrum.
`findpeaks`	`findpeaks(Hs)` finds local maxima or peaks. If no peaks are found, `findpeaks` returns an empty vector. `[pks,frqs] = findpeaks(x)` returns peaks values (`pks`) and the frequencies (`frqs`) at which the peaks occur. `findpeaks(x,'minpeakheight',mph)` returns only peaks greater than the minimum peak height `mph`, where `mph` is a real scalar. Default is `-Inf`. `findpeaks(x,'minpeakdistance',mpd)` returns only peaks separated by the minimum frequency units distance `mpd`, which is a positive integer. Setting the minimum peak distance ignores smaller peaks that may occur close to larger local peaks. Default is 1. `findpeaks(x,'threshold',th)` returns only peaks greater than their neighbors by at least the threshold `th`, which is a real, scalar value greater than or equal to 0. Default is 0. `findpeaks(x,'npeaks',np)` returns a maximum of `np` number of peaks. When `np` peaks are found, the search stops. Default is to return all peaks. `findpeaks(x,'sortstr',str)` specifies the sorting order, where `str` is `'ascend'`, `'descend'` or `'none'`. For `'ascend'` , the peaks are returned in order from smallest to largest, and vice versa for `'descend'`. For `'none'`, the peaks are returned in the order in which they occur.
`halfrange`	`halfrange(Hs)` converts the `Hs` spectrum to a spectrum calculated over half the Nyquist interval. All associated properties affected by the new frequency range are adjusted automatically. This method is used for `dspdata.pseudospectrum` objects. Note that the spectrum is assumed to be from a real signal (that is, `halfrange` uses half the data points regardless of whether the data is symmetric).
`normalizefreq`	`normalizefreq(Hs)` or `normalizefreq(Hs,true)` normalizes the frequency specifications in the `Hs` object to `Fs` so the frequencies are between 0 and 1. It also sets the `NormalizedFrequency` property to `true`. `normalizefreq(Hs,false)` converts the frequencies to linear frequencies. `normalizefreq(Hs,false,Fs)` sets a new sampling frequency `Fs`. This can be used only with `false`.
`onesided`	`onesided(Hs)` converts the `Hs` spectrum to a spectrum calculated over half the Nyquist interval and containing the total signal power. All associated properties affected by the new frequency range are adjusted automatically. This method is used for `dspdata.psd` and `dspdata.msspectrum` objects. Note that the spectrum is assumed to be from a real signal (that is, `onesided` uses half the data points regardless of whether the data is symmetric).
`plot`	Displays the data graphically in the current figure window. For a `dspdata.psd` object, it displays the power spectral density in dB/Hz. For a `dspdata.msspectrum` object, it displays the mean–square in dB. For a `dspdata.pseudospectrum` object, it displays the pseudospectrum in dB.
`sfdr`	This method applies only to `dspdata.msspectrum` objects. `sfdr(Hs)` computes the spurious-free dynamic range (SFDR) in dB of a mean square spectrum object `Hs`. SFDR is the usable range before spurious noise interferes with the signal. `[sfd,spur,frq] = sfdr(Hs)` returns the magnitude of the highest `spur` and the frequency `frq` at which it occurs. `sfdr(Hs,'minspurlevel',msl)` ignores spurs below the minimum spur level `msl`, which is a real scalar in dB. `sfdr(Hs,'minspurdistance',msd)` includes spurs only if they are separated by at least the minimum spur distance `msd`, which is a real, positive scalar in frequency units.
`twosided`	`twosided(Hs)` converts the `Hs` spectrum to a spectrum calculated over the whole Nyquist interval. All associated properties affected by the new frequency range are adjusted automatically. This method is used for `dspdata.psd` and `dspdata.msspectrum` objects. Note that if your data is nonuniformly sampled, converting from `onesided` to `twosided` may produce incorrect results.
`wholerange`	`wholerange(Hs)` converts the `Hs` spectrum to a spectrum calculated over the whole Nyquist interval. All associated properties affected by the new frequency range are adjusted automatically. This method is used for `dspdata.pseudospectrum` objects. Note that if your data is nonuniformly sampled, converting from `half` to `wholerange` may produce incorrect results.

For more information on each method, use the syntax help dspdata/method at the MATLAB prompt.

Plotting a dspdata Object

The plot method displays the dspdata object spectrum in a separate figure window.

plot(Hs)             % Plots an existing Hs object

Modifying a dspdata Object

After you create a dspdata object, you can use any of the methods in the table above to modify the object properties.

For example, to change the object from two-sided to one-sided, use

onesided(Hs)

The Hs object is modified.

Examples

See the msspectrum, psd, or pseudospectrum reference pages for specific examples.