# signalFrequencyFeatureExtractor

## Description

Use `signalFrequencyFeatureExtractor`

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

## Creation

### Description

creates a `sFE`

= signalFrequencyFeatureExtractor`signalFrequencyFeatureExtractor`

object with default property
values.

specifies nondefault property values of the
`sFE`

= signalFrequencyFeatureExtractor(`Name=Value`

)`signalFrequencyFeatureExtractor`

object. For example,
`signalFrequencyFeatureExtractor(FrameSize=30,FrameOverlapLength=6)`

divides the signal into overlapping 30-sample frames and extracts features from each
frame.

## 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`

. 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

`frequencyScalarFeatureOptions`

object

*Since R2024b*

Methods to convert feature vectors to scalar values, specified as a `frequencyScalarFeatureOptions`

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`signalFrequencyFeatureExtractor`

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

`signalFrequencyFeatureExtractor`

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

`frequencyScalarFeatureOptions`

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`signalFrequencyFeatureExtractor`

object does not perform any scalarization.

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

### Features to Extract

`MeanFrequency`

— Option to extract mean frequency

`false`

(default) | `true`

Option to extract the mean frequency of the power spectrum, specified as
`true`

or `false`

. If you specify
`MeanFrequency`

as true, the `signalFrequencyFeatureExtractor`

object
extracts the mean frequency of the power spectrum and appends it to the features
returned by the `extract`

function.

**Data Types: **`logical`

`MedianFrequency`

— Option to extract median frequency

`false`

(default) | `true`

Option to extract the median frequency of the power spectrum, specified as
`true`

or `false`

. If you specify
`MedianFrequency`

as true, the `signalFrequencyFeatureExtractor`

object extracts the median frequency of the power spectrum and appends it to the
features returned by the `extract`

function.

**Data Types: **`logical`

`BandPower`

— Option to extract average band power

`false`

(default) | `true`

Option to extract the average band power, specified as `true`

or
`false`

. If you specify `BandPower`

as true, the
`signalFrequencyFeatureExtractor`

object extracts the band power and appends it to the
features returned by the `extract`

function.

**Data Types: **`logical`

`OccupiedBandwidth`

— Option to extract occupied bandwidth

`false`

(default) | `true`

Option to extract the 99% occupied bandwidth, specified as `true`

or `false`

. If you specify `OccupiedBandwidth`

as
true, the `signalFrequencyFeatureExtractor`

object extracts the 99% occupied bandwidth and
appends it to the features returned by the `extract`

function.

To set parameters of the occupied bandwidth extraction, use `setExtractorParameters`

.

`setExtractorParameters(sFE,"OccupiedBandwidth",Name=Value)`

Settable parameters for the occupied bandwidth extraction are:

`Percentage`

— Power percentage, specified as a positive integer between`0`

and`100`

.

**Data Types: **`logical`

`PowerBandwidth`

— Option to extract half-power bandwidth

`false`

(default) | `true`

Option to extract the 3 dB (half-power) bandwidth, specified as
`true`

or `false`

. If you specify
`PowerBanwidth`

as true, the `signalFrequencyFeatureExtractor`

object
extracts the 3 dB bandwidth value and appends it to the features returned by the
`extract`

function.

To set parameters of the half-power bandwidth extraction, use `setExtractorParameters`

.

`setExtractorParameters(sFE,"PowerBandwidth",Name=Value)`

Settable parameters for the half-power bandwidth extraction are:

`RelativeAmplitude`

— Relative amplitude, specified as an integer.

**Data Types: **`logical`

`WelchPSD`

— Option to extract power spectral density estimate

`false`

(default) | `true`

Option to extract the power spectral density (PSD) estimate, specified as
`true`

or `false`

. If you specify
`WelchPSD`

as true, the `signalFrequencyFeatureExtractor`

object
extracts the PSD estimate using Welch's method and appends it to the features returned
by the `extract`

function.

To set parameters of the Welch's PSD estimate, use `setExtractorParameters`

.

`setExtractorParameters(sFE,"WelchPSD",Name=Value)`

