Main Content

spectrum

Spectral estimation

Syntax

Hs = spectrum.estmethod(input1,...)

Description

Note

The use of spectrum.estmethod is not recommended. Use the corresponding function instead. See Spectrum Estimation Methods for the functional forms.

Hs = spectrum.estmethod(input1,...) returns a spectral estimation object Hs of type estmethod. This object contains all the parameter information needed for the specified estimation method. Each estimation method takes one or more inputs, which are described on the individual reference pages.

Estimation Methods

Estimation methods for spectrum specify the type of spectral estimation method to use. Available estimation methods for spectrum are listed below.

Note

You must use a spectral estmethod with spectrum.

Spectrum Estimation Methods

spectrum.estmethod

Description

Corresponding Function

spectrum.burg

Burg

pburg

spectrum.cov

Covariance

pcov

spectrum.eigenvector

Eigenvector

peig

spectrum.mcov

Modified covariance

pmcov

spectrum.mtm

Thomson multitaper

pmtm

spectrum.music

Multiple Signal Classification

pmusic

spectrum.periodogram

Periodogram

periodogram

spectrum.welch

Welch

pwelch

spectrum.yulear

Yule-Walker

pyulear

For more information on each estimation method, use the syntax help spectrum.estmethod at the MATLAB® prompt or refer to its reference page.

Note

For estimation methods that use overlap and window length inputs, you specify the number of overlap samples as a percent overlap and you specify the segment length instead of the window length.

For estimation methods that use windows, if the window uses an additional parameter, a property is dynamically added to the spectrum object for that parameter. You can change that property using set (see Changing Object Properties).

Methods

Methods provide ways of performing functions directly on your spectrum object without having to specify the spectral estimation parameters again. You can apply these methods directly on the variable you assigned to your spectrum object. For more information on any of these methods, use the syntax help spectrum/method at the MATLAB prompt or refer to the table below.

Spectrum Methods

MethodDescription

msspectrum

Note that the msspectrum method is only available for the periodogram and welch spectrum estimation objects.

The mean-squared spectrum is intended for discrete spectra (from periodic, discrete-time signals). The distribution of the mean square value across frequency is the msspectrum. Unlike the power spectral density (see psd below), the peaks in the mean-square spectrum reflect the power in the signal at a given frequency. For the PSD, the power is reflected as the area in a frequency band. The units of the mean-squared spectrum are units of power.

Hmss = msspectrum(Hs,X) returns a mean-square spectrum object containing the mean-square (power) estimate of the discrete-time signal X using the spectrum object Hs. Default for real X is the 'onesided' Nyquist frequency range and for complex X the default is the 'twosided' Nyquist frequency range.

Hmss contains a vector of normalized frequencies W, at which the mean-square spectrum is estimated. For real signals, the range of W is [0,π] if the number of FFT points (NFFT) is even, and [0,π) if NFFT is odd. For complex signals, the range of W is [0,2π). To estimate the spectrum on a vector of specific frequencies, see FreqPoints property below.

The msspectrum method includes these properties, which you can set using this msspectrum method or via the msspectrumopts method. These properties are listed here and described in the msspectrumopts section below:

SpectrumType'onesided' or 'twosided'
NormalizedFrequency – normalizes frequency between 0 and 1
Fs — sampling frequency in Hz
NFFT — number of FFT points
CenterDC — shifts data and frequencies to center DC component
FreqPoints'All' or 'User Defined'
FrequencyVector — frequencies at which to compute spectrum
ConfLevel — confidence level to calculate the confidence interval. Value must be from 0 to 1.

For example, Hmss = msspectrum(Hs,X,'FreqPoints','User Defined', FreqVector,fvect) returns a mean-square spectrum object where the spectrum is calculated only on the frequency points defined in the frequency vector, fvect.

msspectrum(...) with no output arguments plots the mean-square spectrum in dB.

msspectrumopts

Hopts = msspectrumopts(Hs) returns an object that contains options for the spectrum object Hs.

Hopts = msspectrumopts(Hs,X) returns an object with data-specific options and defaults.

