timeFrequencyScalarFeatureOptions

Store information for converting time-frequency-domain feature vectors to scalar values

Since R2024a

Description

Use a timeFrequencyScalarFeatureOptions object to store methods to convert time-frequency-domain feature vectors to scalars. You can use the timeFrequencyScalarFeatureOptions object to set the ScalarizationMethod property of a signalTimeFrequencyFeatureExtractor object.

Creation

Syntax

opts = timeFrequencyScalarFeatureOptions

opts = timeFrequencyScalarFeatureOptions(PropertyName=Value)

Description

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

example

opts = timeFrequencyScalarFeatureOptions(PropertyName=Value) specifies scalarization methods for each time-frequency domain signal feature using name-value arguments. You can specify multiple name-value arguments. For example, timeFrequencyScalarFeatureOptions(SpectralCrest=["Mean" "Energy"],TFRidges="Kurtosis") specifies "Mean" and "Energy" as scalarization methods for the spectral crest feature, and "Kurtosis" as the scalarization method for the time-frequency ridge feature. For more information about scalarization methods, see Scalarization Methods for Time-Frequency Features.

example

Properties

expand all

`SpectralKurtosis` — Scalarization methods for spectral kurtosis feature vector
`strings(0)` (default) | string array | cell array

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 the signalTimeFrequencyFeatureExtractor 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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

