signalTimeFeatureExtractor - Streamline signal time feature extraction - MATLAB (original) (raw)

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

Description

`sFE` = signalTimeFeatureExtractor creates asignalTimeFeatureExtractor object with default property values.

`sFE` = signalTimeFeatureExtractor([PropertyName=Value](#mw%5Fb44a6c1c-5e8e-4509-a616-c52cc92857a3)) 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.

example

Properties

expand all

Main Properties

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 specifyFrameSize, or if you specifyFrameSize as empty, the object extracts features for the whole signal.

Data Types: single | double

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 specifyFrameRate, then you must also specify FrameSize. If you do not specify FrameRate orFrameOverlapLength, then the object assumesFrameRate to be equal to FrameSize.

Note

You cannot specify FrameRate andFrameOverlapLength simultaneously.

Data Types: single | double

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 specifyFrameSize.

Note

You cannot specify FrameOverlapLength andFrameRate simultaneously.

Data Types: single | double

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

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

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

Data Types: char | string

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

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

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 theScalarizationMethod name-value argument or the setScalarizationMethods function.

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, whereName 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)

Option to extract the mean, specified as true orfalse.

If you specify this feature as true:

For more information about the mean feature, see mean.

Data Types: logical

Option to extract the root mean square (RMS), specified as true or false.

If you specify this feature as true:

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

Data Types: logical

Option to extract the standard deviation, specified as true orfalse.

If you specify this feature as true:

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

Data Types: logical

Option to extract the shape factor, specified as true orfalse. 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:

Data Types: logical

Option to extract the signal-to-noise ratio (SNR), specified astrue or false.

If you specify this feature as true:

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

Data Types: logical

Option to extract the total harmonic distortion (THD), specified astrue or false.

If you specify this feature as true:

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

Data Types: logical

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:

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

Data Types: logical

Option to extract the peak value, specified as true orfalse. The peak value corresponds to the maximum absolute value of the signal.

If you specify this feature as true:

Data Types: logical

Option to extract the crest factor, specified as true orfalse. The crest factor is equal to the peak value divided by the RMS.

If you specify this feature as true:

Data Types: logical

Option to extract the clearance factor, specified as true orfalse. 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:

Data Types: logical

Option to extract the impulse factor, specified as true orfalse. The impulse factor is equal to the peak value divided by the mean of the absolute amplitude.

If you specify this feature as true:

Data Types: logical

Object Functions

Examples

collapse all

Since R2025a

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

Generate a sinusoidal signal with an amplitude of 1102 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 = 110sqrt(2)[1 0.15 0.03 0.01]; f = 50*[1 3 5 7]; x = cos(2pif.*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)")

Figure contains an axes object. The axes object with xlabel Time (seconds), ylabel Amplitude (V) contains an object of type line.

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

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.

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(2pif.*t)a'; sHealthy = sClean + 0.2randn(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(2pi3000*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"])

Figure contains an axes object. The axes object with xlabel Frequency (kHz), ylabel Power Spectrum (dB) contains 2 objects of type line. These objects represent 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

expand all

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, specifyproperties 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 theextract 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.

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.

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 signalx into frames of size fl, frame ratefr 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 rateFs, 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, usegenerateMATLABFunction.

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

expand all

Usage notes and limitations:

Version History

Introduced in R2021a

expand all

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

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

See Also

Apps

Functions

Objects

Blocks

Topics