extract

Extract time-domain, frequency-domain, or time-frequency-domain features

Since R2021b

Syntax

features = extract(sFE,x)

[features,info] = extract(sFE,x)

[features,info,framelimits] = extract(sFE,x)

[___] = extract(sFE,sds)

[___] = extract(sFE,sds,UseParallel=tf)

Description

features = extract(sFE,x) returns a matrix or a table containing features extracted from input x. The output depends on the settings of the feature extractor object sFE.

[features,info] = extract(sFE,x) returns a structure info that maps a specific feature to its column location in the output feature matrix features. This syntax is valid only when you set the FeatureFormat property of the feature extractor object to "matrix".

[features,info,framelimits] = extract(sFE,x) returns a matrix framelimits whose i-th row contains the beginning and end limits of the i-th frame. This syntax is valid only when you set the FeatureFormat property of the feature extractor object to "matrix".

[___] = extract(sFE,sds) returns a cell array of matrices or a tables containing features extracted from the datastore object sds. The output depends on the settings of the feature extractor object sFE. (since R2024b)

[___] = extract(sFE,sds,UseParallel=tf) enables you to accelerate code by automatically running computations in parallel. You must have a Parallel Computing Toolbox™ license and specify UseParallel=true in the syntax to use this functionality. (since R2024b)

Examples

Extract Daily Peaks from Temperature Data

Load a set of temperature readings in degrees Celsius taken every hour at Logan Airport in Boston for 31 days. Plot the data.

load bostemp
days = (1:31*24)/24;
plot(days, tempC)
axis tight
ylabel("Temperature (\circC)")
xlabel("Time elapsed from Jan 1, 2011 (days)")
title("Logan Airport Dry Bulb Temperature (source: NOAA)")

Create a signalTimeFeatureExtractor object and enable the PeakValue feature. To obtain the maximum absolute temperature reading per day, set the frame size to 24 samples and the frame overlap to 0 samples.

fl = 24;
sFE = signalTimeFeatureExtractor(FrameSize=fl, ...
    FrameOverlapLength=0,PeakValue=true);

Call the extract function on the object to extract the daily absolute maximum temperatures in the data set.

peaktemps = extract(sFE,tempC)

peaktemps = 31×1

    2.8000
    6.1000
    8.3000
    3.3000
    2.8000
    4.4000
    4.4000
    6.1000
   10.6000
   11.7000
    7.8000
    8.9000
    9.4000
    5.6000
    7.8000
      ⋮

Confirm the extracted peak values. Divide the signal into 24-sample segments representing temperature readings per day and compute the maximum absolute value of each segment. Compare the resulting vector to peaktemps.

y = framesig(tempC,fl);
[mx,idx] = max(abs(y));

