signalTimeFeatureExtractor

Streamline signal time feature extraction

Since R2021a

Description

Use signalTimeFeatureExtractor to extract time-domain features from a signal. You can use the extracted features to train a machine learning model or a deep learning network.

Creation

Syntax

sFE = signalTimeFeatureExtractor

sFE = signalTimeFeatureExtractor(Name=Value)

Description

sFE = signalTimeFeatureExtractor creates a signalTimeFeatureExtractor object with default property values.

sFE = signalTimeFeatureExtractor(Name=Value) specifies nondefault property values of the signalTimeFeatureExtractor object. For example, signalTimeFeatureExtractor(FeatureFormat="table") sets the output format of the generated features to a table.

example

Properties

expand all

Main Properties

`FrameSize` — Number of samples per frame
positive integer

Number of samples per frame, specified as a positive integer. The object divides the signal into frames of the specified length and extracts features for each frame. If you do not specify FrameSize, or if you specify FrameSize as empty, the object extracts features for the whole signal.

Data Types: single | double

`FrameRate` — Number of samples between start of frames
positive integer

Number of samples between the start of frames, specified as a positive integer. The frame rate determines the distance in samples between the starting points of frames. If you specify FrameRate, then you must also specify FrameSize. If you do not specify FrameRate or FrameOverlapLength, then the object assumes FrameRate to be equal to FrameSize. You cannot specify FrameRate and FrameOverlapLength simultaneously.

Data Types: single | double

`FrameOverlapLength` — Number of overlapping samples between consecutive frames
positive integer

Number of overlapping samples between consecutive frames, specified as a positive integer. FrameOverlapLength must be less than or equal to the frame size. If you specify FrameOverlapLength, then you must also specify FrameSize. You cannot specify FrameOverlapLength and FrameRate simultaneously.

Data Types: single | double

`SampleRate` — Sample rate
`[]` (default) | positive scalar

Input sample rate, specified as a positive scalar in hertz.

If you do not specify SampleRate, the extract function of the object assumes the signal sampling rate as 2π Hz.

Data Types: single | double

`FeatureFormat` — Format of generated signal features
`"matrix"` (default) | `"table"`

Format of the signal features generated by the extract function, specified as one of these:

"matrix" — Columns correspond to feature values.
"table" — Each table variable corresponds to a feature value.

Note

You can generate features for multiple signals at once by specifying a datastore object input in the extract function. In this case, extract returns a cell array where each member corresponds to a feature matrix or table from a signal member of the datastore. The format of the generated features in each member follows the format specified in FeatureFormat.

Data Types: char | string

`IncompleteFrameRule` — Rule to handle incomplete frames
`"drop"` (default) | `"zeropad"`

Rule to handle incomplete frames, specified as one of these:

"drop" — Drop the incomplete frame and do not use it to compute features.
"zeropad" — Zero-pad the incomplete frame and use it to compute features.

This rule applies when the current frame size is less than the specified FrameSize property.

Data Types: char | string

`ScalarizationMethod` — Methods to convert feature vectors to scalar values
`timeScalarFeatureOptions` object

Since R2024b

Methods to convert feature vectors to scalar values, specified as a timeScalarFeatureOptions object.

You can specify methods to extract scalar values from the Features to Extract. Specify scalarization methods for the feature extractor object by using the ScalarizationMethod name-value argument or the setScalarizationMethods function.

If you specify ScalarizationMethod, the signalTimeFeatureExtractor object returns the corresponding scalar values for each feature vector using the scalarization method.
To convert a feature vector to scalar feature values:
- You must enable the feature for extraction by setting the feature name in the signalTimeFeatureExtractor object to true.
- You must specify the desired scalarization methods for each feature name using a cell array of character vectors or a string array and store the information in a timeScalarFeatureOptions object.
After that, the extract function:
- Extracts the vectors corresponding to each enabled feature.
- Takes the list of scalarization methods compiled by the object and for each method computes the corresponding scalar value.
- Concatenates the vector features and the scalar features.
If you do not specify ScalarizationMethod, the signalTimeFeatureExtractor object does not perform any scalarization.

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

Features to Extract

`Mean` — Option to extract mean
`false` (default) | `true`

Option to extract the mean, specified as true or false. If you specify Mean as true, the signalTimeFeatureExtractor object extracts the mean and appends the value to the features returned by the extract function.

Data Types: logical

`RMS` — Option to extract root mean square
`false` (default) | `true`

Option to extract the root mean square (RMS), specified as true or false. If you specify RMS as true, the signalTimeFeatureExtractor object extracts the RMS and appends the value to the features returned by the extract function.

Data Types: logical

`StandardDeviation` — Option to extract standard deviation
`false` (default) | `true`

