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 timeScalarFeatureOptions object to set the ScalarizationMethod property of a signalTimeFeatureExtractor object.

Creation

Syntax

opts = timeScalarFeatureOptions

opts = timeScalarFeatureOptions(PropertyName=Value)

Description

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

opts = timeScalarFeatureOptions(PropertyName=Value) specifies scalarization methods for each time-domain signal feature using name-value arguments. You can specify multiple name-value arguments. For example, 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 Time-Domain Features.

Properties

PeakValue — Scalarization methods for peak value feature vector

strings(0) (default) | string array | cell array

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

If you specify this feature, the feature extractor object:

1. Applies the scalarization methods associated with the feature.

2. 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:

• 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

Add Scalarization Methods for Time-Domain Feature Extraction

Create a timeScalarFeatureOptions object with default values.

opts = timeScalarFeatureOptions

opts = 
  timeScalarFeatureOptions with properties:

    PeakValue: [0×0 string]
          All: [0×0 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: [0×0 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: [0×0 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"
    ScalarizationMethod: [1×1 timeScalarFeatureOptions]

   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 Time-Domain Features

To set the methods for extracting scalar values from feature vectors in the time domain, set the scalarization method property of a signalTimeFeatureExtractor object with a timeScalarFeatureOptions object. Only the PeakValue feature supports 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=\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}}$$

Version History

Introduced in R2024b