setExtractorParameters

Set nondefault parameter values for feature extractor object

Since R2021b

Syntax

setExtractorParameters(sFE,featureName)

setExtractorParameters(sFE,featureName,params)

Description

setExtractorParameters(sFE,featureName) sets all the parameters of the feature specified in featureName to their default values.

setExtractorParameters(sFE,featureName,params) sets the parameters specified in params.

Examples

Set Parameter Values for Feature Extraction

Create a signalFrequencyFeatureExtractor object to extract the Welch power spectral density (PSD) estimate of a signal consisting of a 100 Hz sinusoid in additive N(0,1) white noise. The sample rate is 1 kHz and the signal has a duration of 5 seconds.

fs = 1000;
t = 0:1/fs:5-1/fs;
x = cos(2*pi*100*t) + randn(size(t));

sFE = signalFrequencyFeatureExtractor(SampleRate=fs,WelchPSD=true);

For the PSD computation, set the OverlapLength to 25 samples and the FFTLength to 512 samples. Call the getExtractorParameters function on the object to view the PSD parameters.

setExtractorParameters(sFE,"WelchPSD",OverlapLength=25,FFTLength=1024)
params = getExtractorParameters(sFE,"WelchPSD")

params = struct with fields:
          FFTLength: 1024
    FrequencyVector: []
      OverlapLength: 25
             Window: []

Use the extract function to extract the Welch's PSD estimate of the signal. Plot the result.

feature = extract(sFE,x);

fvec = linspace(0,fs/2,length(feature));
plot(fvec,pow2db(abs(feature)))

xlabel("Frequency (Hz)")
ylabel("PSD (dB/Hz)")
grid

Input Arguments

sFE — Feature extractor object

signalFrequencyFeatureExtractor object | signalTimeFrequencyFeatureExtractor object

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

featureName — Name of feature

string scalar | character vector

Name of feature, specified as a string scalar or a character vector.

Specify featureName based on the feature extractor object specified in sFE.

• If you specify sFE as a signalFrequencyFeatureExtractor object, specify featureName as one of these:

  • Frequency-domain features: "OccupiedBandwidth", "PowerBandwidth", "PeakAmplitude", "PeakLocation", or "WelchPSD".

• If you specify sFE as a signalTimeFrequencyFeatureExtractor object, specify featureName as one of these:

  • Time-frequency analysis methods: "spectrogram", "synchrosqueezedspectrogram", "emd", "vmd", "scalogram", "synchrosqueezedscalogram", "wavelet", or "waveletpacket".

  • Time-frequency features: "SpectralEntropy", "TFRidges", "InstantaneousBandwidth", "InstantaneousFrequency", "InstantaneousEnergy", "WaveletEntropy", "TimeSpectrum", or "ScaleSpectrum".

Data Types: char | string

params — Parameters

name-value arguments | structure

Parameters, specified as name-value arguments or as a structure. Use this argument to set the parameters to extract the feature specified in featurename.

• You can specify multiple parameters for a feature at a time. The order of the parameters does not matter.

• setExtractorParameters updates all parameters of the feature specified in featureName. It sets the specified parameters to the specified values and the unspecified parameters to default values.

Specify params based on the feature specified in featurename.

Frequency-domain Features — Extractor parameters for signal features in frequency domain

parameters

Specify the parameters in this table to customize extracting signal features in frequency domain.

Feature Name	Parameter Name	Parameter Value
"OccupiedBandwidth"	Percentage	99 (default) | positive scalar less than 100
"PowerBandwidth"	RelativeAmplitude	10*log10(2) (default) | real-valued scalar
"PeakAmplitude" "PeakLocation"	PeakType	"maxima" (default) | "minima"
	MaxNumExtrema	1 (default) | positive integer scalar
	MinProminence	0 (default) | nonnegative scalar
	MinSeparation	0 (default) | nonnegative scalar
	FlatSelection	"center" (default) | "first" | "last" | "all"
"WelchPSD"	Window	Integer scalar | vector
	OverlapLength	Positive integer scalar
	FFTLength	Positive integer scalar
	FrequencyVector	Real-valued vector FrequencyVector cannot be specified simultaneously with FFTLength.

Example: setExtractorParameters(sfFE,"PeakAmplitude",PeakType="maxima",MaxNumExtrema=2) specifies the peak type and the maximum number of extrema as extraction parameters for the peak amplitude feature, and sets up the frequency-domain feature extractor object sfFE for extraction.

Example: PeakAmplitudeParams = struct("PeakType","maxima","MaxNumExtrema",2); setExtractorParameters(fFE,"PeakAmplitude",PeakAmplitudeParams) specifies a structure array PeakAmplitudeParams consisting of the peak type and the maximum number of extrema as extraction parameters for the peak amplitude feature. Then, setExtractorParameters uses PeakAmplitudeParams to set up the frequency-domain feature extractor object sfFE for extraction.

