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(PropertyName=Value)

Description

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

sFE = signalTimeFeatureExtractor(PropertyName=Value) specifies nondefault property values of the signalTimeFeatureExtractor object. For example,

sFE = signalTimeFeatureExtractor(FeatureFormat="table",Mean=true,THD=true)

creates a signalTimeFeatureExtractor object that extracts the mean and total harmonic distortion (THD) of a signal and returns the features in table format.

Properties

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.

Note

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.

Note

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

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

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

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

Features to Extract

You can extract these time-domain features: mean, root mean square (RMS), standard deviation, shape factor, signal-to-noise ratio (SNR), total harmonic distortion (THD), signal to noise and distortion ratio (SINAD), peak value, crest factor, clearance factor, and impulse factor.

Specify the features to be extracted as name-value arguments Name1=true,...,NameN=true, where Name is the feature name. The order of the arguments does not matter. For example, this code creates a time-domain feature extractor object to extract the mean and crest factor of a signal.

sFE = signalTimeFeatureExtractor(Mean=true,CrestFactor=true)

Mean — Option to extract mean

false (default) | true

Option to extract the mean, specified as true or false.

If you specify this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

For more information about the mean feature, see mean.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

For more information about the root mean square feature, see rms.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

For more information about the standard deviation feature, see std.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

For more information about the signal-to-noise ratio feature, see snr.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

For more information about the total harmonic distortion feature, see thd.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

For more information about the signal to noise and distortion ratio feature, see sinad.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

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 this feature as true:

• The feature-extractor object enables this feature for extraction.

• The extract function extracts this feature and concatenates it with all the other features that you enable in the feature-extractor object.

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
getScalarizationMethods	Get scalarization methods for domain-specific signal features
setScalarizationMethods	Set scalarization methods for domain-specific signal features

Examples

Extract Time-Domain Features from Signal

Since R2025a

Extract time-domain features from a synthetic power-supply signal with harmonics.

Generate a sinusoidal signal with an amplitude of 110$\sqrt{2}$ V, a frequency of 50 Hz, and add third-, fifth-, and seventh-order harmonics. The harmonic relative amplitudes are 0.15, 0.03, and 0.01, respectively. The signal is five seconds long and has a sample rate of 1000 Hz.

rng("default")
Fs = 1000;
t = (0:1/Fs:5)';
a = 110*sqrt(2)*[1 0.15 0.03 0.01];
f = 50*[1 3 5 7];
x = cos(2*pi*f.*t)*a' + randn(size(t));

Display the first 0.1 seconds of the generated signal.

plot(t,x)
xlim([0 0.1])
xlabel("Time (seconds)")
ylabel("Amplitude (V)")

Create a time-domain feature extractor object. Set the frame size so that each frame is one second long. Set up the object to extract the root mean square (RMS), signal-to-noise ratio (SNR), and total harmonic distortion (THD) features of a signal. Return the features in a table.

sFE = signalTimeFeatureExtractor(FrameSize=Fs, ...
    SampleRate=Fs,FeatureFormat="table", ...
    RMS=true,SNR=true,THD=true)

sFE = 
  signalTimeFeatureExtractor with properties:

   Properties
              FrameSize: 1000
              FrameRate: []
             SampleRate: 1000
    IncompleteFrameRule: "drop"
          FeatureFormat: "table"
    ScalarizationMethod: [1×1 timeScalarFeatureOptions]

   Enabled Features
     RMS, SNR, THD

   Disabled Features
     Mean, StandardDeviation, ShapeFactor, SINAD, PeakValue, CrestFactor
     ClearanceFactor, ImpulseFactor


   

Extract the features from the signal.

features = extract(sFE,x)

features=5×5 table
    FrameStartTime    FrameEndTime     RMS       SNR        THD  
    ______________    ____________    ______    ______    _______

            1             1000        111.34    37.736    -16.247
         1001             2000        111.26    37.302     -16.35
         2001             3000        111.31    37.748    -16.298
         3001             4000        111.26    38.057    -16.278
         4001             5000        111.34    37.376    -16.346

Extract Time-Domain Features from Data Set

Extract time-domain features from electromyographic (EMG) data to use later 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)

Multidomain Signal Features from Vibration Signal

Since R2025a