tf = isequal(peaktemps,mx')

tf = logical
   1

Extract Mean Values from Timetable Data

Load a set of temperature readings in degrees Celsius taken every hour at Logan Airport in Boston for 31 days. Plot the data.

load bostemp
days = (1:31*24)/24;
plot(days,tempC)
axis tight
ylabel("Temperature (\circC)")
xlabel("Time elapsed from Jan 1, 2011 (days)")
title("Logan Airport Dry Bulb Temperature (source: NOAA)")

Convert the array of temperature readings to a timetable. The first temperature reading was taken on January 1, 2011.

tt = array2timetable(tempC, ...
    TimeStep=hours(1),StartTime=datetime(2011,01,01));

Create a signalTimeFeatureExtractor object and enable the Mean feature to obtain the weekly average temperatures. Specify the sample rate and frame size (1 week = 168 hours) of the extractor. Set the output format of the extracted values to a table.

fs = 1/3600;
sFE = signalTimeFeatureExtractor(SampleRate=fs, ...
    FrameSize=168,Mean=true,FeatureFormat="table");

Call the extract function to extract the weekly average temperatures from the data set. The function does not include the readings taken in the last three days (72 hours) since they do not span a full week.

meantemps = extract(sFE,tt)

meantemps=4×3 table
    FrameStartTime    FrameEndTime     Mean  
    ______________    ____________    _______

           1              168         -1.8357
         169              336         -4.3095
         337              504          1.7976
         505              672          2.0911

Extract Features from Signal

Consider a quadratic chirp sampled at 1 kHz for 2 seconds. The chirp has an initial frequency of 100 Hz that increases to 200 Hz at t = 1 second. Compute and display the spectrogram.

fs = 1e3;
t = 0:1/fs:2;
y = chirp(t,100,1,200,"quadratic");
pspectrum(y,fs,"spectrogram")

Create a signalFrequencyFeatureExtractor object to obtain the mean and median frequencies from the signal. Specify the sample rate.

sFE = signalFrequencyFeatureExtractor(SampleRate=fs, ...
    MeanFrequency=true,MedianFrequency=true);

Extract the features. info returns the column index in features of each extracted feature.

[features,info] = extract(sFE,y)

features = 1×2

  226.0160  199.7034

info = struct with fields:
      MeanFrequency: 1
    MedianFrequency: 2

Set the FrameSize and FrameRate properties of the feature extractor object to divide the signal into two frames. The first frame represents the chirp oscillating at the initial frequency of 100 Hz and the second frame represents the chirp oscillating at 200 Hz. Extract the mean and median frequencies for each frame and include the frame limits in the output.

sFE.FrameSize = round(length(y)/2);
sFE.FrameRate = 1000;
[features2,info2,frameLimits] = extract(sFE,y)

features2 = 2×2

  131.4921  124.9820
  331.2664  324.6992

info2 = struct with fields:
      MeanFrequency: 1
    MedianFrequency: 2

frameLimits = 2×2

           1        1001
        1001        2001

Input Arguments

sFE — Feature extractor object

signalFrequencyFeatureExtractor object | signalTimeFeatureExtractor object | signalTimeFrequencyFeatureExtractor object

Feature extractor object, specified as a signalFrequencyFeatureExtractor object, a signalTimeFeatureExtractor object, or a signalTimeFrequencyFeatureExtractor object.

x — Input signal

vector | matrix | timetable

Input signal, specified as a vector, matrix, or timetable.

If x is a timetable, you must specify the SampleRate property of the feature extractor object sFE. The sample rate in timetable x must equal the sample rate specified in sFE.

Data Types: single | double

sds — Datastore of input signals

signalDatastore object | audioDatastore object

Since R2024b

Datastore of input signals, specified as a signalDatastore object or an audioDatastore (Audio Toolbox) object. The extract function computes the features for each member of sds.

Initially, extract verifies that the data resulting from the first read operation of sds is a matrix, a timetable, a cell array containing a matrix, or a cell array containing a timetable. Every subsequent member of sds is assumed to have the same data format as the first.

Note

If sds contains members in nonhomogeneous data formats, you can get unexpected results or errors when using extract. A best practice is to ensure that the datastore object sds points to data of the same format at every read.

tf — Option to perform feature extraction in parallel

false or 0 (default) | true or 1

Since R2024b

Option to perform feature extraction in parallel, specified as either false or true.

By default, extract performs feature extraction in serial. If you set tf to true, then extract performs the feature extraction process using a parallel pool of workers only if:

• You have installed Parallel Computing Toolbox.

• You have enabled automatic pool creation in Parallel Settings or an open parallel pool exists. For more information on how to control your Parallel Settings, see Specify Your Parallel Settings (Parallel Computing Toolbox).

Otherwise, extract does not perform feature extraction and errors out.

Data Types: logical

Output Arguments

features — Extracted features

3-D array | table | cell array

Extracted features, returned as a 3-D array, table, or cell array. The format of the features features output depends on the value of the FeatureFormat property in the feature extractor object sFE and on whether you are extracting features from a signal x or a datastore object sds.

• If you set the FeatureFormat property of the input feature extractor object to "matrix", and you specify an input signal x, then extract returns features as an L-by-M-by-N array:

  • L is the number of frames.

  • M is the number of features extracted per frame.

  • N is the number of channels.

• If you set the FeatureFormat property of the input feature extractor object to "table", and you specify an input signal x, then extract returns the extracted features in a table with the frame limits listed in the first two table variables.

• If you specify an input datastore object sds with k members, the function returns a k-by-1 cell array. The kth element of the array contains the features extracted from the kth signal in sds in the specified format FeatureFormat. (since R2024b)

  • If you set FeatureFormat to "matrix", extract returns each element of the cell array as a matrix.

  • If you set FeatureFormat to "table", extract returns each element of the cell array as a table.

info — Feature information

structure | cell array

Feature information, returned as a structure. The function maps each feature to its column location in the output matrix features. This argument applies only when you set the FeatureFormat property of the input feature extractor object to "matrix".

If you specify an input datastore object sds with k members, the function returns a k-by1 cell array where each element is a feature information structure corresponding to a signal from sds. (since R2024b)

framelimits — Frame limits

matrix | cell array

Frame limits, returned as a matrix. The i-th row in framelimits contains the beginning and end limits of the i-th frame. This argument applies only when you set the FeatureFormat property of the input feature extractor object to "matrix".

If you specify an input datastore object sds with k members, the function returns a k-by1 cell array where each element is a matrix containing the frame limits corresponding to a signal from sds. (since R2024b)

Version History

Introduced in R2021b

R2024b: Extract scalar features from signal matrix or datastore object

The extract function supports extracting scalar signal features in time domain, frequency domain, and time-frequency domain from a signal matrix or datastore object input.

R2024b: Accelerate feature extraction with parallel computing

The UseParallel name-value argument in the extract function enables you to accelerate code by automatically running computations in parallel. You must have a Parallel Computing Toolbox license to use this functionality.

R2024a: Extract scalar features in time-frequency domain

The extract function supports extracting scalar signal features in time-frequency domain from a signal matrix input.