You can pass an Hopts options object as an argument to the msspectrum method. Any individual option you specify after the Hopts object overrides the value in Hopts. For example, Hmss = msspectrum(Hs,X,Hopts, 'SpectrumType', 'twosided') overrides the default SpectrumType value in Hopts.

The following properties apply to both msspectrumopts and msspectrum methods.

Hmss = msspectrum (..., 'SpectrumType', 'twosided') returns the two-sided mean-square spectrum. The spectrum length (NFFT) is computed over [0,2π), or if Fs is specified, [0,Fs) . Entering 'onesided' returns the one-sided mean-square spectrum, which contains the total signal power in half the Nyquist range. Default is 'onesided'.

Hmss = msspectrum(Hs,X,'NormalizedFrequency',true) returns a mean-square spectrum object with frequency values normalized between 0 and 1. Default is true.

Hmss = msspectrum(Hs,X,'Fs',Fs) returns a mean-square spectrum object computed as a function of frequency, where Fs is the sampling frequency in Hz. Note that you can set Fs only if NormalizedFrequency is set to false.

Hmss = msspectrum(...,'NFFT',nfft) specifies the number of FFT points to use. Valid values are a positive integer, 'Nextpow2' or 'Auto'. 'Nextpow2' uses the next power of 2 greater than the input length or 256, whichever is greater. 'Auto' uses the input length or 256, whichever is greater. Default is 'Nextpow2'. Note that for spectrum.welch, 'Nextpow2' and 'Auto' are compared to the SegmentLength instead of the input length.

Hmss = msspectrum (..., 'Centerdc', true) shifts the data and frequency values so that the DC component is at the center of the spectrum. Default is false.

To estimate the spectrum on a vector of specific frequencies, first set the number of frequency points to 'User Defined', which replaces the NFFT property of msspectrum with a FrequencyVector property.
Hopts.FreqPoints = 'User Defined'
(Note that the default for FreqPoints is 'All', which causes msspectrum to use the NFFT property as described above.)

Then, specify the frequency vector F to use.
Hopts.FrequencyVector = F
(Note that the default value for FrequencyVector is 'Auto'. In this case, the number of frequency points used follows the same rule as described for NFFT 'Auto' above.)

Hmms = msspectrum(...,'ConfLevel',p) specifies the confidence level p for computing the confidence interval, which is an estimate of the error in the calculated mean-squared spectrum. The confidence level (p) is between 0 and 1. For example, Hmss = msspectrum(Hs,X,'ConfLevel',0.95) returns the 95% confidence interval.

psd

Note that music and eigenvector spectrum objects do not support the psd method. See the pseudospectrum method below.

The power spectral density (PSD) is intended for continuous spectra. The integral of the PSD over a given frequency band computes the average power in the signal in that frequency band. In contrast to the msspectrum, the peaks in this spectra do not reflect the power at a given frequency. The units of the PSD are power per unit of frequency. See the avgpower method of dspdata for more information.

Hpsd = psd (Hs,X) returns a power spectral density object containing the power spectral density estimate of the discrete-time signal X using the spectrum object Hs. The PSD is the distribution of power per unit frequency. Default for real X is 'onesided' and for complex X is 'twosided'.

Hpsd contains a vector of normalized frequencies W, at which the PSD is estimated. For real signals, the range of W is [0,π] if the number of FFT points (NFFT) is even, and [0,π) if NFFT is odd. For complex signals, the range of W is [0,2π).

The psd method includes these properties, which you can set using this psd method or via the psdopts method. These properties are listed here and described in the psdopts section below:

SpectrumType'onesided' or 'twosided'
NormalizedFrequency — normalizes frequency between 0 and 1
Fs — sampling frequency in Hz
NFFT — number of FFT points
CenterDC — shifts data and frequencies to center DC component
FreqPoints'All' or 'User Defined'
FrequencyVector – frequencies at which to compute spectrum
ConfLevel — confidence level to calculate the confidence interval. Value must be from 0 to 1.

For example, Hmss = psd(Hs,X,'FreqPoints','User Defined', FreqVector,fvect) returns a PSD object where the spectrum is calculated only on the frequency points defined in the frequency vector, fvect.

psd(...) with no output arguments plots PSD in dB per unit frequency.

psdopts

Hopts = psdopts(Hs) returns an object that contains options for the spectrum object Hs.

