setScalarizationMethods

Set scalarization methods for domain-specific signal features

Since R2024a

Syntax

setScalarizationMethods(sFE,featurename)

setScalarizationMethods(sFE,featurename,params)

Description

setScalarizationMethods(sFE,featurename) sets the ScalarizationMethod property of the signalTimeFrequencyFeatureExtractor object sFE by specifying an empty list of scalarization methods for the signal feature featurename.

setScalarizationMethods(sFE,featurename,params) sets scalarization methods params for the signal feature featurename in the ScalarizationMethod property of the signalTimeFrequencyFeatureExtractor object sFE.

Examples

Scalar Feature Extraction Using Scalarization Methods

Extract the spectral kurtosis and spectral crest from the Fourier synchrosqueezed transform of a sinusoidal signal. Set scalarization methods to extract the impulse factor and peak value for the spectral kurtosis feature.

Create a time-frequency feature extractor object that returns the spectral kurtosis and spectral crest features from the Fourier synchrosqueezed transform of a sinusoidal signal.

x = sin(2*pi*(0:0.1:1));
tfFE = signalTimeFrequencyFeatureExtractor( ...
    Transform="synchrosqueezedspectrogram", ...
    SpectralKurtosis=true,SpectralCrest=true);

Specify the scalarization methods to the time-frequency feature extractor object to extract the impulse factor and peak value for the spectral kurtosis feature. This operation sets up the ScalarizationMethod property in tfFE.

setScalarizationMethods(tfFE,"SpectralKurtosis",...
                            ImpulseFactor=true,PeakValue=true)
disp(tfFE.ScalarizationMethod)

  timeFrequencyScalarFeatureOptions with properties:

          SpectralKurtosis: [2×1 string]
          SpectralSkewness: [0×0 string]
             SpectralCrest: [0×0 string]
          SpectralFlatness: [0×0 string]
           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: [0×0 string]

Extract the vector and scalar features from the Fourier synchrosqueezed transform of x. Display the indices corresponding to the extracted features from the returned feature matrix. The feature extraction returns the spectral kurtosis vector followed by the impulse factor and the peak value scalar features, and then appends the spectral crest vector.

  [features,info] = extract(tfFE,x);
  info

info = struct with fields:
                 SpectralKurtosis: [1 2 3 4 5 6 7 8 9 10 11]
    SpectralKurtosisImpulseFactor: 12
        SpectralKurtosisPeakValue: 13
                    SpectralCrest: [14 15 16 17 18 19 20 21 22 23 24]

Input Arguments

sFE — Feature extractor object

signalTimeFrequencyFeatureExtractor object

Feature extractor object, specified as a signalTimeFrequencyFeatureExtractor object.

featurename — Signal feature name

string scalar | character vector

Name of the signal feature, specified as a string scalar or a character vector.

Data Types: char | string

params — Scalarization methods

name-value arguments | structure array

Scalarization methods associated with featurename, specified as name-value arguments or a structure array. You can specify multiple name-value arguments.

• Specify params as name-value arguments, where:

  • Name — Name of the scalarization method. Specify Name as ClearanceFactor, Mean, CrestFactor, PeakValue, ImpulseFactor, Energy, StandardDeviation, Kurtosis, Skewness, or Entropy. For more information, see Scalarization Methods for Domain-Specific Signal Features.

  • Value — Logical value of the scalarization method. Specify Value as either true or false.

• Specify params as a struct array, where the field name is the name of the scalarization method and the value is either true or false.

Note

The scalarization method Entropy is not supported if you specify featurename as either WaveletEntropy or SpectralEntropy.

Example: setScalarizationMethods(sFE,"SpectralCrest",PeakValue=true,Mean=true) and setScalarizationMethods(sFE,"SpectralCrest",struct("PeakValue",true,"Mean",true)) set the peak value and the mean as scalarization methods for the spectral crest feature in the signalTimeFrequencyFeatureExtractor object sFE using name-value arguments and structure arrays, respectively.

More About

Scalarization Methods for Domain-Specific Signal Features

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.

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.

All Signal Domains

• "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}}$$

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.

  $$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}}.$$

Note

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

Tips

• Use the getScalarizationMethods function to return the list of scalarization methods for the features that you enabled when creating the feature extractor object.

Version History

Introduced in R2024a