# scalarFeatureOptions

## Syntax

## Description

creates an object
`opts`

= scalarFeatureOptions`opts`

that stores the scalarization methods for all the
time-frequency-domain features with default values. 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

## Input Arguments

`domain`

— Domain of signal representation

`"timefrequency"`

Domain of signal representation, specified as
`"timefrequency"`

.

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

When `domain`

is `"timefrequency"`

, the name-value
arguments must correspond with signal features in the time-frequency domain.

Valid feature names are

`SpectralKurtosis`

,`SpectralSkewness`

,`SpectralCrest`

,`SpectralFlatness`

,`SpectralEntropy`

,`TFRidges`

,`InstantaneousBandwidth`

,`InstantaneousFrequency`

,`MeanEnvelopeEnergy`

,`InstantaneousEnergy`

,`WaveletEntropy`

,`TimeSpectrum`

,`ScaleSpectrum`

, or`All`

.Valid scalarization method names are

`ClearanceFactor`

,`Mean`

,`CrestFactor`

,`PeakValue`

,`ImpulseFactor`

,`Energy`

,`StandardDeviation`

,`Kurtosis`

,`Skewness`

, or`Entropy`

. For more information about scalarization methods, see Scalarization Methods for Signal Features in Time-Frequency Domain.

`SpectralKurtosis`

— Scalarization methods for spectral kurtosis feature vector

`strings(0)`

(default) | cell array | string array

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

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 it 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) | cell array | string array

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

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 it 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) | cell array | string array

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

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 it 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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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) | cell array | string array

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

`signalTimeFrequencyFeatureExtractor`

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.

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 feature

`strings(0)`

(default) | cell array | string array

Scalarization methods for all the signal features, specified as a cell array of character vectors or as a string array.

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

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.

For more information about signal features in the time-frequency domain, see
`signalTimeFrequencyFeatureExtractor`

.

**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

List of features and their corresponding scalarization methods, returned as a
`timeFrequencyScalarFeatureOptions`

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 Signal Features in Time-Frequency Domain

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}{\mathrm{max}}\left|{v}_{i}\right|$$

`'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}}}}$$

`'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*p*log_{2}*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}{\mathrm{log}}_{2}{p}_{i}},$$

where

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

**Note**The scalarization method

`'Entropy'`

is not supported for the`WaveletEntropy`

nor the`SpectralEntropy`

features.`'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|}}$$

`'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}}$$

## Version History

**Introduced in R2024a**

## 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)