|
Calling Sequence
|
|
BandPower( data )
BandPower( data, samplerate )
BandPower( data, samplerate, frequencyrange )
BandPower( data, frequencies )
BandPower( data, frequencies, frequencyrange )
|
|
Parameters
|
|
data
|
-
|
1-D rtable or list of data, representing either a signal or power spectral density (PSD)
|
samplerate
|
-
|
(optional) positive numeric value for the sampling rate
|
frequencies
|
-
|
(optional) 1-D list or rtable of numeric frequency components
|
frequencyrange
|
-
|
(optional) range of numeric frequency values used to filter (i.e. band-limit) the data. If omitted, all frequencies are considered.
|
|
|
|
|
Options
|
|
•
|
variety: Specifies the type of data passed. The options are signal and psd (for a power spectral density). The default is signal.
|
•
|
frequencyunit: Specifies the underlying unit of frequency used when computing statistics. Either of the forms algebraic and Unit(algebraic) are accepted. The default is Unit(Hz).
|
•
|
fftnormalization: One of none, symmetric, or full, indicates the normalization to be applied when using the Fast Fourier Transform (FFT). The default is symmetric.
|
•
|
temperendpoints: Either true or false, specifies whether the power spectrum is to be tempered at the endpoints. The default is false.
|
•
|
window: Either a list, name, or string, specifies the windowing command to be applied to the signal when variety=signal. The default is "none" (for no windowing to be applied).
|
•
|
windownormalization: Either true or false, indicates if the windowing function is to be normalized. The default is true.
|
•
|
method: The method of numerical integration to be used to find band power. The options are leftendpoint, rightendpoint, simpson, and trapezoid. The default is trapezoid, which is equivalent to finding the area under the linear interpolation through all the points.
|
•
|
output : The type of output. The supported options are:
|
–
|
bandpower: Returns a value of type float[8] for the band power.
|
–
|
entropy: Returns a value of type float[8] for the spectral entropy.
|
–
|
meanfrequency: Returns a value of type float[8] for the mean frequency.
|
–
|
frequencies: Returns a Vector, of float[8] datatype and length the same as signal, containing the frequencies.
|
–
|
indices: Returns a list of the form , where and are, respectively, the lower and upper indices of the frequencies Vector that correspond to the frequencies in frequencyrange.
|
–
|
psd: Returns a vector of float[8] datatype containing the power spectral density.
|
–
|
record: Returns a record with the previous options.
|
–
|
list of any of the above options: Returns an expression sequence with the corresponding outputs, in the same order.
|
|
The default output is bandpower.
|
|
|
Description
|
|
•
|
The BandPower command takes a 1-D rtable or list of data and computes band power based on the remaining parameters and options. Other statistics, like mean frequency and spectral entropy, can be computed and returned, along with Vectors for the power spectral density and frequencies.
|
•
|
If data is an rtable of type AudioTools:-Audio, the sample rate in hertz () is inferred from the attributes. Should samplerate also be passed, it will be overridden.
|
•
|
Values for/in samplerate, frequencyrange, and frequencies can include units for frequency, and those without an explicit unit are assumed to be in terms of frequencyunit. An error will be thrown if a unit which cannot be converted to hertz is passed. Caution: Passing long vectors with elements having units requires time-consuming conversions. It is recommended that the frequencies Vector consist only of the numeric values, with units indicated by frequencyunit.
|
•
|
If window is passed as a list, the first element provides the name of the windowing command, and any remaining terms are passed as options to the command.
|
•
|
The value of window, when not passed as a list, should be the name or string, with or without the Window suffix, that corresponds to the windowing command. For example, to use a Hamming window, you can pass window=Hamming or window="HammingWindow". In both cases, the command SignalProcessing[HammingWindow] will be used internally. Similarly, you can pass window=["Exponential",0.5] or window=[ExponentialWindow,0.5] to use SignalProcessing[ExponentialWindow] with parameter value 0.5.
|
•
|
To apply a window to a Vector of length , the window is first applied to another Vector of size and filled with ones, and then is multiplied element-wise by . When windownormalization=true, is first normalized with respect to its Root Mean Square (RMS).
|
•
|
Two or more points are always required in data to compute band power, mean frequency, and spectral entropy in the frequency domain.
|
•
|
When variety=psd, the elements of data must be non-negative, the elements of frequencies must be strictly increasing, and the left end of frequencyrange must be less than the right end.
|
•
|
A value for samplerate is required and used when variety=signal.
|
•
|
The frequencies rtable is required and used only when variety=psd. In this case, the rtable must be of the same size as data.
|
•
|
Input rtables (data and frequencies) are converted to Vectors of either float[8] or complex[8] datatype, and an error will be thrown if this is not possible. For this reason, it is most efficient for input rtables to already be Vectors having the appropriate datatype. Specifically:
|
•
|
frequencies should be float[8].
|
•
|
When variety=signal, data should be float[8] (for real-valued data) or complex[8] (for complex-valued data).
|
•
|
When variety=psd, data should be float[8].
|
•
|
The band power of signal with length is computed as the area beneath the graph of the power spectral density of versus the frequencies . To this end, first calculate the FFT of . If is real-valued, we take to be the first half of the FFT (due to symmetry). The end result will be scaled appropriately, giving the same band power as if the truncation had not been performed. When has complex values, on the other hand, a full FFT is used to define . We take the half-size to be the following:
|
|
Second, compute the power spectral density from :
|
|
where is the size of (either or ), is the sample rate, and when is real-valued and when is complex-valued. To create the Vector of frequencies, we consider the two cases. When is real-valued:
|
|
When is complex-valued:
|
|
Caution: Maple uses the convention of the frequencies ranging from to , where and is the interval over which the signal is sampled. The other common convention is to use frequencies in the range . Usually, is the period of a periodic function.
|
•
|
The mean frequency of signal is computed as the average of the frequencies weighted by the power spectral density :
|
|
where is the size of (either or ). When all elements of are zero, then the mean frequency is HFloat(undefined).
|
•
|
The spectral entropy of signal is computed using the formula from Shannon Information Theory applied to the power spectral density treated as a probability distribution:
|
|
and is the size of (either or ). When all elements of are zero, then the spectral entropy is HFloat(undefined). Note that another convention for spectral entropy is to divide the above by , which quantifies the maximum spectral entropy of white noise.
|
•
|
When temperendpoints=true, the endpoints of the power spectrum, determined by the method described above, are halved. Note that the signal size must be three or more for tempering.
|
•
|
The frequencyrange option is used to restrict the computations for statistics to a specific frequency band. It can be in the form a..b (to restrict frequencies to those between a and b), a.. (to restrict frequencies to those that are no less than a), ..b (to restrict frequencies to those that are no more than b), or .. (to allow all frequencies). The endpoints of frequencyrange are used to determine indices and , with the band power estimated as the the numeric integral of over , the mean frequency estimated as the mean of with weights , and the spectral entropy computed as the entropy of where is normalized as a probability distribution. In the simplest case, where and are both provided with , , and , we take to be the largest index such that , and to be the smallest index such that .
|
•
|
Band powers for a disjoint union of intervals typically add up to close to the total. For example, BandPower(X,0.01,..50)+BandPower(X,0.01,50..) should be close to (but not necessarily equal, due to discretization and numerical errors) BandPower(X).
|
•
|
The BandPower command is not thread safe.
|
|
|
Examples
|
|
>
|
|
|
Real-Valued Signal
|
|
|
Signal
|
|
•
|
For an illustrative example involving a real-valued signal, first create a signal:
|
>
|
|
| (2) |
>
|
|
|
|
Periodogram
|
|
>
|
|
|
|
Band Power
|
|
•
|
Intuitively, we expect the overall band power to be dominated by the frequencies 500, 1000, and 1500, in the proportion 1:9:4. The frequencies can be gleaned from the standard expression , and the proportions follow from the squares of the respective amplitudes.
|
•
|
To confirm this, first find the overall band power:
|
>
|
|
| (3) |
•
|
Second, we output the power spectral density and frequencies Vectors from BandPower so that they are only calculated once:
|
>
|
|
•
|
Of course, we can pass the original signal using the variety=signal option to compute band powers and mean frequencies for various frequency ranges, but each call would compute internally the power spectral density and frequencies Vectors.
|
•
|
Now, find the band powers in a narrow band around each of the frequencies:
|
>
|
|
| (4) |
>
|
|
| (5) |
>
|
|
| (6) |
•
|
The total of these individual band powers is indeed very close to the overall band power:
|
•
|
Units are also accepted:
|
>
|
|
•
|
BandPower can also return the indices for the frequencies Vector corresponding to the provided frequency range:
|
>
|
|
|
|
|
Complex-Valued Signal
|
|
•
|
Consider now the following complex-valued signal:
|
>
|
|
| (11) |
>
|
|
•
|
First, determine the power spectral density and frequencies Vectors, so that they are only calculated once:
|
>
|
|
•
|
The overall power can be found in either the time domain or the frequency domain:
|
>
|
|
>
|
|
•
|
We can consult the plot of the power spectral density versus the frequencies to see where the power is concentrated:
|
>
|
|
>
|
|
>
|
|
|
|
Audio Signal
|
|
•
|
The signal passed to BandPower can also come directly from an audio file:
|
>
|
|
| (16) |
>
|
|
| (17) |
•
|
Here, let's find the band power for frequencies between 0 and 5000, and the band power for frequencies above 5000:
|
>
|
|
| (18) |
>
|
|
| (19) |
•
|
Units can also be supplied for frequencies:
|
>
|
|
| (20) |
| (21) |
|
|
|
Compatibility
|
|
•
|
The SignalProcessing[BandPower] command was introduced in Maple 2021.
|
|
|
|