`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

collapse all

Add Scalarization Methods for Time-Frequency Feature Extraction

Open Live Script

Create a timeFrequencyScalarFeatureOptions object with default values.

opts = timeFrequencyScalarFeatureOptions

opts = 
  timeFrequencyScalarFeatureOptions with properties:

          SpectralKurtosis: [0×0 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]

Add scalarization methods for the spectral flatness and mean envelope energy time-frequency domain features.

opts.SpectralFlatness = "Energy";
opts.MeanEnvelopeEnergy = ["Kurtosis" "PeakValue"];

Display the list of scalarization methods for all the time-frequency features.

opts

opts = 
  timeFrequencyScalarFeatureOptions with properties:

          SpectralKurtosis: [0×0 string]
          SpectralSkewness: [0×0 string]
             SpectralCrest: [0×0 string]
          SpectralFlatness: "Energy"
           SpectralEntropy: [0×0 string]
                  TFRidges: [0×0 string]
    InstantaneousBandwidth: [0×0 string]
    InstantaneousFrequency: [0×0 string]
       InstantaneousEnergy: [0×0 string]
        MeanEnvelopeEnergy: ["Kurtosis"    "PeakValue"]
              TimeSpectrum: [0×0 string]
            WaveletEntropy: [0×0 string]
             ScaleSpectrum: [0×0 string]
                       All: [0×0 string]

Set Scalarization Method Property in Time-Frequency Feature Extractor Object

Open Live Script

Create and use a timeFrequencyScalarFeatureOptions object to set the ScalarizationMethod property in a signalTimeFrequencyFeatureExtractor object.

Specify the mean and the crest factor as scalar features for the spectral crest time-frequency feature. Store this information in a timeFrequencyScalarFeatureOptions object.

opts  = timeFrequencyScalarFeatureOptions( ...
    SpectralCrest=["Mean" "CrestFactor"]);

Create a signalTimeFrequencyFeatureExtractor object to extract the spectral crest and time-frequency ridges with their corresponding scalar values. Display the ScalarizationMethod property of the feature extractor object.

tfFE = signalTimeFrequencyFeatureExtractor( ...
    SpectralCrest=true,TFRidges=true, ...
    ScalarizationMethod=opts);
disp(tfFE.ScalarizationMethod)

  timeFrequencyScalarFeatureOptions with properties:

          SpectralKurtosis: [0×0 string]
          SpectralSkewness: [0×0 string]
             SpectralCrest: ["Mean"    "CrestFactor"]
          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]

Scalar and Vector Features in Time-Frequency Domain

Open Live Script

Set scalarization methods to convert time-frequency-domain 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 = timeFrequencyScalarFeatureOptions( ...
    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

More About

expand all

Scalarization Methods for Time-Frequency Features

To set the methods for extracting scalar values from feature vectors in the time-frequency domain, set the scalarization method property of a signalTimeFrequencyFeatureExtractor object with a timeFrequencyScalarFeatureOptions object. All time-frequency features support scalarization.

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 = \bar{v} = \frac{1}{N} \sum_{i = 1}^{N} v_{i}$
"StandardDeviation" — Standard deviation of the elements of v, normalized by N-1.

$s = \sqrt{\frac{1}{N - 1} \sum_{i = 1}^{N} | v_{i} - \bar{v} |^{2}}$
"PeakValue" — Peak value, defined as the maximum absolute value of v.

$s = v_{p} = \max_{i} | v_{i} |$
"Kurtosis" — Kurtosis, defined as the ratio between the fourth moment of v and the squared second moment of v.

$s = \frac{\frac{1}{N} \sum_{i = 1}^{N} {(v_{i} - \bar{v})}^{4}}{{[\frac{1}{N} \sum_{i = 1}^{N} {(v_{i} - \bar{v})}^{2}]}^{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} \sum_{i = 1}^{N} {(v_{i} - \bar{v})}^{3}}{{[\frac{1}{N} \sum_{i = 1}^{N} {(v_{i} - \bar{v})}^{2}]}^{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}}{{(\frac{1}{N} \sum_{i = 1}^{N} \sqrt{| v_{i} |})}^{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} \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} \sum_{i = 1}^{N} | v_{i} |}$
"Energy" — Energy, defined as the sum of the squared values of v.

$s = \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 = \sum_{i = 1}^{N} p_{i} \log_{2} p_{i},$
where
$p = \frac{v^{2}}{\sum_{i = 1}^{N} v_{i}^{2}} .$

Note

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

Version History

Introduced in R2024a

timeFrequencyScalarFeatureOptions

Description

Creation

Syntax

Description

Properties

`SpectralKurtosis` — Scalarization methods for spectral kurtosis feature vector
`strings(0)` (default) | string array | cell array

`SpectralSkewness` — Scalarization methods for spectral skewness feature vector
`strings(0)` (default) | string array | cell array

`SpectralCrest` — Scalarization methods for spectral crest feature vector
`strings(0)` (default) | string array | cell array

`SpectralFlatness` — Scalarization methods for spectral flatness feature vector
`strings(0)` (default) | string array | cell array

`SpectralEntropy` — Scalarization methods for spectral entropy feature vector
`strings(0)` (default) | string array | cell array

`TFRidges` — Scalarization methods for time-frequency ridges feature vector
`strings(0)` (default) | string array | cell array

`InstantaneousBandwidth` — Scalarization methods for instantaneous bandwidth feature vector
`strings(0)` (default) | string array | cell array

`InstantaneousFrequency` — Scalarization methods for instantaneous frequency feature vector
`strings(0)` (default) | string array | cell array

`InstantaneousEnergy` — Scalarization methods for instantaneous energy feature vector
`strings(0)` (default) | string array | cell array

`MeanEnvelopeEnergy` — Scalarization methods for mean envelope energy feature vector
`strings(0)` (default) | string array | cell array

`WaveletEntropy` — Scalarization methods for wavelet entropy feature vector
`strings(0)` (default) | string array | cell array

`TimeSpectrum` — Scalarization methods for time-averaged wavelet spectrum feature vector
`strings(0)` (default) | string array | cell array

`ScaleSpectrum` — Scalarization methods for scale-averaged wavelet spectrum feature vector
`strings(0)` (default) | string array | cell array

`All` — Scalarization methods for all signal features
`strings(0)` (default) | string array | cell array

Examples

Add Scalarization Methods for Time-Frequency Feature Extraction

Set Scalarization Method Property in Time-Frequency Feature Extractor Object

Scalar and Vector Features in Time-Frequency Domain

More About

Scalarization Methods for Time-Frequency Features

Version History

See Also

Functions

Objects

timeFrequencyScalarFeatureOptions

Description

Creation

Syntax

Description

Properties

SpectralKurtosis — Scalarization methods for spectral kurtosis feature vector strings(0) (default) | string array | cell array

SpectralSkewness — Scalarization methods for spectral skewness feature vector strings(0) (default) | string array | cell array

SpectralCrest — Scalarization methods for spectral crest feature vector strings(0) (default) | string array | cell array

SpectralFlatness — Scalarization methods for spectral flatness feature vector strings(0) (default) | string array | cell array

SpectralEntropy — Scalarization methods for spectral entropy feature vector strings(0) (default) | string array | cell array

TFRidges — Scalarization methods for time-frequency ridges feature vector strings(0) (default) | string array | cell array

InstantaneousBandwidth — Scalarization methods for instantaneous bandwidth feature vector strings(0) (default) | string array | cell array

InstantaneousFrequency — Scalarization methods for instantaneous frequency feature vector strings(0) (default) | string array | cell array

InstantaneousEnergy — Scalarization methods for instantaneous energy feature vector strings(0) (default) | string array | cell array

MeanEnvelopeEnergy — Scalarization methods for mean envelope energy feature vector strings(0) (default) | string array | cell array

WaveletEntropy — Scalarization methods for wavelet entropy feature vector strings(0) (default) | string array | cell array

TimeSpectrum — Scalarization methods for time-averaged wavelet spectrum feature vector strings(0) (default) | string array | cell array

ScaleSpectrum — Scalarization methods for scale-averaged wavelet spectrum feature vector strings(0) (default) | string array | cell array

All — Scalarization methods for all signal features strings(0) (default) | string array | cell array

Examples

Add Scalarization Methods for Time-Frequency Feature Extraction

Set Scalarization Method Property in Time-Frequency Feature Extractor Object

Scalar and Vector Features in Time-Frequency Domain

More About

Scalarization Methods for Time-Frequency Features

Version History

See Also

Functions

Objects

`SpectralKurtosis` — Scalarization methods for spectral kurtosis feature vector
`strings(0)` (default) | string array | cell array

`SpectralSkewness` — Scalarization methods for spectral skewness feature vector
`strings(0)` (default) | string array | cell array

`SpectralCrest` — Scalarization methods for spectral crest feature vector
`strings(0)` (default) | string array | cell array

`SpectralFlatness` — Scalarization methods for spectral flatness feature vector
`strings(0)` (default) | string array | cell array

`SpectralEntropy` — Scalarization methods for spectral entropy feature vector
`strings(0)` (default) | string array | cell array

`TFRidges` — Scalarization methods for time-frequency ridges feature vector
`strings(0)` (default) | string array | cell array

`InstantaneousBandwidth` — Scalarization methods for instantaneous bandwidth feature vector
`strings(0)` (default) | string array | cell array

`InstantaneousFrequency` — Scalarization methods for instantaneous frequency feature vector
`strings(0)` (default) | string array | cell array

`InstantaneousEnergy` — Scalarization methods for instantaneous energy feature vector
`strings(0)` (default) | string array | cell array

`MeanEnvelopeEnergy` — Scalarization methods for mean envelope energy feature vector
`strings(0)` (default) | string array | cell array

`WaveletEntropy` — Scalarization methods for wavelet entropy feature vector
`strings(0)` (default) | string array | cell array

`TimeSpectrum` — Scalarization methods for time-averaged wavelet spectrum feature vector
`strings(0)` (default) | string array | cell array

`ScaleSpectrum` — Scalarization methods for scale-averaged wavelet spectrum feature vector
`strings(0)` (default) | string array | cell array

`All` — Scalarization methods for all signal features
`strings(0)` (default) | string array | cell array