Extract time-domain, frequency-domain, and time-frequency features from healthy bearing vibration signals and faulty bearing vibration signals. While a healthy bearing vibration signal does not have outstanding defects, a faulty bearing vibration signal results from wear-and-tear defects, such as spalls on the gear teeth, eccentricity or gear misalignment, and cracks at the races.

For more information on bearing signal generation and analysis, see Vibration Analysis of Rotating Machinery. To learn more about the feature extraction and model training workflow to identify faulty bearing signals in mechanical systems, see Machine Learning and Deep Learning Classification Using Signal Feature Extraction Objects.

Generate Healthy Bearing Signal

Generate a healthy bearing vibration signal as a sum of three cosine pulses with amplitudes of 0.4 V, 0.2 V, and 1 V, respectively, and frequencies of 22.5 Hz, 8.36 Hz, and 292.5 Hz, respectively, for three seconds and with a sample rate of 20 kHz. Generate Gaussian noise and add it to the signal.

rng("default")
Fs = 20e3;
t = (0:1/Fs:3-1/Fs)';

a = [0.4 0.2 1];
f = [22.5 8.36 292.5];
sClean = cos(2*pi*f.*t)*a';
sHealthy = sClean + 0.2*randn(size(t));

Generate Faulty Bearing Signal

Generate a faulty bearing vibration signal by adding a bearing impact signal to the healthy bearing signal. Model each impact as a 3 kHz sinusoid windowed by a Kaiser window. The defect causes a series of 10-millisecond impacts on the bearing.

tImpact = t(t<10e-3)';
xImpact = sin(2*pi*3000*tImpact).*kaiser(length(tImpact),40)';

xImpactBper = 0.33*pulstran(t,0:1/104.5:t(end),xImpact,Fs);

Generate a faulty bearing vibration signal as a sum of the healthy bearing signal, the bearing impact signal, and additive Gaussian noise.

sFaulty = sHealthy + xImpactBper;

Consolidate and Visualize Signals

Bundle the healthy bearing and faulty bearing signals in a signalDatastore object in single precision.

sds = signalDatastore({sHealthy,sFaulty},OutputDataType="single");

Plot the power spectrum of the healthy and faulty vibration signals. Observe the peaks that correspond to the bearing impact.

[P,F] = pspectrum([sHealthy sFaulty],Fs);
p = plot(F/1000,pow2db(P));
p(1).Marker = ".";
xlabel("Frequency (kHz)")
ylabel("Power Spectrum (dB)")
legend(["Healthy" "Faulty"])

Set Up Feature Extraction Pipeline

Create a signalTimeFeatureExtractor object for time-domain feature extraction.

timeFE = signalTimeFeatureExtractor(SampleRate=Fs,...
    RMS=true,ImpulseFactor=true,StandardDeviation=true);

Create a signalFrequencyFeatureExtractor object for frequency-domain feature extraction.

freqFE = signalFrequencyFeatureExtractor(SampleRate=Fs, ...
    MedianFrequency=true,BandPower=true,PeakAmplitude=true);

Create a signalTimeFrequencyFeatureExtractor object to extract time-frequency features from a spectrogram. Set the leakage parameter for the spectrogram to 90%.

timeFreqFE = signalTimeFrequencyFeatureExtractor(SampleRate=Fs, ...
    SpectralKurtosis=true,SpectralSkewness=true,TFRidges=true);

setExtractorParameters(timeFreqFE,"spectrogram",Leakage=0.9);

Extract Multidomain Features

Extract signal features using all three feature extractors for the signals in the signalDatastore object. Concatenate and display the features in a multidomain feature table.

features = cellfun(@(a,b,c) [real(a) real(b) real(c)], ...
    extract(timeFE,sds),extract(freqFE,sds),extract(timeFreqFE,sds), ...
    UniformOutput=false);

featureMatrix = cell2mat(features);
featureTable = array2table(featureMatrix);
rows2vars(featureTable)

