# bandpower

## Syntax

``p = bandpower(x)``
``p = bandpower(x,fs,freqrange)``
``p = bandpower(pxx,f,'psd')``
``p = bandpower(pxx,f,freqrange,'psd')``

## Description

example

````p = bandpower(x)` returns the average power in the input signal, `x`. If `x` is a matrix, then `bandpower` computes the average power in each column independently.```

example

````p = bandpower(x,fs,freqrange)` returns the average power in the frequency range, `freqrange`, specified as a two-element vector. You must input the sample rate, `fs`, to return the power in a specified frequency range. `bandpower` uses a modified periodogram to determine the average power in `freqrange`.```

example

````p = bandpower(pxx,f,'psd')` returns the average power computed by integrating the power spectral density (PSD) estimate, `pxx`. The integral is approximated by the rectangle method. The input, `f`, is a vector of frequencies corresponding to the PSD estimates in `pxx`. The `'psd'` option indicates that the input is a PSD estimate and not time series data.```

example

````p = bandpower(pxx,f,freqrange,'psd')` returns the average power contained in the frequency interval, `freqrange`. If the frequencies in `freqrange` do not match values in `f`, the closest values are used. The average power is computed by integrating the power spectral density (PSD) estimate, `pxx`. The integral is approximated by the rectangle method. The `'psd'` option indicates the input is a PSD estimate and not time series data.```

## Examples

collapse all

Create a signal consisting of a 100 Hz sine wave in additive N(0,1) white Gaussian noise. The sampling frequency is 1 kHz. Determine the average power and compare it against the ${\ell }_{2}$ norm.

```t = 0:0.001:1-0.001; x = cos(2*pi*100*t)+randn(size(t)); p = bandpower(x)```
```p = 1.5264 ```
`l2norm = norm(x,2)^2/numel(x)`
```l2norm = 1.5264 ```

Determine the percentage of the total power in a specified frequency interval.

Create a signal consisting of a 100 Hz sine wave in additive N(0,1) white Gaussian noise. The sampling frequency is 1 kHz. Determine the percentage of the total power in the frequency interval between 50 Hz and 150 Hz. Reset the random number generator for reproducible results.

```rng('default') t = 0:0.001:1-0.001; x = cos(2*pi*100*t)+randn(size(t)); pband = bandpower(x,1000,[50 150]); ptot = bandpower(x,1000,[0 500]); per_power = 100*(pband/ptot)```
```per_power = 51.9591 ```

Determine the average power by first computing a PSD estimate using the periodogram. Input the PSD estimate to `bandpower`.

Create a signal consisting of a 100 Hz sine wave in additive N(0,1) white Gaussian noise. The sampling frequency is 1 kHz. Obtain the periodogram and use the `'psd'` flag to compute the average power using the PSD estimate. Compare the result against the average power computed in the time domain.

```t = 0:0.001:1-0.001; Fs = 1000; x = cos(2*pi*100*t)+randn(size(t)); [Pxx,F] = periodogram(x,rectwin(length(x)),length(x),Fs); p = bandpower(Pxx,F,'psd')```
```p = 1.5264 ```
`avpow = norm(x,2)^2/numel(x)`
```avpow = 1.5264 ```

Determine the percentage of the total power in a specified frequency interval using the periodogram as the input.

Create a signal consisting of a 100 Hz sine wave in additive N(0,1) white Gaussian noise. The sampling frequency is 1 kHz. Obtain the periodogram and corresponding frequency vector. Using the PSD estimate, determine the percentage of the total power in the frequency interval between 50 Hz and 150 Hz.

```Fs = 1000; t = 0:1/Fs:1-0.001; x = cos(2*pi*100*t)+randn(size(t)); [Pxx,F] = periodogram(x,rectwin(length(x)),length(x),Fs); pBand = bandpower(Pxx,F,[50 150],'psd'); pTot = bandpower(Pxx,F,'psd'); per_power = 100*(pBand/pTot)```
```per_power = 49.1798 ```

Create a multichannel signal consisting of three sinusoids in additive N(0,1) white Gaussian noise. The sinusoids' frequencies are 100 Hz, 200 Hz, and 300 Hz. The sampling frequency is 1 kHz, and the signal has a duration of 1 s.

```Fs = 1000; t = 0:1/Fs:1-1/Fs; f = [100;200;300]; x = cos(2*pi*f*t)'+randn(length(t),3);```

Determine the average power of the signal and compare it to the ${\ell }_{2}$ norm.

`p = bandpower(x)`
```p = 1×3 1.5264 1.5382 1.4717 ```
`l2norm = dot(x,x)/length(x)`
```l2norm = 1×3 1.5264 1.5382 1.4717 ```

## Input Arguments

collapse all

Input time series data, specified as a row or column vector or as a matrix. If `x` is a matrix, then its columns are treated as independent channels.

Example: `cos(pi/4*(0:159))'+randn(160,1)` is a single-channel column-vector signal.

Example: `cos(pi./[4;2]*(0:159))'+randn(160,2)` is a two-channel noisy sinusoid.

Data Types: `double` | `single`
Complex Number Support: Yes

Sampling frequency for the input time series data, specified as a positive scalar.

Data Types: `double` | `single`

Frequency range for the band power computation, specified as a two-element real-valued row or column vector. If the input signal, `x`, contains N samples, `freqrange` must be within the following intervals:

• [0, `fs`/2] if `x` is real-valued and N is even

• [0, (N – 1)`fs`/(2N)] if `x` is real-valued and N is odd

• [–(N – 2)`fs`/(2N), `fs`/2] if `x` is complex-valued and N is even

• [–(N – 1)`fs`/(2N), (N – 1)`fs`/(2N)] if `x` is complex-valued and N is odd

Data Types: `double` | `single`

One- or two-sided PSD estimates, specified as a real-valued column vector or matrix with nonnegative elements.

The power spectral density must be expressed in linear units, not decibels. Use `db2pow` to convert decibel values to power values.

Example: ```[pxx,f] = periodogram(cos(pi./[4;2]*(0:159))'+randn(160,2))``` specifies the periodogram PSD estimate of a noisy two-channel sinusoid sampled at 2π Hz and the frequencies at which it is computed.

Data Types: `double` | `single`

Frequency vector, specified as a column vector. The frequency vector, `f`, contains the frequencies corresponding to the PSD estimates in `pxx`.

Data Types: `double` | `single`

## Output Arguments

collapse all

Average band power, returned as a nonnegative scalar.

Data Types: `double` | `single`