frequencyScalarFeatureOptions
Store information for converting frequency-domain feature vectors to scalar values
Since R2024b
Description
Use a frequencyScalarFeatureOptions
object to store methods to convert
frequency-domain feature vectors to scalars. You can use the resulting
frequencyScalarFeatureOptions
object to set the ScalarizationMethod
property of a signalFrequencyFeatureExtractor
object.
Creation
Description
creates
an object opts
= frequencyScalarFeatureOptionsopts
that stores the scalarization methods with default
values (empty string arrays) for all signal features in frequency domain.
specifies scalarization methods for each frequency-domain signal feature using name-value
arguments. You can specify multiple name-value arguments. For example,
opts
= frequencyScalarFeatureOptions(Name=Value
)frequencyScalarFeatureOptions(WelchPSD=["Mean"
"Energy"],PeakAmplitude="Kurtosis")
specifies "Mean"
and
"Energy"
as scalarization methods for the Welch PSD feature, and
"Kurtosis"
as the scalarization method for the peak amplitude
feature. For more information about scalarization methods, see Scalarization Methods for Domain-Specific Signal Features.
Properties
WelchPSD
— Scalarization methods for power spectral density estimate feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the power spectral density estimate feature, specified as a string array or as a cell array of character vectors.
Each element of the array corresponds to a scalarization method that you apply on the feature, if enabled. Enable signal features for extraction when creating the signalFrequencyFeatureExtractor
object.
If you specify this feature, the feature extractor object:
Associates with the feature any scalarization methods you have specified for it.
Appends any scalarization methods you have specified using the
All
name-value argument.
For more information about the power spectral density estimate feature, see pwelch
.
Example: WelchPSD = ["Mean" "Skewness"]
sets the option to extract the mean
and the skewness of the power spectral density estimate feature
vector.
Data Types: cell
| string
PeakAmplitude
— Scalarization methods for peak amplitude feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the peak amplitude feature, specified as a string array or as a cell array of character vectors.
Each element of the array corresponds to a scalarization method that you apply on the feature, if enabled. Enable signal features for extraction when creating the signalFrequencyFeatureExtractor
object.
If you specify this feature, the feature extractor object:
Associates with it any scalarization methods you have specified for it.
Appends any scalarization methods you have specified using the
All
name-value argument.
Example: PeakAmplitude = ["Mean" "Skewness"]
sets the option to extract the
mean and the skewness of the peak amplitude feature vector.
Data Types: cell
| string
All
— Scalarization methods for all signal features
strings(0)
(default) | string array | cell array
Scalarization methods for all the signal features, specified as a string array or as a cell array of character vectors.
Each element of the array corresponds to a scalarization method that you apply on all the enabled features. Enable signal features for extraction when creating the feature extractor object.
If you specify All
, the feature extractor object:
Associates the scalarization methods you have specified with all enabled features.
Appends them to the list of methods already specified for each particular feature.
Example: All = ["Mean" "PeakValue"]
sets the option to extract the mean and the peak value of all the feature vectors.
Data Types: cell
| string
Examples
Add Scalarization Methods for Frequency-Domain Feature Extraction
Create a frequencyScalarFeatureOptions
object with default values.
opts = frequencyScalarFeatureOptions
opts = frequencyScalarFeatureOptions with properties: WelchPSD: [0x0 string] PeakAmplitude: [0x0 string] All: [0x0 string]
Add scalarization methods for the power spectral density estimate and peak amplitude frequency-domain features:
opts.WelchPSD = "Energy"; opts.PeakAmplitude = ["Kurtosis" "PeakValue"];
Display the list of scalarization methods for all the frequency-domain features.
opts
opts = frequencyScalarFeatureOptions with properties: WelchPSD: "Energy" PeakAmplitude: ["Kurtosis" "PeakValue"] All: [0x0 string]
Set Scalarization Method Property in Frequency-Domain Feature Extractor Object
Create and use a frequencyScalarFeatureOptions
object to set the ScalarizationMethod
property in a signalFrequencyFeatureExtractor
object.
Specify the mean and the crest factor as scalar features for the power spectral density estimate feature in the frequency domain. Store this information in a frequencyScalarFeatureOptions
object.
opts = frequencyScalarFeatureOptions( ... WelchPSD=["Mean" "CrestFactor"]);
Create a signalTimeFrequencyFeatureExtractor
object to extract the occupied bandwidth and power spectral density estimate with its corresponding scalar values. Display the ScalarizationMethod
property of the feature extractor object.
fFE = signalFrequencyFeatureExtractor( ... OccupiedBandwidth=true,WelchPSD=true, ... ScalarizationMethod=opts); disp(fFE.ScalarizationMethod)
frequencyScalarFeatureOptions with properties: WelchPSD: ["Mean" "CrestFactor"] PeakAmplitude: [0x0 string] All: [0x0 string]
Scalar and Vector Features in Frequency Domain
Set scalarization methods to convert frequency-domain feature vectors to scalar values.
Specify "Entropy"
and "Mean"
as scalarization methods for the power spectral density estimate feature. Specify "Kurtosis"
as the scalarization method for all the enabled signal features. Store this information in a frequencyScalarFeatureOptions
object.
opts = frequencyScalarFeatureOptions( ... WelchPSD=["Entropy" "Mean"],All="Kurtosis")
opts = frequencyScalarFeatureOptions with properties: WelchPSD: ["Entropy" "Mean"] PeakAmplitude: [0x0 string] All: "Kurtosis"
Create a signalFrequencyFeatureExtractor
object to extract the band power, peak location, peak amplitude, and power spectral density estimate features. Use opts
to set the scalarization method property of the feature extractor object.
sFE = signalFrequencyFeatureExtractor( ... BandPower=true,PeakLocation=true,PeakAmplitude=true, ... WelchPSD=true,ScalarizationMethod=opts,FeatureFormat="table")
sFE = signalFrequencyFeatureExtractor with properties: Properties FrameSize: [] FrameRate: [] SampleRate: [] IncompleteFrameRule: "drop" FeatureFormat: "table" Enabled Features BandPower, WelchPSD, PeakAmplitude, PeakLocation Disabled Features MeanFrequency, MedianFrequency, OccupiedBandwidth, PowerBandwidth
Extract vectors and scalar features from a signal.
Fs = 1000; a = [1 1 0.1 0.03]; f = 60*[1 3 5 7]; t = (0:1/Fs:1)'; x = cos(2*pi*f.*t)*a'; features = extract(sFE,x);
List of extracted vector and scalar features.
T = rows2vars(features(:,[3 end-5:end])); T.Properties.VariableNames = ["Feature" "Value"]
T=7×2 table
Feature Value
_________________________ _______
{'BandPower' } 1.0054
{'WelchPSDEntropy' } 1.8607
{'WelchPSDMean' } 0.31756
{'WelchPSDKurtosis' } 39.787
{'PeakAmplitude' } 12.823
{'PeakAmplitudeKurtosis'} NaN
{'PeakLocation' } 1.129
Plot the power spectral density estimate feature.
plot(db(features.WelchPSD))
More About
Scalarization Methods for Domain-Specific Signal Features
To set the scalarization methods for features in time domain, frequency domain, or time-frequency domain, select the domain-specific feature extractor objects and scalarization method specification. Refer to the following table for the list of domain-specific features from which you can extract scalar features.
Feature domain | Feature extractor object | Scalarization method specification | Features that support scalarization |
---|---|---|---|
Time | signalTimeFeatureExtractor | timeScalarFeatureOptions object | PeakValue |
Frequency | signalFrequencyFeatureExtractor | frequencyScalarFeatureOptions object | PeakAmplitude WelchPSD |
Time-frequency | signalTimeFrequencyFeatureExtractor | timeFrequencyScalarFeatureOptions object | All time-frequency features |
For a given feature vector v with N elements, the scalarization method options convert v to a scalar s as follows.
"Mean"
— Mean, defined as the average value of v."StandardDeviation"
— Standard deviation of the elements of v, normalized by N-1."PeakValue"
— Peak value, defined as the maximum absolute value of v."Kurtosis"
— Kurtosis, defined as the ratio between the fourth moment of v and the squared second moment of v."Skewness"
— Skewness, defined as the ratio between the third moment of v and the second moment of v raised to the power of 1.5.
"ClearanceFactor"
— Clearance factor, defined as the ratio between the peak value of v and the squared mean of the square roots of the absolute values of v."CrestFactor"
— Crest factor, defined as the ratio between the peak value of v and the root-mean-square value of v."Energy"
— Energy, defined as the sum of the squared values of v."Entropy"
— Entropy, defined as the sum of plog2p values, where p is the vector of normalized squared values of v with respect to their sum.where
Note
The scalarization method
"Entropy"
is not supported for theWaveletEntropy
nor theSpectralEntropy
features."ImpulseFactor"
— Impulse factor, defined as the ratio between the peak value of v and the average absolute value of v.
Version History
Introduced in R2024b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
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)