signalFrequencyFeatureExtractor
Description
Use signalFrequencyFeatureExtractor
to extract
frequency-domain features from a signal. You can use the extracted features to train a machine
learning model or a deep learning network.
Creation
Description
creates a sFE
= signalFrequencyFeatureExtractorsignalFrequencyFeatureExtractor
object with default property
values.
specifies nondefault property values of the
sFE
= signalFrequencyFeatureExtractor(Name=Value
)signalFrequencyFeatureExtractor
object. For example,
signalFrequencyFeatureExtractor(FrameSize=30,FrameOverlapLength=6)
divides the signal into overlapping 30-sample frames and extracts features from each
frame.
Properties
Main Properties
FrameSize
— Number of samples per frame
positive integer
Number of samples per frame, specified as a positive integer. The
object divides the signal into frames of the specified length
and extracts features for each frame. If you do not specify
FrameSize
, or if you specify
FrameSize
as empty, the object
extracts features for the whole signal.
Data Types: single
| double
FrameRate
— Number of samples between start of frames
positive integer
Number of samples between the start of frames, specified as a positive integer. The frame rate
determines the distance in samples between the starting points
of frames. If you specify FrameRate
, then
you must also specify FrameSize
. If you do
not specify FrameRate
or
FrameOverlapLength
, then the
object assumes FrameRate
to be equal to
FrameSize
. You cannot specify
FrameRate
and
FrameOverlapLength
simultaneously.
Data Types: single
| double
FrameOverlapLength
— Number of overlapping samples between consecutive frames
positive integer
Number of overlapping samples between consecutive frames, specified as a positive
integer. FrameOverlapLength
must be less than or equal to the frame
size. If you specify FrameOverlapLength
, then you must also specify
FrameSize
. You cannot specify
FrameOverlapLength
and FrameRate
simultaneously.
Data Types: single
| double
SampleRate
— Sample rate
[]
(default) | positive scalar
Input sample rate, specified as a positive scalar in hertz.
If you do not specify SampleRate
, the extract
function of the object assumes the signal
sampling rate as 2π Hz.
Data Types: single
| double
FeatureFormat
— Format of generated features
"matrix"
(default) | "table"
Format of the features generated by the extract
function, specified as one of these:
"matrix"
— Columns correspond to feature values."table"
— Each table variable corresponds to a feature value.
Data Types: char
| string
IncompleteFrameRule
— Rule to handle incomplete frames
"drop"
(default) | "zeropad"
Rule to handle incomplete frames, specified as one of these:
"drop"
— Drop the incomplete frame and do not use it to compute features."zeropad"
— Zero-pad the incomplete frame and use it to compute features.
This rule applies when the current frame size is less than the specified
FrameSize
property.
Data Types: char
| string
Features to Extract
MeanFrequency
— Option to extract mean frequency
false
(default) | true
Option to extract the mean frequency of the power spectrum, specified as
true
or false
. If you specify
MeanFrequency
as true, the signalFrequencyFeatureExtractor
object
extracts the mean frequency of the power spectrum and appends it to the features
returned by the extract
function.
Data Types: logical
MedianFrequency
— Option to extract median frequency
false
(default) | true
Option to extract the median frequency of the power spectrum, specified as
true
or false
. If you specify
MedianFrequency
as true, the signalFrequencyFeatureExtractor
object extracts the median frequency of the power spectrum and appends it to the
features returned by the extract
function.
Data Types: logical
BandPower
— Option to extract average band power
false
(default) | true
Option to extract the average band power, specified as true
or
false
. If you specify BandPower
as true, the
signalFrequencyFeatureExtractor
object extracts the band power and appends it to the
features returned by the extract
function.
Data Types: logical
OccupiedBandwidth
— Option to extract occupied bandwidth
false
(default) | true
Option to extract the 99% occupied bandwidth, specified as true
or false
. If you specify OccupiedBandwidth
as
true, the signalFrequencyFeatureExtractor
object extracts the 99% occupied bandwidth and
appends it to the features returned by the extract
function.
To set parameters of the occupied bandwidth extraction, use setExtractorParameters
.
setExtractorParameters(sFE,"OccupiedBandwidth",Name=Value)
Settable parameters for the occupied bandwidth extraction are:
Percentage
— Power percentage, specified as a positive integer between0
and100
.
Data Types: logical
PowerBandwidth
— Option to extract half-power bandwidth
false
(default) | true
Option to extract the 3 dB (half-power) bandwidth, specified as
true
or false
. If you specify
PowerBanwidth
as true, the signalFrequencyFeatureExtractor
object
extracts the 3 dB bandwidth value and appends it to the features returned by the
extract
function.
To set parameters of the half-power bandwidth extraction, use setExtractorParameters
.
setExtractorParameters(sFE,"PowerBandwidth",Name=Value)
Settable parameters for the half-power bandwidth extraction are:
RelativeAmplitude
— Relative amplitude, specified as an integer.
Data Types: logical
WelchPSD
— Option to extract power spectral density estimate
false
(default) | true
Option to extract the power spectral density (PSD) estimate, specified as
true
or false
. If you specify
WelchPSD
as true, the signalFrequencyFeatureExtractor
object
extracts the PSD estimate using Welch's method and appends it to the features returned
by the extract
function.
To set parameters of the Welch's PSD estimate, use setExtractorParameters
.
setExtractorParameters(sFE,"WelchPSD",Name=Value)
Settable parameters for the Welch's PSD estimate extraction are:
FFTLength
— Number of DFT points, specified as a positive integer.FrequencyVector
— Frequencies at which the PSD is estimated, specified as a vector with at least two elements. You can specifyFrequencyVector
only whenFFTLength
is not specified.OverlapLength
— Number of overlapping samples, specified as a positive integer.Window
— Window, specified as a scalar or vector.
Data Types: logical
PeakAmplitude
— Option to extract peak amplitude
false
(default) | true
Option to extract the peak spectral amplitudes, specified as
true
or false
. If you specify
PeakAmplitude
as true, the signalFrequencyFeatureExtractor
object
extracts the peak amplitudes of the computed Welch PSD estimate and appends them to
the features returned by the extract
function.
To set parameters of the peak amplitude extraction, use setExtractorParameters
.
setExtractorParameters(sFE,"PeakAmplitude",Name=Value)
Settable parameters for the peak amplitude extraction are:
PeakType
— Type of peak, specified as"minima"
or"maxima"
.MaxNumExtrema
— Maximum number of peaks, specified as a positive integer scalar.MinProminence
— Minimum prominence, specified as a positive scalar. The object returns only peaks whose prominence is at least the value specified.MinSeparation
— Minimum separation between peaks, specified as a positive scalar.FlatSelection
— Flat region indicator, specified as one of these:"center"
— Indicate only the center element of a flat region as the peak."first"
— Indicate only the first element of a flat region as the peak."last"
— Indicate only the last element of a flat region as the peak."all"
— Indicate all elements of a flat region as the peak.
Data Types: logical
PeakLocation
— Option to extract peak location
false
(default) | true
Option to extract the spectral peak locations, specified as
true
or false
. If you specify
PeakLocation
as true, the signalFrequencyFeatureExtractor
object
extracts the peak locations of the computed Welch PSD estimate and appends them to the
features returned by the extract
function.
To set parameters of the peak location extraction, use setExtractorParameters
.
setExtractorParameters(sFE,"PeakLocation",Name=Value)
Settable parameters for the peak location extraction are:
PeakType
— Type of peak, specified as"minima"
or"maxima"
.MaxNumExtrema
— Maximum number of peaks, specified as a positive integer scalar.MinProminence
— Minimum prominence, specified as a positive scalar. ThesetExtractorParameters
function returns only peaks whose prominence is at least the value specified.MinSeparation
— Minimum separation between peaks, specified as a positive scalar.FlatSelection
— Flat region indicator, specified as one of these:"center"
— Indicate only the center element of a flat region as the peak."first"
— Indicate only the first element of a flat region as the peak."last"
— Indicate only the last element of a flat region as the peak."all"
— Indicate all elements of a flat region as the peak.
Data Types: logical
Note
To compute frequency features, signalFrequencyFeatureExtractor
first
estimates the PSD of the input time-domain signal using Welch's method. The object uses
the computed Welch PSD and corresponding frequency vector to compute the specified
features. You can configure the computed Welch PSD estimate using the setExtractorParameters
function.
Object Functions
extract | Extract time-domain, frequency-domain, or time-frequency-domain features |
generateMATLABFunction | Create MATLAB function compatible with C/C++ code generation |
getExtractorParameters | Get current parameter values of feature extractor object |
setExtractorParameters | Set nondefault parameter values for feature extractor object |
Examples
Extract Frequency-Domain Features From Signal
Generate 1024 samples of a chirp sampled at 1024 kHz. The chirp has an initial frequency of 50 kHz and reaches 100 kHz at the end of the sampling. Add white Gaussian noise such that the signal-to-noise ratio is 40 dB. Plot the power spectral density (PSD) and annotate the mean frequency and occupied bandwidth of the signal.
nSamp = 1024; Fs = 1024e3; SNR = 40; t = (0:nSamp-1)'/Fs; x0 = chirp(t,50e3,nSamp/Fs,100e3); x = x0+randn(size(x0))*std(x0)/db2mag(SNR); [pxx,f]= pwelch(x,[],[],[],Fs); obw(pxx,f); m = meanfreq(pxx,f); xline(m/1000,"--", ... "Mean Frequency Estimate: "+m/1000+" kHz")
Create a signalFrequencyFeatureExtractor
object to extract the mean frequency, 99% occupied bandwidth, and 3 dB bandwidth of the signal.
sFE = signalFrequencyFeatureExtractor(SampleRate=Fs, ...
MeanFrequency=true,OccupiedBandwidth=true,PowerBandwidth=true)
sFE = signalFrequencyFeatureExtractor with properties: Properties FrameSize: [] FrameRate: [] SampleRate: 1024000 IncompleteFrameRule: "drop" FeatureFormat: "matrix" Enabled Features MeanFrequency, OccupiedBandwidth, PowerBandwidth Disabled Features MedianFrequency, BandPower, WelchPSD, PeakAmplitude, PeakLocation
Call the extract
function to extract the specified features.
[features,info] = extract(sFE,x)
features = 1×3
104 ×
7.2252 4.3783 3.7773
info = struct with fields:
MeanFrequency: 1
OccupiedBandwidth: 2
PowerBandwidth: 3
To view the extracted features in a table, modify the FeatureFormat
property of the object.
sFE.FeatureFormat = "table";
featureTable = extract(sFE,x)
featureTable=1×5 table
FrameStartTime FrameEndTime MeanFrequency OccupiedBandwidth PowerBandwidth
______________ ____________ _____________ _________________ ______________
1 1024 72252 43783 37773
You can use the getExtractorParameters
function to view parameters used to compute a specified feature. The occupied bandwidth measures the bandwidth containing 99% of the total power for the input signal by default. Use the setExtractorParameters
function to change the percentage to 95% and extract the specified features again.
params = getExtractorParameters(sFE,'OccupiedBandwidth')
params = struct with fields:
Percentage: []
params.Percentage = 95;
setExtractorParameters(sFE,'OccupiedBandwidth',params)
featuresTable2 = extract(sFE,x)
featuresTable2=1×5 table
FrameStartTime FrameEndTime MeanFrequency OccupiedBandwidth PowerBandwidth
______________ ____________ _____________ _________________ ______________
1 1024 72252 39840 37773
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
You cannot generate code directly from
signalFrequencyFeatureExtractor
. You can generate C/C++ code from the function returned bygenerateMATLABFunction
.
GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.
This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).
Version History
Introduced in R2021bR2023a: Use gpuArray
inputs
The signalFrequencyFeatureExtractor
object supports gpuArray
inputs. You
must have Parallel Computing Toolbox™ to use this functionality.
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)