Hopts = psdopts(Hs,X) returns an object with data-specific options and defaults.

You can pass an Hopts options object as an argument to the psd method. Any individual option you specify after the Hopts object overrides the value in Hopts. For example, Hpsd = psd(Hs,X,Hopts,'SpectrumType', 'twosided') overrides the SpectrumType value in Hopts.

The following properties apply to both psdmopts and psd methods.

Hpsd = psd (Hs,X,'SpectrumType','twosided') returns the two-sided power spectral density of X. The spectrum length is NFFT and is computed over [0,2π) if Fs is not specified or [0,Fs) if Fs is specified. Entering 'onesided' returns the one-sided PSD, which contains the total signal power.

Hmss = psd(Hs,X,'NormalizedFrequency',true) returns a power spectral density object with frequency values normalized between 0 and 1. Default is true.

Hpsd = psd (...,'Fs',Fs) returns a power spectral density object computed as a function of frequency, where Fs is the sampling frequency in Hz.

Hmss = psd(...,'NFFT',nfft) specifies the number of FFT points to use. Valid values are a positive integer, 'Nextpow2' or 'Auto'. 'Nextpow2' uses the next power of 2 greater than the input length or 256, whichever is greater. 'Auto' uses the input length or 256, whichever is greater. Default is 'Nextpow2'. Note that for spectrum.welch, 'Nextpow2' and 'Auto' are compared to the SegmentLength instead of the input length.

Hmss = psd (..., 'Centerdc', true) shifts the data and frequency values so that the DC component is at the center of the spectrum. Default is false.

To estimate the spectrum on a vector of specific frequencies, first set the number of frequency points to 'User Defined', which replaces the NFFT property of psd with a FrequencyVector property.
Hopts.FreqPoints = 'User Defined'
(Note that the default for FreqPoints is 'All' which causes psd to use the NFFT property as described above.)

Hmms = psd(...,'ConfLevel',p) specifies the confidence level p for computing the confidence interval, which is an estimate of the error in the calculated PSD. The confidence level (p) is between 0 and 1. For example, Hmss = psd(Hs,X,'ConfLevel',0.95) returns the 95% confidence interval.

pseudospectrum

Note that this method is used for only music or eigenvector spectrum objects.

Hps = pseudospectrum(Hs,X) returns an object containing the pseudospectrum estimate of the discrete-time signal X using the spectrum object Hs. Hs must be a music or eigenvector object. Default for real X is 'half' and for complex X is the 'whole' Nyquist frequency range.

Hps contains a vector of normalized frequencies W, at which the pseudospectrum is estimated. For real signals, the range of W is [0,π] if the number of FFT points (NFFT) is even, and [0,π) if NFFT is odd. For complex signals, the range of W is [0,2π).

The pseudospectrum method includes these properties, which you can set using this pseudospectrum method or via the pseudospectrumopts method. These properties are described below:

SpectrumRange'half' or 'whole'
NormalizedFrequency — normalizes frequency between 0 and 1
Fs — sampling frequency in Hz
NFFT — number of FFT points
CenterDC — shifts data and frequencies to center DC component
FreqPoints'All' or 'User Defined'
FrequencyVector — frequencies at which to compute spectrum

For example, Hmss = psd(Hs,X,'FreqPoints','User Defined', FreqVector,fvect) returns a PSD object where the spectrum is calculated only on the frequency points defined in the frequency vector, fvect.

pseudospectrum(...) with no output arguments plots the pseudospectrum in dB.

pseudospectrumopts

Hopts = pseudospectrumopts(Hs) returns an object that contains options for the spectrum object Hs.

Hopts = pseudospectrumopts(Hs,X) returns an object with data-specific options and defaults. You can pass an Hopts options object as an argument to the pseudospectrum method. Any individual option you specify after the Hopts object overrides the value in Hopts. For example, Hpseudospectrum= pseudospectrum(Hs,X, Hopts,'SpectrumRange', 'whole') overrides the SpectrumRange value in Hopts.