Settable parameters for the Welch's PSD estimate extraction are:

`FFTLength`

— Number of DFT points, specified as a positive integer.`FrequencyVector`

— Frequencies at which the PSD is estimated, specified as a vector with at least two elements. You can specify`FrequencyVector`

only when`FFTLength`

is not specified.`OverlapLength`

— Number of overlapping samples, specified as a positive integer.`Window`

— Window, specified as a scalar or vector.

**Data Types: **`logical`

`PeakAmplitude`

— Option to extract peak amplitude

`false`

(default) | `true`

Option to extract the peak spectral amplitudes, specified as
`true`

or `false`

. If you specify
`PeakAmplitude`

as true, the `signalFrequencyFeatureExtractor`

object
extracts the peak amplitudes of the computed Welch PSD estimate and appends them to
the features returned by the `extract`

function.

To set parameters of the peak amplitude extraction, use `setExtractorParameters`

.

`setExtractorParameters(sFE,"PeakAmplitude",Name=Value)`

Settable parameters for the peak amplitude extraction are:

`PeakType`

— Type of peak, specified as`"minima"`

or`"maxima"`

.`MaxNumExtrema`

— Maximum number of peaks, specified as a positive integer scalar.`MinProminence`

— Minimum prominence, specified as a positive scalar. The object returns only peaks whose prominence is at least the value specified.`MinSeparation`

— Minimum separation between peaks, specified as a positive scalar.`FlatSelection`

— Flat region indicator, specified as one of these:`"center"`

— Indicate only the center element of a flat region as the peak.`"first"`

— Indicate only the first element of a flat region as the peak.`"last"`

— Indicate only the last element of a flat region as the peak.`"all"`

— Indicate all elements of a flat region as the peak.

**Data Types: **`logical`

`PeakLocation`

— Option to extract peak location

`false`

(default) | `true`

Option to extract the spectral peak locations, specified as
`true`

or `false`

. If you specify
`PeakLocation`

as true, the `signalFrequencyFeatureExtractor`

object
extracts the peak locations of the computed Welch PSD estimate and appends them to the
features returned by the `extract`

function.

To set parameters of the peak location extraction, use `setExtractorParameters`

.

`setExtractorParameters(sFE,"PeakLocation",Name=Value)`

Settable parameters for the peak location extraction are:

`PeakType`

— Type of peak, specified as`"minima"`

or`"maxima"`

.`MaxNumExtrema`

— Maximum number of peaks, specified as a positive integer scalar.`MinProminence`

— Minimum prominence, specified as a positive scalar. The`setExtractorParameters`

function returns only peaks whose prominence is at least the value specified.`MinSeparation`

— Minimum separation between peaks, specified as a positive scalar.`FlatSelection`

— Flat region indicator, specified as one of these:`"center"`

— Indicate only the center element of a flat region as the peak.`"first"`

— Indicate only the first element of a flat region as the peak.`"last"`

— Indicate only the last element of a flat region as the peak.`"all"`

— Indicate all elements of a flat region as the peak.

**Data Types: **`logical`

**Note**

To compute frequency features, `signalFrequencyFeatureExtractor`

first
estimates the PSD of the input time-domain signal using Welch's method. The object uses
the computed Welch PSD and corresponding frequency vector to compute the specified
features. You can configure the computed Welch PSD estimate using the `setExtractorParameters`

function.

## Object Functions

`extract` | Extract time-domain, frequency-domain, or time-frequency-domain features |

`generateMATLABFunction` | Create MATLAB function compatible with C/C++ code generation |

`getExtractorParameters` | Get current parameter values of feature extractor object |

`setExtractorParameters` | Set nondefault parameter values for feature extractor object |

## Examples

### Extract Frequency-Domain Features From Signal

Generate 1024 samples of a chirp sampled at 1024 kHz. The chirp has an initial frequency of 50 kHz and reaches 100 kHz at the end of the sampling. Add white Gaussian noise such that the signal-to-noise ratio is 40 dB. Plot the power spectral density (PSD) and annotate the mean frequency and occupied bandwidth of the signal.

