setExtractorParameters

Set nondefault parameter values for feature extractor object

Since R2021b

collapse all in page

    The function has changed. For more information, see Version History.

    Syntax

    setExtractorParameters(freqFE,freqFeatureName,freqFeatureParams)
    setExtractorParameters(tfFE,tfAnalysisName,tfAnalysisParams)
    setExtractorParameters(tfFE,tfFeatureName,tfFeatureParams)

    Description

    setExtractorParameters(freqFE,freqFeatureName,freqFeatureParams) sets the parameters specified in freqFeatureParams to the frequency-domain feature specified in freqFeatureName. The feature extractor object freqFE uses the specified parameters to set up feature extraction.

    example

    setExtractorParameters(tfFE,tfAnalysisName,tfAnalysisParams) sets the parameters specified in tfAnalysisParams to the time-frequency analysis method specified in tfAnalysisName. The feature extractor object tfFE uses the specified parameters to set up feature extraction.

    setExtractorParameters(tfFE,tfFeatureName,tfFeatureParams) sets the parameters specified in tfFeatureParams to the time-frequency feature specified in tfFeatureName. The feature extractor object tfFE uses the specified parameters to set up feature extraction.

    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.

    psdFeature = extract(sFE,x);

f = linspace(0,Fs/2,length(psdFeature));
plot(f,pow2db(abs(psdFeature)))

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

    Figure contains an axes object. The axes object with xlabel Frequency (Hz), ylabel PSD (dB/Hz) contains an object of type line.

    Input Arguments

    collapse all

    Frequency Domain

    Frequency feature extractor, specified as a signalFrequencyFeatureExtractor object.

    Name of frequency feature, specified as one of these values:

    • "OccupiedBandwidth" — Occupied bandwidth

    • "PowerBandwidth" — Power bandwidth

    • "PeakAmplitude" — Amplitudes of spectral peaks

    • "PeakLocation" — Locations of spectral peaks

    • "WelchPSD" — Welch's power spectral density estimate

    Data Types: char | string

    Parameters for frequency feature, specified as name-value arguments or as a struct array. Use this argument to set the parameters to extract the feature specified in freqFeatureName.

    This table lists the parameters that you can set for frequency-domain signal features. You can specify multiple parameters for a feature at a time. The order of the specified parameters does not matter.

    Feature NameParameter NameParameter Value
    "OccupiedBandwidth"Percentage — Power percentage

    99 (default) | positive scalar less than 100

    For more information, see obw.

    "PowerBandwidth"RelativeAmplitude — Power level drop, in dB

    10*log10(2) (default) | real-valued scalar

    For more information, see powerbw.

    "PeakAmplitude"
    "PeakLocation"    		PeakType — Type of peak

    "maxima" (default) | "minima"

    MaxNumExtrema — Maximum number of peaks

    1 (default) | positive integer scalar

    MinProminence — Minimum prominence

    0 (default) | nonnegative scalar

    MinSeparation — Minimum peak separation

    0 (default) | nonnegative scalar

    FlatSelection — Element of a flat region to indicate as peak

    "center" (default) | "first" | "last" | "all"

    For more information about these parameters, see islocalmax or islocalmin.

    "WelchPSD"Window — Window to partition input signal into segments

    Integer scalar | vector

    OverlapLength — Number of overlapping samples

    Positive integer scalar

    FFTLength — Number of DFT points

    Positive integer scalar

    FrequencyVector — Frequencies at which to estimate PSD

    Real-valued vector

    FrequencyVector cannot be specified simultaneously with FFTLength.

    For more information about these parameters, see pwelch.

    Example: setExtractorParameters(freqFE,"PeakAmplitude",PeakType="maxima",MaxNumExtrema=2) specifies the peak type and the maximum number of extrema parameters for the PeakAmplitude feature using name-value arguments.

    Example: PeakAmplitudeParams = struct(PeakType="maxima",MaxNumExtrema=2); setExtractorParameters(freqFE,"PeakAmplitude",PeakAmplitudeParams) specifies the peak type and the maximum number of extrema parameters for the PeakAmplitude feature using a struct array.

    Data Types: string | struct

    Time-Frequency Domain

    Time-frequency feature extractor, specified as a signalTimeFrequencyFeatureExtractor object.

    Name of time-frequency analysis method, specified as one of these values:

    • "spectrogram" — Short-time Fourier transform

    • "synchrosqueezedspectrogram" — Fourier synchrosqueezed transform

    • "emd" — Empirical mode decomposition

    • "vmd" — Variational mode decomposition

    • "scalogram" — Continuous wavelet transform magnitude

    • "synchrosqueezedscalogram" — Wavelet synchrosqueezed transform

    • "wavelet" — Maximal overlap discrete wavelet transform

    • "waveletpacket" — Maximal overlap discrete wavelet packet transform

    Data Types: char | string

    Parameters for time-frequency analysis method, specified as name-value arguments or as a struct array. Use this argument to set the parameters to extract the feature specified in tfAnalysisName.

    This table lists the parameters that you can set for time-frequency analysis methods. You can specify multiple parameters for an analysis method at a time. The order of the specified parameters does not matter.

    Feature NameParameter NameParameter Value
    "spectrogram"Leakage — Spectral leakage

    0.5 (default) | scalar between 0 and 1

    OverlapPercent — Overlap between adjoining segments

    Positive scalar less than 100

    TimeResolution — Time resolution

    Scalar greater than 1 and less than signal duration

    For more information about these parameters, see pspectrum.

    "synchrosqueezedspectrogram"Window — Window for partitioning input signal into segments

    Vector of nonnegative scalars

    For more information, see fsst.

    "emd"Interpolation — Interpolation method to construct envelope

    "spline" (default) — For smooth input signal |
    "pchip" — For nonsmooth input signal

    MaxEnergyRatio — Signal to residual energy ratio

    20 (default) | real-valued scalar

    MaxNumExtrema — Maximum number of extrema in residual signal

    1 (default) | positive integer scalar

    MaxNumIMF — Maximum number of intrinsic mode functions

    10 (default) | positive integer scalar

    For more information about these parameters, see emd.

    "vmd"CentralFrequencies — Initial central IMF frequencies

    Vector of NumIMFs positive scalars

    InitializeMethod — Method to initialize central frequencies

    "peaks" (default) — Peak frequencies of the signal in frequency domain |
    "random" — Random frequencies uniformly distributed within [0, 0.5] cycles/sample interval |
    "grid" — Uniformly sampled grid of frequencies from 0 to 0.5 cycles/sample

    NumIMFs — Number of intrinsic mode functions

    5 (default) | positive integer scalar

    PenaltyFactor — Penalty factor

    1000 (default) | positive scalar

    For more information about these parameters, see vmd.

    "scalogram"

    Boundary — Signal extension boundary

    "reflection" (default) — Extend signal symmetrically at the left and right boundaries |
    "periodic" — Extend signal periodically |
    "zeropad" — Pad signal boundaries with zeros

    Frequencylimits — Frequency limits

    Two-element row vector of real-valued scalars

    VoicesPerOctave — Number of voices per octave

    10 (default) | integer scalar between 1 and 48

    Wavelet — Name of analytic wavelet

    "morse" (default) — Analytic Morse wavelet |
    "amor" — Analytic Morlet wavelet |
    "bump" — Bump wavelet

    WaveletParameters — Symmetry and time-bandwidth product of the Morse wavelet

    [3 60] (default) | two-element vector

    For more information about these parameters, see cwt (Wavelet Toolbox).

    "synchrosqueezedscalogram"

    Boundary — Signal extension boundary

    "reflection" (default) — Extend signal symmetrically at the left and right boundaries |
    "periodic" — Extend signal periodically |
    "zeropad" — Pad signal boundaries with zeros

    VoicesPerOctave — Number of voices per octave

    32 (default) | even integer scalar between 10 and 48

    Wavelet — Name of analytic wavelet

    "morse" (default) — Analytic Morse wavelet |
    "amor" — Analytic Morlet wavelet |
    "bump" — Bump wavelet

    For more information about these parameters, see wsst (Wavelet Toolbox).

    "wavelet"HighPass — Wavelet (highpass) filter
    LowPass — Scaling (lowpass) filter

    Even-length real-valued vectors

    You must specify LowPass and HighPass simultaneously and with the same length.
    Do not specify these parameters if you specify Wname.

    Level — Transform level

    Positive integer scalar less than or equal to floor(log2(N)), where N is the signal length.

    Reflection — Option to use reflection boundary handling

    strings(0) (default) | "reflection"

    Wname — Wavelet name

    "sym4" (default) | character vector | string scalar

    For more information about these parameters, see modwt (Wavelet Toolbox).

    "waveletpacket"FullTree — Option to return full wavelet packet tree

    false or 0 (default) | true or 1

    HighPass — Wavelet (highpass) filter
    LowPass — Scaling (lowpass) filter

    Even-length real-valued vectors

    You must specify LowPass and HighPass simultaneously and with vectors of the same length. Do not specify these parameters if you specify Wname.

    Level — Transform level

    Positive integer scalar less than or equal to floor(log2(N)), where N is the signal length.

    Wname — Wavelet name

    "fk18" (default) | character vector | string scalar

    For more information about these parameters, see modwpt (Wavelet Toolbox).

    Example: setExtractorParameters(tfFE,"emd",Interpolation="spline",MaxNumExtrema=2) specifies the interpolation method and the maximum number of extrema parameters for the empirical mode decomposition (EMD) analysis method using name-value arguments.

    Example: emdParams = struct(Interpolation="spline",MaxNumExtrema=2); setExtractorParameters(tfFE,"emd",emdParams) specifies the interpolation method and the maximum number of extrema parameters for the EMD analysis method using a struct array.

    Data Types: string | struct

    Name of time-frequency feature, specified as one of these values:

    • "SpectralEntropy" — Spectral entropy

    • "TFRidges" — Time-frequency ridges

    • "InstantaneousBandwidth" — Instantaneous bandwidth

    • "InstantaneousFrequency" — Instantaneous frequency

    • "InstantaneousEnergy" — Instantaneous energy

    • "WaveletEntropy" — Wavelet entropy

    • "TimeSpectrum" — Time spectrum

    • "ScaleSpectrum" — Scale spectrum

    Data Types: char | string

    Parameters for time-frequency feature, specified as name-value arguments or as a struct array. Use this argument to set the parameters to extract the feature specified in tfFeatureName.

    This table lists the parameters that you can set for time-frequency signal features. You can specify multiple parameters for a feature at a time. The order of the specified parameters does not matter.

    Feature NameParameter NameParameter Value
    "SpectralEntropy"Range — Frequency range, in Hz

    Two-element row vector of nonnegative scalars

    For more information, see spectralEntropy.

    "TFRidges"NumRidges — Number of time-frequency ridges

    1 (default) | Positive integer scalar

    NumFrequencyBins — Number of bins to remove when extracting multiple ridges

    4 (default) | Positive integer scalar

    Penalty — Penalty for changing frequency

    Nonnegative real-valued scalar

    For more information about these parameters, see tfridge.

    "InstantaneousBandwidth"FrequencyLimits — Frequency range, in Hz

    Two-element row vector of real-valued scalars

    ScaleFactor — Scaling factor for spectral moment

    sqrt(4*pi) (default) | Positive scalar

    For more information about these parameters, see instbw.

    "InstantaneousFrequency"

    Note

    This feature supports the FrequencyResolution and MinThreshold parameters for these analysis methods: "emd", "vmd", "wavelet", and "waveletpacket".

    		FrequencyLimits — Frequency range, in Hz

    Two-element row vector of real-valued scalars

    FrequencyResolution — Frequency resolution to discretize frequency limits

    -Inf (default) | scalar

    MinThreshold — Minimum threshold value of Hilbert spectrum

    Real-valued scalar

    For more information, see instfreq or hht.

    "InstantaneousEnergy"

    Note

    This feature supports extraction parameters for these analysis methods: "emd", "vmd", "wavelet", and "waveletpacket".

    		FrequencyLimits — Frequency limits to compute Hilbert spectrum

    Two-element row vector of real-valued scalars

    FrequencyResolution — Frequency resolution to discretize frequency limits

    -Inf (default) | scalar

    MinThreshold — Minimum threshold value of Hilbert spectrum

    Real-valued scalar

    For more information about these parameters, see hht.

    "WaveletEntropy"Entropy — Entropy measure

    "Shannon" (default) | "Renyi" | "Tsallis"

    Exponent — Exponent for Renyi and Tsallis entropy

    2 (default) | Real-valued scalar

    Distribution — Normalization method for empirical probability distribution and wavelet transform coefficients

    "scale" (default) — Normalize the squared magnitudes of the coefficients by their total sum |
    "global" — Normalize the wavelet coefficients at each scale

    Scaled — Option to scale wavelet entropy

    true or 1 (default) | false or 0

    For more information about these parameters, see wentropy (Wavelet Toolbox).

    "TimeSpectrum"Normalization — Normalization method for time-averaged wavelet spectrum

    "var" (default) — Normalize to equal the variance of the input signal |
    "pdf" — Normalize to equal 1 |
    "none" — Do not normalize

    SpectrumType — Type of wavelet spectrum

    "power" (default) — Normalize the averaged sum of the time-averaged wavelet spectrum |
    "density" — Normalize the weighted integral of the wavelet spectrum

    TimeLimits — Time limits for averaging wavelet spectrum

    Two-element vector of real-valued scalars

    For more information about these parameters, see timeSpectrum (Wavelet Toolbox).

    "ScaleSpectrum"Normalization — Normalization method for time-averaged wavelet spectrum

    "var" (default) — Normalize to equal the variance of the input signal |
    "pdf" — Normalize to equal 1 |
    "none" — Do not normalize

    SpectrumType — Type of wavelet spectrum

    "power" (default) — Normalize the averaged sum of the time-averaged wavelet spectrum |
    "density" — Normalize the weighted integral of the wavelet spectrum

    FrequencyLimits — Frequency limits for averaging magnitude-squared scalogram

    Two-element vector of real-valued scalars

    For more information about these parameters, see scaleSpectrum (Wavelet Toolbox).

    Example: setExtractorParameters(tfFE,"TFRidges",NumRidges=3,NumFrequencyBins=10) specifies the number of ridges and number of frequency bins parameters for the TFRidges feature using name-value arguments.

    Example: tfRidgesParams = struct(NumRidges=3,NumFrequencyBins=10); setExtractorParameters(tfFE,"TFRidges",tfRidgesParams) specifies the number of ridges and number of frequency bins parameters for the TFRidges feature using a struct array.

    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

    expand all

    See Also

    Objects

    Functions