# 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 resulting
`frequencyScalarFeatureOptions`

object to set the `ScalarizationMethod`

property of a `signalFrequencyFeatureExtractor`

object.

## Creation

### Description

creates
an object `opts`

= frequencyScalarFeatureOptions`opts`

that stores the scalarization methods with default
values (empty string arrays) for all signal features in frequency domain.

specifies scalarization methods for each frequency-domain signal feature using name-value
arguments. You can specify multiple name-value arguments. For example,
`opts`

= frequencyScalarFeatureOptions(`Name=Value`

)```
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 Domain-Specific Signal 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, 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 the feature 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 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, 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:

Associates the scalarization methods you have specified 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: [0x0 string] PeakAmplitude: [0x0 string] All: [0x0 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: [0x0 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: [0x0 string] All: [0x0 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: [0x0 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" 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 Domain-Specific Signal Features

To set the scalarization methods for features in time domain, frequency domain, or time-frequency domain, select the domain-specific feature extractor objects and scalarization method specification. Refer to the following 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}{\mathrm{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}}}}$$

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

## Version History

**Introduced in R2024b**

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