Hmps = pseudospectrum (..., 'SpectrumRange', 'whole') returns the pseudospectrum over the whole Nyquist range. The spectrum length is NFFT and is computed over [0,2π) if Fs is not specified or [0,Fs) if Fs is specified. Entering 'half' returns the pseudospectrum calculated over half the Nyquist range.

Hmss = pseudospectrum(Hs,X,'NormalizedFrequency',true) returns a pseudospectrum object with frequency values normalized between 0 and 1. Default is true.

Hps = pseudospectrum(Hs,X,'Fs',Fs) returns a pseudospectrum object computed as a function of frequency, where Fs is the sampling frequency in Hz.

Hps = pseudospectrum(...,'NFFT',nfft) specifies the number of FFT points to use. Valid values are a positive integer, 'Nextpow2' or 'Auto'. 'Nextpow2' uses the next power of 2 greater than the input length or 256, whichever is greater. 'Auto' uses the input length or 256, whichever is greater. Default is 'Nextpow2'.

Hps = pseudospectrum(...,'Centerdc',true) shifts the data and frequency values so that the DC component is at the center of the spectrum. The default value is false.

To estimate the spectrum on a vector of specific frequencies, first set the number of frequency points to 'User Defined', which replaces the NFFT property of pseudospectrum with a FrequencyVector property.
Hopts.FreqPoints = 'User Defined'
(Note that the default for FreqPoints is 'All', which causes pseudospectrum to use the NFFT property as described above.)

powerest

Note that powerest is available only for music and eigenvector spectrum objects.

POW = powerest(Hs,X) returns a vector POW containing estimates of the powers of the complex sinusoids in X. The input X can be a vector or a matrix. If it is a matrix it can be a data matrix, where X*X=R or a correlation matrix R. The value the InputType property of Hs determines how X is interpreted. Hs must be a music or eigenvector spectrum object.

[POW,W]=powerest(Hs,X) returns POW and a vector W of the frequencies in rad/sample of the sinusoids in X.

[POW,F]=powerest(Hs,X,Fs) returns POW and a vector F of the frequencies in Hz of the sinusoids in X. Fs is the sampling frequency.

Viewing Object Properties

As with any object, you can use get to view a spectrum object's properties. To see a specific property, use

 get(Hs,'property') 

where 'property' is the specific property name.

To see all properties for an object, use

get(Hs)

Changing Object Properties

To set specific properties, use

set(Hs,'property1',value, 'property2',value,...) 

where 'property1', 'property2', etc. are the specific property names.

To view the options for a property use set without specifying a value

set(Hs,'property')

Note that you must use single quotation marks around the property name. For example, to change the order of a Burg spectrum object Hs to 6, use

set(Hs,'order',6)

Another example of using set to change an object's properties is this example of changing the dynamically created window property of a periodogram spectrum object.

Hs=spectrum.periodogram       % Create periodogram object

Hs =

    EstimationMethod: 'Periodogram'
          WindowName: 'Rectangular'

set(Hs,'WindowName','Chebyshev')   % Change window type
Hs                                 % View changed object

Hs =

    EstimationMethod: 'Periodogram'
          WindowName: 'Chebyshev'  % Note changed property
       SidelobeAtten: 100

set(Hs,'SidelobeAtten',150)   % Change dynamic property
Hs                            % View changed object

Hs =

    EstimationMethod: 'Periodogram'
          WindowName: 'Chebyshev'
       SidelobeAtten: 150 

All spectrum object properties can be changed using the set command, except for the EstimationMethod property.

Another way to change an object's properties is by using the inspect command which opens the Property Inspector window where you can edit any property, except dynamic properties, such as those used with windows.

inspect(Hs)

Copying an Object

To create a copy of an object, use the copy method.

H2 = copy(Hs)

Note

Using the syntax H2 = Hs copies only the object handle and does not create a new object.

Examples

collapse all

Generate a cosine of frequency 200 Hz sampled at 1 kHz for 300 ms. Add Gaussian white noise. View its power spectral density estimate generated with the periodogram algorithm.

Fs = 1000;
t = 0:1/Fs:0.3;
x = cos(2*pi*t*200) + randn(size(t));

Hs = spectrum.periodogram;
psd(Hs,x,'Fs',Fs)

Refer to the reference pages for each estimation method for more examples.

Version History

Introduced before R2006a