scalarFeatureOptions - Store information for converting feature vectors to scalar values - MATLAB (original) (raw)

Store information for converting feature vectors to scalar values

Since R2024a

Syntax

Description

[opts](#mw%5F170d74b4-585b-4994-a1fd-034ff1df3fa1) = scalarFeatureOptions creates an objectopts that stores the scalarization methods for all the time-frequency-domain features with default values (empty string arrays). You can use the object to set the ScalarizationMethod property of a signalTimeFrequencyFeatureExtractor object.

[opts](#mw%5F170d74b4-585b-4994-a1fd-034ff1df3fa1) = scalarFeatureOptions([domain](#mw%5F4f3f0166-3d1b-47e8-8130-8768a6e8928f)) creates an object opts that stores the scalarization methods for all the signal features from a domain representation with default values (empty string arrays).

[opts](#mw%5F170d74b4-585b-4994-a1fd-034ff1df3fa1) = scalarFeatureOptions([domain](#mw%5F4f3f0166-3d1b-47e8-8130-8768a6e8928f),[Name=Value](#namevaluepairarguments)) specifies scalarization methods for each signal feature in the signal domain using name-value arguments.

example

Examples

collapse all

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(2pi/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

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: [0×0 string]
      SpectralSkewness: [0×0 string]
         SpectralCrest: [0×0 string]
      SpectralFlatness: ["Entropy"    "Mean"]
       SpectralEntropy: [0×0 string]
              TFRidges: [0×0 string]
InstantaneousBandwidth: [0×0 string]
InstantaneousFrequency: [0×0 string]
   InstantaneousEnergy: [0×0 string]
    MeanEnvelopeEnergy: [0×0 string]
          TimeSpectrum: [0×0 string]
        WaveletEntropy: [0×0 string]
         ScaleSpectrum: [0×0 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: [1×1 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

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: [0×0 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" ScalarizationMethod: [1×1 frequencyScalarFeatureOptions]

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(2pif.*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))

Figure contains an axes object. The axes object contains an object of type line.

Input Arguments

collapse all

Domain of signal, specified as one of these:

"timefrequency" — You can use the resultingtimeFrequencyScalarFeatureOptions object to set theScalarizationMethod property of a signalTimeFrequencyFeatureExtractor object.
"time" — You can use the resulting timeScalarFeatureOptions object to set theScalarizationMethod property of a signalTimeFeatureExtractor object. (since R2024b)
"frequency" — You can use the resulting frequencyScalarFeatureOptions object to set the ScalarizationMethod property of a signalFrequencyFeatureExtractor object. (since R2024b)

Data Types: char | string

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=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 a domain-specific signal feature name. For example, when domain 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 signal domain.
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 Domain (since R2024b)

Scalarization methods for the peak value feature vector, 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:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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)

Scalarization methods for the power spectral density estimate feature vector, 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:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the peak amplitude feature vector, specified as a string array or as a cell array of character vectors.

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

Time-Frequency Domain

Scalarization methods for the spectral kurtosis feature vector, 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 thesignalTimeFrequencyFeatureExtractor object.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the spectral skewness feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the spectral crest feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the spectral flatness feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the spectral entropy feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the time-frequency ridges feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the instantaneous bandwidth feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the instantaneous frequency feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the instantaneous energy feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the mean envelope energy feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the wavelet entropy feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the time-averaged wavelet spectrum feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Scalarization methods for the scale-averaged wavelet spectrum feature vector, specified as a string array or as a cell array of character vectors.

If you specify this feature, the feature extractor object:

Applies the scalarization methods associated with the feature.
Appends any scalarization methods you have specified using theAll 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

Any Domain

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:

Applies the scalarization methods associated 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

collapse all

List of features and their corresponding scalarization methods, returned as atimeFrequencyScalarFeatureOptions 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

collapse all

To set the methods for extracting scalar values from feature vectors in the time domain, frequency domain, or time-frequency domain, set the scalarization method property of the domain-specific feature extractor object with the corresponding scalarization method specification object. Refer to this table for the list of domain-specific features from which you can extract scalar features.

For a given feature vector v with N elements, the scalarization method options convert v to a scalar s as follows.

All Signal Domains

"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.

Frequency and Time-Frequency Signal Domains

"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.
"ImpulseFactor" — Impulse factor, defined as the ratio between the peak value of v and the average absolute value of_v_.
"Energy" — Energy, defined as the sum of the squared values of v.
"Entropy" — Entropy, defined as the sum of p_log2_p values, where p is the vector of normalized squared values of v with respect to their sum.
where

Note

The WaveletEntropy and SpectralEntropy time-frequency features do not support the "Entropy" scalarization method.

Version History

Introduced in R2024a

expand all

The scalarFeatureOptions function supports storing scalarization methods for signal features in time domain and frequency domain.

scalarFeatureOptions - Store information for converting feature vectors to scalar values - MATLAB (original) (raw)

Syntax

Description

Examples

Input Arguments

Name-Value Arguments

Output Arguments

More About

Version History

See Also

Objects