Option to extract the standard deviation, specified as true or false. If you specify StandardDeviation as true, the signalTimeFeatureExtractor object extracts the standard deviation and appends the value to the features returned by the extract function.

Data Types: logical

`ShapeFactor` — Option to extract shape factor
`false` (default) | `true`

Option to extract the shape factor, specified as true or false. The shape factor is equal to the RMS value divided by the mean absolute value of the signal. If you specify ShapeFactor as true, the signalTimeFeatureExtractor object extracts the shape factor and appends the value to the features returned by the extract function.

Data Types: logical

`SNR` — Option to extract signal-to-noise ratio
`false` (default) | `true`

Option to extract the signal-to-noise ratio (SNR), specified as true or false. If you specify SNR as true, the signalTimeFeatureExtractor object extracts the SNR and appends the value to the features returned by the extract function.

Data Types: logical

`THD` — Option to extract total harmonic distortion
`false` (default) | `true`

Option to extract the total harmonic distortion (THD), specified as true or false. If you specify THD as true, the signalTimeFeatureExtractor object extracts the THD and appends the value to the features returned by the extract function.

Data Types: logical

`SINAD` — Option to extract signal to noise and distortion ratio
`false` (default) | `true`

Option to extract the signal to noise and distortion ratio (SINAD) in decibels, specified as true or false. If you specify Sinad as true, the signalTimeFeatureExtractor object extracts the SINAD and appends the value to the features returned by the extract function.

Data Types: logical

`PeakValue` — Option to extract peak value
`false` (default) | `true`

Option to extract the peak value, specified as true or false. The peak value corresponds to the maximum absolute value of the signal. If you specify PeakValue as true, the signalTimeFeatureExtractor object extracts the peak and appends the value to the features returned by the extract function.

Data Types: logical

`CrestFactor` — Option to extract crest factor
`false` (default) | `true`

Option to extract the crest factor, specified as true or false. The crest factor is equal to the peak value divided by the RMS. If you specify CrestFactor as true, the signalTimeFeatureExtractor object extracts the crest factor and appends the value to the features returned by the extract function.

Data Types: logical

`ClearanceFactor` — Option to extract clearance factor
`false` (default) | `true`

Option to extract the clearance factor, specified as true or false. The clearance factor is equal to the peak value divided by the squared mean of the square roots of the absolute amplitude. If you specify ClearanceFactor as true, the signalTimeFeatureExtractor object extracts the clearance factor and appends the value to the features returned by the extract function.

Data Types: logical

`ImpulseFactor` — Option to extract impulse factor
`false` (default) | `true`

Option to extract the impulse factor, specified as true or false. The impulse factor is equal to the peak value divided by the mean of the absolute amplitude. If you specify ImpulseFactor as true, the signalTimeFeatureExtractor object extracts the impulse factor and appends the value to the features returned by the extract function.

Data Types: logical

Object Functions

`extract`	Extract time-domain, frequency-domain, or time-frequency-domain features
`generateMATLABFunction`	Create MATLAB function compatible with C/C++ code generation

Examples

collapse all

Extract Time-Domain Features from Data Set

Open Live Script

Extract time-domain features from electromyographic (EMG) data for later use in a machine learning workflow to classify forearm motions. The files are available at this location: https://ssd.mathworks.com/supportfiles/SPT/data/MyoelectricData.zip.

This example uses EMG signals collected from the forearms of 30 subjects [1]. The data set consists of 720 files. Each subject participated in four testing sessions, and performed six trials of different forearm motions per session. Download and unzip the files into your temporary directory.

localfile = matlab.internal.examples.downloadSupportFile( ...
    "SPT","data/MyoelectricData.zip");
datasetFolder = fullfile(tempdir,"MyoelectricData");
unzip(localfile,datasetFolder)

Each file contains an eight-channel EMG signal that represents the activation of eight forearm muscles during a series of motions. The sample rate is 1000 Hz. Create a signalDatastore object that points to the data set folder.

fs = 1000;
sds = signalDatastore(datasetFolder,IncludeSubfolders=true);

For this example, analyze only the last (sixth) trial of the third session. Use the endsWith function to find the indices that correspond to these files. Create a new datastore that contains this subset of signals.

idSession = 3;
idTrial = 6;
idSuffix = "S"+idSession+"T"+idTrial+"d.mat";
p = endsWith(sds.Files,idSuffix);
sdssub = subset(sds,p);

Create a signalTimeFeatureExtractor object to extract the mean, root mean square (RMS), and peak values from the EMG signals. Call the extract function to extract the specified features.

sFE = signalTimeFeatureExtractor(SampleRate=fs, ...
    Mean=true,RMS=true,PeakValue=true);

