# timeScalarFeatureOptions

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

*Since R2024b*

## Description

Use a `timeScalarFeatureOptions`

object to store methods to convert time-domain
feature vectors to scalars. You can use the resulting `timeScalarFeatureOptions`

object to
set the `ScalarizationMethod`

property of a `signalTimeFeatureExtractor`

object.

## Creation

### Description

creates an
object `opts`

= timeScalarFeatureOptions`opts`

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

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

= timeScalarFeatureOptions(`Name=Value`

)```
timeScalarFeatureOptions(PeakValue=["Mean"
"Kurtosis"],All="Skewness")
```

specifies `"Mean"`

and
`"Kurtosis"`

as scalarization methods for the peak value feature, and
`"Skewness"`

as the scalarization method for all the time-domain
features. For more information about scalarization methods, see Scalarization Methods for Domain-Specific Signal Features.

## Properties

`PeakValue`

— Scalarization methods for peak value feature vector

`strings(0)`

(default) | string array | cell array

Scalarization methods for the peak value 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 `signalTimeFeatureExtractor`

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.

**Example: **`PeakValue = ["Mean" "Skewness"]`

sets the option to extract the mean
and the skewness of the peak value 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 Time-Domain Feature Extraction

Create a `timeScalarFeatureOptions`

object with default values.

opts = timeScalarFeatureOptions

opts = timeScalarFeatureOptions with properties: PeakValue: [0x0 string] All: [0x0 string]

Add scalarization methods for the peak value time-domain feature:

opts.PeakValue = ["Mean" "Kurtosis"];

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

opts

opts = timeScalarFeatureOptions with properties: PeakValue: ["Mean" "Kurtosis"] All: [0x0 string]

### Set Scalarization Method Property in Time-Domain Feature Extractor Object

Create and use a `timeScalarFeatureOptions`

object to set the `ScalarizationMethod`

property in a `signalTimeFeatureExtractor`

object.

Specify the standard deviation and the kurtosis as scalar features for the peak value time-domain feature. Store this information in a `timeScalarFeatureOptions`

object.

opts = timeScalarFeatureOptions( ... PeakValue=["StandardDeviation" "Kurtosis"]);

Create a `signalTimeFeatureExtractor`

object to extract the root mean square and peak value with its corresponding scalar values. Display the `ScalarizationMethod`

property of the feature extractor object.

tFE = signalTimeFeatureExtractor( ... RMS=true,PeakValue=true, ... ScalarizationMethod=opts); disp(tFE.ScalarizationMethod)

timeScalarFeatureOptions with properties: PeakValue: ["StandardDeviation" "Kurtosis"] All: [0x0 string]

### Scalar and Vector Features in Time Domain

Set scalarization methods to convert time-domain feature vectors to scalar values.

Specify `"Mean"`

and `"StandardDeviation"`

as scalarization methods for the peak value feature. Specify `"Kurtosis"`

as the scalarization method for all the enabled signal features. Store this information in a `timeScalarFeatureOptions`

object.

opts = timeScalarFeatureOptions( ... PeakValue=["Mean" "StandardDeviation"],All="Kurtosis")

opts = timeScalarFeatureOptions with properties: PeakValue: ["Mean" "StandardDeviation"] All: "Kurtosis"

Create a `signalTimeFeatureExtractor`

object to extract the signal-to-noise ratio, peak value, and total harmonic distortion features. Use `opts`

to set the scalarization method property of the feature extractor object.

sFE = signalTimeFeatureExtractor( ... SNR=true,PeakValue=true,THD=true, ... ScalarizationMethod=opts)

sFE = signalTimeFeatureExtractor with properties: Properties FrameSize: [] FrameRate: [] SampleRate: [] IncompleteFrameRule: "drop" FeatureFormat: "matrix" Enabled Features SNR, THD, PeakValue Disabled Features Mean, RMS, StandardDeviation, ShapeFactor, SINAD, CrestFactor ClearanceFactor, ImpulseFactor

Extract vectors and scalar features from a signal. Observe the list of extracted features.

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,indices] = extract(sFE,x)

`features = `*1×6*
30.4576 0.0432 2.1300 2.1300 0 NaN

`indices = `*struct with fields:*
SNR: 1
THD: 2
PeakValue: 3
PeakValueMean: 4
PeakValueStandardDeviation: 5
PeakValueKurtosis: 6

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