Time-frequency Analysis Methods — Extractor parameters for signal transforms in time-frequency domain

parameters

Specify the parameters in this table to customize computing the time-frequency domain representation of the signal.

Feature Name	Parameter Name	Parameter Value
"spectrogram"	Leakage	0.5 (default) | Scalar between 0 and 1
	OverlapPercent	Positive scalar less than 100
	TimeResolution	Scalar greater than 1 and less than signal duration.
"synchrosqueezedspectrogram"	Window	Vector of nonnegative scalars
"emd"	MaxNumIMF	10 (default) | positive integer scalar
	MaxNumExtrema	1 (default) | positive integer scalar
	MaxEnergyRatio	20 (default) | Scalar
	Interpolation	"spline" (default) | "pchip"
"vmd"	NumIMFs	5 (default) | Positive integer scalar
	CentralFrequencies	Vector of NumIMFs positive scalars
	PenaltyFactor	1000 (default) | Positive scalar
	InitializeMethod	"peaks" (default) | "random" | "grid"
"scalogram"	Wavelet	"morse" (default) | "amor" | "bump"
	VoicesPerOctave	10 (default) | Integer scalar between 1 and 48
	WaveletParameters	[3 60] (default) | Two-element vector
	Frequencylimits	Two-element row vector of real-valued scalars
"synchrosqueezedscalogram"	Wavelet	"morse" (default) | "amor" | "bump"
	VoicesPerOctave	32 (default) | Even integer scalar between 10 and 48
	ExtendSignal	false or 0 (default) | true or 1
"wavelet" "waveletpacket"	FullTree ("waveletpacket" only)	false or 0 (default) | true or 1
	Wname	"sym4" (default for wavelet) | "fk18" (default for waveletpacket) | character vector | string scalar
	LowPass HighPass	Vectors of at least two scalars You must specify LowPass and HighPass simultaneously and with vectors of the same length.
	Level	Positive integer scalar
	Reflection ("wavelet" only)	strings(0) (default) | "reflection"

Example: setExtractorParameters(stfFE,"emd",Interpolation="spline",MaxNumExtrema=2) specifies the interpolation method and the maximum number of extrema as extraction parameters for the empirical mode decomposition (EMD), and sets up the time-frequency feature extractor object stfFE for extraction.

Time-frequency Features — Extractor parameters for signal features in time-frequency domain

parameters

Specify the parameters in this table to customize extracting signal features in time-frequency domain.

Feature Name	Parameter Name	Parameter Value
"SpectralEntropy"	Range	Two-element row vector of nonnegative scalars
"TFRidges"	NumRidges	1 (default) | Positive integer scalar
	NumFrequencyBins	4 (default) | Positive integer scalar
	Penalty	Nonnegative real-valued scalar
"InstantaneousBandwidth"	FrequencyLimits	Two-element row vector of real-valued scalars
	ScaleFactor	sqrt(4*pi) (default) | Positive scalar
"InstantaneousFrequency" "InstantaneousEnergy"	FrequencyLimits	Two-element row vector of real-valued scalars
	FrequencyResolution	-Inf (default) | Scalar
	MinThreshold	Real-valued scalar
"WaveletEntropy"	Entropy	"Shannon" (default) | "Renyi" | "Tsallis"
	Exponent	2 (default) | Real-valued scalar
	Distribution	"scale" (default) | "global"
	Scaled	true or 1 (default) | false or 0
"TimeSpectrum"	Normalization	"var" (default) | "pdf" | "none"
	SpectrumType	"power" (default) | "density"
	TimeLimits	Two-element vector of real-valued scalars
"ScaleSpectrum"	Normalization	"var" (default) | "pdf" | "none"
	SpectrumType	"power" (default) | "density"
	FrequencyLimits	Two-element vector of real-valued scalars

Note

• The InstantaneousFrequency feature supports the FrequencyResolution and MinThreshold parameters only when Transform is "emd", "vmd", "wavelet", or "waveletpacket".

• The InstantaneousEnergy feature supports feature extraction parameters only when Transform is "emd".

Example: setExtractorParameters(stfFE,"TFRidges",NumRidges=3,NumFrequencyBins=10) specifies the number of ridges and number of frequency bins as extraction parameters for the time-frequency-ridges feature, and sets up the time-frequency feature extractor object stfFE for extraction.

Data Types: string | struct

Tips

• Use the getExtractorParameters function to get the list of available parameters to use when extracting the features that you enabled when creating the feature extractor object.

Version History

Introduced in R2021b