setExtractorParameters

Set nondefault parameter values for feature extractor object

Since R2021b

collapse all in page

    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.

    example

    Examples

    collapse all

    Open Live Script

    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

    collapse all

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

    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

    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.

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

    Feature NameParameter NameParameter 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.

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

    Feature NameParameter NameParameter 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.

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

    Feature NameParameter NameParameter 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

    See Also

    Objects

    Functions