# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# 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

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}^{\prime }}^{*}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.