scalarFeatureOptions
Syntax
Description
creates an object
opts
= scalarFeatureOptionsopts
that stores the scalarization methods for all the
time-frequency-domain features with default values (empty string arrays). You can use the
resulting object to set the ScalarizationMethod
property of a signalTimeFrequencyFeatureExtractor
object.
specifies scalarization methods for each signal feature in the signal domain using
name-value arguments.opts
= scalarFeatureOptions(domain
,Name=Value
)
Examples
Extract Signal Features in Time-Frequency Domain
Specify the impulse factor and peak value as scalarization methods for the instantaneous frequency feature.
opts = scalarFeatureOptions("timefrequency",... InstantaneousFrequency=["ImpulseFactor" "PeakValue"]);
Create a time-frequency feature extractor that returns the desired scalar features using the empirical mode decomposition (EMD) transform.
tfFE = signalTimeFrequencyFeatureExtractor(Transform="emd", ... InstantaneousFrequency=true,ScalarizationMethod=opts);
Extract the instantaneous frequency vector feature and the desired scalar features from the EMD transform of a sinusoidal signal.
x = sin(2*pi/5*(0:1:7)); [features,info] = extract(tfFE,x)
features = 1×10
1.0165 1.0416 1.0887 1.1918 1.2957 1.2502 1.0863 0.9903 1.1567 1.2957
info = struct with fields:
InstantaneousFrequency: [1 2 3 4 5 6 7 8]
InstantaneousFrequencyImpulseFactor: 9
InstantaneousFrequencyPeakValue: 10
Vector and Scalar Features in Time-Frequency Domain
Set scalarization methods and use for converting time-frequency feature vectors to scalar values.
Specify 'Entropy'
and 'Mean'
as scalarization methods for the spectral flatness feature. Specify 'Kurtosis'
as the scalarization method for all the enabled signal features. Store this information in a timeFrequencyScalarFeatureOptions
object.
opts = scalarFeatureOptions("timefrequency", ... SpectralFlatness=["Entropy" "Mean"],All="Kurtosis")
opts = timeFrequencyScalarFeatureOptions with properties: SpectralKurtosis: [0x0 string] SpectralSkewness: [0x0 string] SpectralCrest: [0x0 string] SpectralFlatness: ["Entropy" "Mean"] SpectralEntropy: [0x0 string] TFRidges: [0x0 string] InstantaneousBandwidth: [0x0 string] InstantaneousFrequency: [0x0 string] InstantaneousEnergy: [0x0 string] MeanEnvelopeEnergy: [0x0 string] TimeSpectrum: [0x0 string] WaveletEntropy: [0x0 string] ScaleSpectrum: [0x0 string] All: "Kurtosis"
Create a signalTimeFrequencyFeatureExtractor
object to extract the spectral crest, spectral flatness, and time-frequency ridges features. Use opts
to set the scalarization method property of the feature extractor object.
sFE = signalTimeFrequencyFeatureExtractor( ... SpectralCrest=true,SpectralFlatness=true, ... TFRidges=true,ScalarizationMethod=opts)
sFE = signalTimeFrequencyFeatureExtractor with properties: Properties FrameSize: [] FrameRate: [] SampleRate: [] IncompleteFrameRule: "drop" FeatureFormat: "matrix" Transform: "Spectrogram" ScalarizationMethod: [1x1 timeFrequencyScalarFeatureOptions] Enabled Features SpectralCrest, SpectralFlatness, TFRidges Disabled Features SpectralKurtosis, SpectralSkewness, SpectralEntropy, InstantaneousBandwidth, InstantaneousFrequency, MeanEnvelopeEnergy InstantaneousEnergy, WaveletEntropy, TimeSpectrum, ScaleSpectrum
Extract vectors and scalar features from the spectrogram of a signal. Observe the list of extracted features.
x = exp(-(-4.5:0.15:4.5).^2); [features,indices] = extract(sFE,x); disp(indices)
SpectralCrest: [1 2 3 4 5] SpectralCrestKurtosis: 6 SpectralFlatness: [7 8 9 10 11] SpectralFlatnessEntropy: 12 SpectralFlatnessMean: 13 SpectralFlatnessKurtosis: 14 TFRidges: [15 16 17 18 19] TFRidgesKurtosis: 20
Vector and Scalar Features in Frequency Domain
Since R2024b
Set scalarization methods to convert frequency-domain feature vectors to scalar values.
Specify "Entropy"
and "CrestFactor"
as scalarization methods for the power spectral density estimate feature. Specify "Skewness"
as the scalarization method for all the enabled signal features. Store this information in a scalarFeatureOptions
object.
opts = scalarFeatureOptions("frequency", ... WelchPSD=["Entropy" "CrestFactor"],All="Skewness")
opts = frequencyScalarFeatureOptions with properties: WelchPSD: ["Entropy" "CrestFactor"] PeakAmplitude: [0x0 string] All: "Skewness"
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
{'WelchPSDCrestFactor' } 7.4767
{'WelchPSDSkewness' } 6.0192
{'PeakAmplitude' } 12.823
{'PeakAmplitudeSkewness'} NaN
{'PeakLocation' } 1.129
Plot the power spectral density estimate feature.
plot(db(features.WelchPSD))
Input Arguments
domain
— Domain of signal
"timefrequency"
(default) | "time"
| "frequency"
Domain of signal, specified as one of these:
"timefrequency"
— You can use the resultingtimeFrequencyScalarFeatureOptions
object to set theScalarizationMethod
property of asignalTimeFrequencyFeatureExtractor
object."time"
— You can use the resultingtimeScalarFeatureOptions
object to set theScalarizationMethod
property of asignalTimeFeatureExtractor
object. (since R2024b)"frequency"
— You can use the resultingfrequencyScalarFeatureOptions
object to set theScalarizationMethod
property of asignalFrequencyFeatureExtractor
object. (since R2024b)
Data Types: char
| string
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: scalarFeatureOptions("timefrequency",SpectralCrest=["Mean"
"CrestFactor"])
sets scalarization methods to extract the mean and crest factor
from the spectral crest feature vector of the time-frequency representation of a
signal.
Each
Name
in the name-value arguments that you specify must correspond to adomain
-specific signal feature name. For example, whendomain
is"frequency"
, the name-value arguments must correspond to frequency-domain signal features. You can also specifyAll
to set scalarization methods for all enabled features in the signaldomain
.Each element of the
Value
in the name-value arguments that you specify must correspond with scalarization methods specific to the signal feature. For more information about scalarization methods, see Scalarization Methods for Domain-Specific Signal Features.
Time-Frequency Domain
SpectralKurtosis
— Scalarization methods for spectral kurtosis feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the spectral kurtosis 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
signalTimeFrequencyFeatureExtractor
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 spectral kurtosis feature, see spectralKurtosis
.
Example: SpectralKurtosis = ["Mean" "PeakValue"]
sets the option
to extract the mean and the peak value of the spectral kurtosis feature
vector.
Data Types: cell
| string
SpectralSkewness
— Scalarization methods for spectral skewness feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the spectral skewness 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
signalTimeFrequencyFeatureExtractor
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 spectral skewness feature, see spectralSkewness
.
Example: SpectralSkewness = ["Mean" "PeakValue"]
sets the option
to extract the mean and the peak value of the spectral skewness feature
vector.
Data Types: cell
| string
SpectralCrest
— Scalarization methods for spectral crest feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the spectral crest 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
signalTimeFrequencyFeatureExtractor
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 spectral crest feature, see spectralCrest
.
Example: SpectralCrest = ["Mean" "PeakValue"]
sets the option to
extract the mean and the peak value of the spectral crest feature
vector.
Data Types: cell
| string
SpectralFlatness
— Scalarization methods for spectral flatness feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the spectral flatness 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
signalTimeFrequencyFeatureExtractor
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 spectral flatness feature, see spectralFlatness
.
Example: SpectralFlatness = ["Mean" "PeakValue"]
sets the option
to extract the mean and the peak value of the spectral flatness feature
vector.
Data Types: cell
| string
SpectralEntropy
— Scalarization methods for spectral entropy feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the spectral entropy 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
signalTimeFrequencyFeatureExtractor
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 spectral entropy feature, see spectralEntropy
.
Example: SpectralEntropy = ["Mean" "PeakValue"]
sets the option
to extract the mean and the peak value of the spectral entropy feature
vector.
Data Types: cell
| string
TFRidges
— Scalarization methods for time-frequency ridges feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the time-frequency ridges 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
signalTimeFrequencyFeatureExtractor
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 time-frequency ridge feature, see tfridge
.
Example: TFRidges = ["Mean" "PeakValue"]
sets the option to
extract the mean and the peak value of the time-frequency ridge feature
vector.
Data Types: cell
| string
InstantaneousBandwidth
— Scalarization methods for instantaneous bandwidth feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the instantaneous bandwidth 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
signalTimeFrequencyFeatureExtractor
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 instantaneous bandwidth feature, see instbw
.
Example: InstantaneousBandwidth = ["Mean" "PeakValue"]
sets the
option to extract the mean and the peak value of the instantaneous bandwidth feature
vector.
Data Types: cell
| string
InstantaneousFrequency
— Scalarization methods for instantaneous frequency feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the instantaneous frequency 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
signalTimeFrequencyFeatureExtractor
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 instantaneous frequency feature, see instfreq
or hht
.
Example: InstantaneousFrequency = ["Mean" "PeakValue"]
sets the
option to extract the mean and the peak value of the instantaneous frequency feature
vector.
Data Types: cell
| string
InstantaneousEnergy
— Scalarization methods for instantaneous energy feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the instantaneous energy 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
signalTimeFrequencyFeatureExtractor
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 instantaneous energy feature, see hht
.
Example: InstantaneousEnergy = ["Mean" "PeakValue"]
sets the
option to extract the mean and the peak value of the instantaneous energy feature
vector.
Data Types: cell
| string
MeanEnvelopeEnergy
— Scalarization methods for mean envelope energy feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the mean envelope energy 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
signalTimeFrequencyFeatureExtractor
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 mean envelope energy feature, see emd
.
Example: MeanEnvelopeEnergy = ["Mean" "PeakValue"]
sets the
option to extract the mean and the peak value of the mean envelope energy feature
vector.
Data Types: cell
| string
WaveletEntropy
— Scalarization methods for wavelet entropy feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the wavelet entropy 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
signalTimeFrequencyFeatureExtractor
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 wavelet entropy feature, see wentropy
(Wavelet Toolbox).
Example: WaveletEntropy = ["Mean" "PeakValue"]
sets the option
to extract the mean and the peak value of the wavelet entropy feature
vector.
Data Types: cell
| string
TimeSpectrum
— Scalarization methods for time-averaged wavelet spectrum feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the time-averaged wavelet spectrum 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
signalTimeFrequencyFeatureExtractor
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 time spectrum feature, see timeSpectrum
(Wavelet Toolbox).
Example: TimeSpectrum = ["Mean" "PeakValue"]
sets the option to
extract the mean and the peak value of the time spectrum feature
vector.
Data Types: cell
| string
ScaleSpectrum
— Scalarization methods for scale-averaged wavelet spectrum feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the scale-averaged wavelet spectrum 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
signalTimeFrequencyFeatureExtractor
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 scale spectrum feature, see scaleSpectrum
(Wavelet Toolbox).
Example: ScaleSpectrum = ["Mean" "PeakValue"]
sets the option to
extract the mean and the peak value of the scale spectrum feature
vector.
Data Types: cell
| string
Time Domain (since R2024b)
PeakValue
— Scalarization methods for peak value feature vector
strings(0)
(default) | string array | cell array
Scalarization methods for the peak value 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 signalTimeFeatureExtractor
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.
Example: PeakValue = ["Mean" "Skewness"]
sets the option to extract the mean
and the skewness of the peak value feature vector.
Data Types: cell
| string
Frequency Domain (since R2024b)
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
Any Domain
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
Output Arguments
opts
— List of features and scalarization methods
timeFrequencyScalarFeatureOptions
object | timeScalarFeatureOptions
object | frequencyScalarFeatureOptions
object
List of features and their corresponding scalarization methods, returned as a
timeFrequencyScalarFeatureOptions
object,
timeScalarFeatureOptions
object,
frequencyScalarFeatureOptions
object.
By default, the scalarFeatureOptions
function sets the scalarization
method for each feature to an empty string array. In this case, the extract
function of the feature extractor returns the feature vectors without converting them to
scalar values.
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 R2024aR2024b: Store scalarization methods in time domain and frequency domain
The scalarFeatureOptions
function supports storing scalarization methods for
signal features in time domain and frequency domain.
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)