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 frequencyScalarFeatureOptions object to set the ScalarizationMethod property of a signalFrequencyFeatureExtractor object.

Creation

Syntax

opts = frequencyScalarFeatureOptions

opts = frequencyScalarFeatureOptions(PropertyName=Value)

Description

opts = frequencyScalarFeatureOptions creates an object opts that stores the scalarization methods with default values (empty string arrays) for all signal features in frequency domain.

opts = frequencyScalarFeatureOptions(PropertyName=Value) specifies scalarization methods for each frequency-domain signal feature using name-value arguments. You can specify multiple name-value arguments. For example, 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 Frequency-Domain 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 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:

1. Applies the scalarization methods associated with the feature.

2. 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 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:

• 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:

• 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

Examples

Add Scalarization Methods for Frequency-Domain Feature Extraction

Create a frequencyScalarFeatureOptions object with default values.

opts = frequencyScalarFeatureOptions

opts = 
  frequencyScalarFeatureOptions with properties:

         WelchPSD: [0×0 string]
    PeakAmplitude: [0×0 string]
              All: [0×0 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: [0×0 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: [0×0 string]
              All: [0×0 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: [0×0 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"
    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(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 Frequency-Domain Features

To set the methods for extracting scalar values from feature vectors in the frequency domain, set the scalarization method property of a signalFrequencyFeatureExtractor object with a frequencyScalarFeatureOptions object.

These frequency-domain features support scalarization: PeakAmplitude and WelchPSD.

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.

  $$s=\overline{v}=\frac{1}{N}{\displaystyle \sum _{i=1}^N{v}_i}$$

• "StandardDeviation" — Standard deviation of the elements of v, normalized by N-1.

  $$s=\sqrt{\frac{1}{N-1}{\displaystyle \sum _{i=1}^N|v_i-\overline{v}{|}^2}}$$

• "PeakValue" — Peak value, defined as the maximum absolute value of v.

  $$s=v_p=\underset{i}{\max }\left|v_i\right|$$

• "Kurtosis" — Kurtosis, defined as the ratio between the fourth moment of v and the squared second moment of v.

  $$s=\frac{\frac{1}{N}{\displaystyle \sum _{i=1}^N{(v_i-\overline{v})}^4}}{{\left[\frac{1}{N}{\displaystyle \sum _{i=1}^N{(v_i-\overline{v})}^2}\right]}^2}$$

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

  $$s=\frac{\frac{1}{N}{\displaystyle \sum _{i=1}^N{(v_i-\overline{v})}^3}}{{\left[\frac{1}{N}{\displaystyle \sum _{i=1}^N{(v_i-\overline{v})}^2}\right]}^{3/2}}$$

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

  $$s=\frac{v_p}{{\left(\frac{1}{N}{\displaystyle \sum _{i=1}^N\sqrt{\left|v_i\right|}}\right)}^2}$$

• "CrestFactor" — Crest factor, defined as the ratio between the peak value of v and the root-mean-square value of v.

  $$s=\frac{v_p}{\sqrt{\frac{1}{N}{\displaystyle \sum _{i=1}^N{v}_i{}^2}}}$$

• "ImpulseFactor" — Impulse factor, defined as the ratio between the peak value of v and the average absolute value of v.

  $$s=\frac{v_p}{\frac{1}{N}{\displaystyle \sum _{i=1}^N\left|v_i\right|}}$$

• "Energy" — Energy, defined as the sum of the squared values of v.

  $$s={\displaystyle \sum _{i=1}^N{v}_i{}^2}$$

• "Entropy" — Entropy, defined as the sum of plog₂p values, where p is the vector of normalized squared values of v with respect to their sum.

  $$s={\displaystyle \sum _{i=1}^N{p}_i{\log }_2{p}_i},$$

  where

  $$p=\frac{v^2}{{\displaystyle \sum _{i=1}^N{v}_i{}^2}}.$$

Version History

Introduced in R2024b