[M,infoFeatures] = extract(sFE,sdssub);
Features = cell2mat(M);

Plot the peak values for the second and eighth EMG channels.

featureName = "PeakValue";
idPeaks = infoFeatures{1}.(featureName);
idChannels = [2 8];
Peaks = squeeze(Features(:,idPeaks,idChannels));

bar(Peaks)
xlabel("Subject")
ylabel(featureName+" EMG (mV)")
legend("Channel"+idChannels)
title(featureName+" Feature: Session "+idSession+ ...
    ", Trial "+idTrial)

Figure contains an axes object. The axes object with title PeakValue Feature: Session 3, Trial 6, xlabel Subject, ylabel PeakValue EMG (mV) contains 2 objects of type bar. These objects represent Channel2, Channel8.

More About

expand all

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 = \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}}$

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}}{{(\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}}}$
"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 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} \sum_{i = 1}^{N} | v_{i} |}$

References

[1] Chan, Adrian D.C., and Geoffrey C. Green. 2007. "Myoelectric Control Development Toolbox." Paper presented at 30th Conference of the Canadian Medical & Biological Engineering Society, Toronto, Canada, 2007.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

You cannot generate code directly from signalTimeFeatureExtractor. You can generate C/C++ code from the function returned by generateMATLABFunction.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2021a

expand all

R2024b: Specify scalarization methods for time-domain signal features

The signalTimeFeatureExtractor function supports specifying methods to extract scalar features in time domain.

R2023a: Use `gpuArray` inputs

The signalTimeFeatureExtractor object supports gpuArray inputs. You must have Parallel Computing Toolbox™ to use this functionality.

signalTimeFeatureExtractor

Description

Creation

Syntax

Description

Properties

Main Properties

FrameSize — Number of samples per frame positive integer

FrameRate — Number of samples between start of frames positive integer

FrameOverlapLength — Number of overlapping samples between consecutive frames positive integer

SampleRate — Sample rate [] (default) | positive scalar

FeatureFormat — Format of generated signal features "matrix" (default) | "table"

IncompleteFrameRule — Rule to handle incomplete frames "drop" (default) | "zeropad"

ScalarizationMethod — Methods to convert feature vectors to scalar values timeScalarFeatureOptions object

Features to Extract

Mean — Option to extract mean false (default) | true

RMS — Option to extract root mean square false (default) | true

StandardDeviation — Option to extract standard deviation false (default) | true

ShapeFactor — Option to extract shape factor false (default) | true

SNR — Option to extract signal-to-noise ratio false (default) | true

THD — Option to extract total harmonic distortion false (default) | true

SINAD — Option to extract signal to noise and distortion ratio false (default) | true

PeakValue — Option to extract peak value false (default) | true

CrestFactor — Option to extract crest factor false (default) | true

ClearanceFactor — Option to extract clearance factor false (default) | true

ImpulseFactor — Option to extract impulse factor false (default) | true

Object Functions

Examples

Extract Time-Domain Features from Data Set

More About

Scalarization Methods for Domain-Specific Signal Features

References

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2024b: Specify scalarization methods for time-domain signal features

R2023a: Use gpuArray inputs

See Also

Functions

Objects

Topics

`FrameSize` — Number of samples per frame
positive integer

`FrameRate` — Number of samples between start of frames
positive integer

`FrameOverlapLength` — Number of overlapping samples between consecutive frames
positive integer

`SampleRate` — Sample rate
`[]` (default) | positive scalar

`FeatureFormat` — Format of generated signal features
`"matrix"` (default) | `"table"`

`IncompleteFrameRule` — Rule to handle incomplete frames
`"drop"` (default) | `"zeropad"`

`ScalarizationMethod` — Methods to convert feature vectors to scalar values
`timeScalarFeatureOptions` object

`Mean` — Option to extract mean
`false` (default) | `true`

`RMS` — Option to extract root mean square
`false` (default) | `true`

`StandardDeviation` — Option to extract standard deviation
`false` (default) | `true`

`ShapeFactor` — Option to extract shape factor
`false` (default) | `true`

`SNR` — Option to extract signal-to-noise ratio
`false` (default) | `true`

`THD` — Option to extract total harmonic distortion
`false` (default) | `true`

`SINAD` — Option to extract signal to noise and distortion ratio
`false` (default) | `true`

`PeakValue` — Option to extract peak value
`false` (default) | `true`

`CrestFactor` — Option to extract crest factor
`false` (default) | `true`

`ClearanceFactor` — Option to extract clearance factor
`false` (default) | `true`

`ImpulseFactor` — Option to extract impulse factor
`false` (default) | `true`

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

R2023a: Use `gpuArray` inputs