ans=579×3 table
    OriginalVariableNames     Var1       Var2  
    _____________________    _______    _______

     {'featureMatrix1' }     0.80115    0.80538
     {'featureMatrix2' }     0.80116    0.80539
     {'featureMatrix3' }      3.2635     3.1501
     {'featureMatrix4' }      292.39     292.41
     {'featureMatrix5' }     0.64086    0.64764
     {'featureMatrix6' }     0.20977    0.20977
     {'featureMatrix7' }      27.474     25.423
     {'featureMatrix8' }      35.088     32.666
     {'featureMatrix9' }      25.867     24.521
     {'featureMatrix10'}      29.091     26.485
     {'featureMatrix11'}      36.085     32.242
     {'featureMatrix12'}       32.92     31.423
     {'featureMatrix13'}      24.421     22.288
     {'featureMatrix14'}      26.056     24.772
     {'featureMatrix15'}       30.36     28.084
     {'featureMatrix16'}      26.464     25.432
      ⋮

More About

Time-Domain Signal Features

The signalTimeFeatureExtractor object sets up a signal framing and feature extraction pipeline to extract time-domain features.

To customize the feature extraction pipeline based on your selected features, specify properties when you create the signalTimeFeatureExtractor object. For example, set up a feature extraction pipeline that extracts the shape factor, signal to noise and distortion ratio (SINAD), and crest factor of a signal.

sFE = signalTimeFeatureExtractor( ...
    ShapeFactor=true,SINAD=true,CrestFactor=true)

sFE = 

  signalTimeFeatureExtractor with properties:

   Properties
              FrameSize: []
              FrameRate: []
             SampleRate: []
    IncompleteFrameRule: "drop"
          FeatureFormat: "matrix"
    ScalarizationMethod: [1×1 timeScalarFeatureOptions]

   Enabled Features
     ShapeFactor, SINAD, CrestFactor

   Disabled Features
     Mean, RMS, StandardDeviation, SNR, THD, PeakValue
     ClearanceFactor, ImpulseFactor

This configuration corresponds to the highlighted feature extraction pipeline. To extract features from a signal, use the extract function. When you use the extract function, the function executes the pipeline and returns the features in a matrix, table, or cell array, depending on the value specified in FeatureFormat.

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

Algorithms

Assume an input signal x sampled at a rate Fs, from which to extract time-domain features. When you specify signal framing properties (FrameSize, FrameRate or FrameOverlapLength, and IncompleteFrameRule), the feature extractor sets up the signal partitioning operation for x to extract features for each frame. This table shows the equivalent syntaxes that signalTimeFeatureExtractor uses to partition the signal x into frames of size fl, frame rate fr or frame overlap length ol, and incomplete frame rule ifr.

Frame Specifications	Feature Extractor Object Specification	Signal Framing Operation Equivalency
FrameSize FrameRate IncompleteFrameRule	sFE = signalTimeFeatureExtractor( ... FrameSize=fl,FrameRate=fr, ... IncompleteFrameRule=ifr);	xFrames = framesig(x,fl, ... OverlapLength=fl-fr, ... IncompleteFrameRule=ifr);
FrameSize FrameOverlapLength IncompleteFrameRule	sFE = signalTimeFeatureExtractor( ... FrameSize=fl,FrameOverlapLength=ol, ... IncompleteFrameRule=ifr);	xFrames = framesig(x,fl, ... OverlapLength=ol, ... IncompleteFrameRule=ifr);

If you do not specify signal framing properties, signalTimeFeatureExtractor considers x as a single-framed signal.

Given the single-framed input signal x and sample rate Fs, this table lists the equivalent syntaxes for extracting features using the signalTimeFeatureExtractor object and the individual feature extractor functions.

Features	Feature Extractor Object	Individual Feature Extractors
Mean RMS StandardDeviation ShapeFactor SNR THD SINAD PeakValue CrestFactor ClearanceFactor ImpulseFactor	sFE = signalTimeFeatureExtractor( ... SampleRate=Fs, ... Mean=true, ... RMS=true, ... StandardDeviation=true, ... ShapeFactor=true, ... SNR=true, ... THD=true, ... SINAD=true, ... PeakValue=true, ... CrestFactor=true, ... ClearanceFactor=true, ... ImpulseFactor=true); features = extract(sFE,x);	features = [ ... mean(x) ... rms(x) ... std(x) ... rms(x)/mean(abs(x)) ... snr(x) ... thd(x) ... sinad(x) ... max(abs(x)) ... max(abs(x))/rms(x) ... max(abs(x))/mean(sqrt(abs(x)))^2 ... max(abs(x))/mean(abs(x)) ... ];

Note

To obtain the equivalent syntax for the feature extraction setup based on the properties specified when you create the signalTimeFeatureExtractor object, use generateMATLABFunction.

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

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.