nSamp = 1024; Fs = 1024e3; SNR = 40; t = (0:nSamp-1)'/Fs; x0 = chirp(t,50e3,nSamp/Fs,100e3); x = x0+randn(size(x0))*std(x0)/db2mag(SNR); [pxx,f]= pwelch(x,[],[],[],Fs); obw(pxx,f); m = meanfreq(pxx,f); xline(m/1000,"--", ... "Mean Frequency Estimate: "+m/1000+" kHz")

Create a `signalFrequencyFeatureExtractor`

object to extract the mean frequency, 99% occupied bandwidth, and 3 dB bandwidth of the signal.

```
sFE = signalFrequencyFeatureExtractor(SampleRate=Fs, ...
MeanFrequency=true,OccupiedBandwidth=true,PowerBandwidth=true)
```

sFE = signalFrequencyFeatureExtractor with properties: Properties FrameSize: [] FrameRate: [] SampleRate: 1024000 IncompleteFrameRule: "drop" FeatureFormat: "matrix" Enabled Features MeanFrequency, OccupiedBandwidth, PowerBandwidth Disabled Features MedianFrequency, BandPower, WelchPSD, PeakAmplitude, PeakLocation

Call the `extract`

function to extract the specified features.

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

features =1×310^{4}× 7.2252 4.3783 3.7773

`info = `*struct with fields:*
MeanFrequency: 1
OccupiedBandwidth: 2
PowerBandwidth: 3

To view the extracted features in a table, modify the `FeatureFormat`

property of the object.

```
sFE.FeatureFormat = "table";
featureTable = extract(sFE,x)
```

`featureTable=`*1×5 table*
FrameStartTime FrameEndTime MeanFrequency OccupiedBandwidth PowerBandwidth
______________ ____________ _____________ _________________ ______________
1 1024 72252 43783 37773

You can use the `getExtractorParameters`

function to view parameters used to compute a specified feature. The occupied bandwidth measures the bandwidth containing 99% of the total power for the input signal by default. Use the `setExtractorParameters`

function to change the percentage to 95% and extract the specified features again.

`params = getExtractorParameters(sFE,"OccupiedBandwidth")`

`params = `*struct with fields:*
Percentage: []

params.Percentage = 95; setExtractorParameters(sFE,OccupiedBandwidth=params) featuresTable2 = extract(sFE,x)

`featuresTable2=`*1×5 table*
FrameStartTime FrameEndTime MeanFrequency OccupiedBandwidth PowerBandwidth
______________ ____________ _____________ _________________ ______________
1 1024 72252 39840 37773

## More About

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

**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}}{{\left(\frac{1}{N}{\displaystyle \sum _{i=1}^{N}\sqrt{\left|{v}_{i}\right|}}\right)}^{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}{\displaystyle \sum _{i=1}^{N}{v}_{i}{}^{2}}}}$$

`"Energy"`

— Energy, defined as the sum of the squared values of*v*.$$s={\displaystyle \sum _{i=1}^{N}{v}_{i}{}^{2}}$$

`"Entropy"`

— Entropy, defined as the sum of*p*log_{2}*p*values, where*p*is the vector of normalized squared values of*v*with respect to their sum.$$s={\displaystyle \sum _{i=1}^{N}{p}_{i}{\mathrm{log}}_{2}{p}_{i}},$$

where

$$p=\frac{{v}^{2}}{{\displaystyle \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}{\displaystyle \sum _{i=1}^{N}\left|{v}_{i}\right|}}$$

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

You cannot generate code directly from

`signalFrequencyFeatureExtractor`

. 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 R2021b**

### R2024b: Specify scalarization methods for frequency-domain signal features

The `signalFrequencyFeatureExtractor`

function supports specifying methods to extract
scalar features in frequency domain.

### R2023a: Use `gpuArray`

inputs

The `signalFrequencyFeatureExtractor`

object supports `gpuArray`

inputs. You
must have Parallel Computing Toolbox™ to use this functionality.

## See Also

### Functions

### Objects

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)