Main Content

signalFrequencyFeatureExtractor

Streamline signal frequency feature extraction

    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

    sFE = signalFrequencyFeatureExtractor creates a signalFrequencyFeatureExtractor object with default property values.

    example

    sFE = signalFrequencyFeatureExtractor(Name,Value) specifies nondefault property values of the signalFrequencyFeatureExtractor object. For example, signalFrequencyFeatureExtractor(FrameSize=30,FrameOverlapLength=6) divides the signal into overlapping 30-sample frames and extracts features from each frame.

    Properties

    expand all

    Main Properties

    Number of samples in a 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

    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 FrameRate is assumed to be equal to FrameSize. You cannot specify FrameRate and FrameOverlapLength simultaneously.

    Data Types: single | double

    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

    Input sample rate, specified as a positive scalar in hertz.

    Data Types: single | double

    Format of generated features, specified as "matrix" or "table". The extract function returns features as one of these:

    • matrix — Matrix with columns corresponding to feature values.

    • table — Table with each table variable corresponding to a feature value.

    Data Types: char | string

    Rule to handle incomplete frames, specified as "drop" or "zeropad". This rule applies when the current frame size is less than the specified FrameSize property.

    • 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.

    Data Types: char | string

    Features to Extract

    Option to extract the mean frequency of the power spectrum, specified as true or false. If you specify MeanFrequency as true, the object extracts the mean frequency of the power spectrum and appends it to the features returned by the extract function.

    Data Types: logical

    Option to extract the median frequency of the power spectrum, specified as true or false. If you specify MedianFrequency as true, the object extracts the median frequency of the power spectrum and appends it to the features returned by the extract function.

    Data Types: logical

    Option to extract the average band power, specified as true or false. If you specify BandPower as true, the object extracts the band power and appends it to the features returned by the extract function.

    Data Types: logical

    Option to extract the 99% occupied bandwidth, specified as true or false. If you specify OccupiedBandwidth as true, the 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

    Option to extract the 3 dB (half-power) bandwidth, specified as true or false. If you specify PowerBanwidth as true, the 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

    Option to extract the power spectral density (PSD) estimate, specified as true or false. If you specify WelchPSD as true, the 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

    Option to extract the peak spectral amplitudes, specified as true or false. If you specify PeakAmplitude as true, the 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

    Option to extract the spectral peak locations, specified as true or false. If you specify PeakLocation as true, the 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

    extractExtract time-domain or frequency-domain features
    generateMATLABFunctionCreate MATLAB function compatible with C/C++ code generation
    getExtractorParametersGet current parameter values of feature extractor object
    setExtractorParametersSet nondefault values for feature extractor object

    Examples

    collapse all

    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.

    nSamp = 1024;
    Fs = 1024e3;
    SNR = 40;
    
    t = (0:nSamp-1)'/Fs;
    
    x = chirp(t,50e3,nSamp/Fs,100e3);
    x = x+randn(size(x))*std(x)/db2mag(SNR);
    meanfreq(x,Fs)

    Figure contains an axes object. The axes object with title Mean Frequency Estimate: 75.032 kHz contains 2 objects of type line.

    ans = 7.5032e+04
    

    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×3
    104 ×
    
        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";
    features = extract(sFE,x)
    features=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)
    features2 = extract(sFE,x)
    features2=1×5 table
        FrameStartTime    FrameEndTime    MeanFrequency    OccupiedBandwidth    PowerBandwidth
        ______________    ____________    _____________    _________________    ______________
    
              1               1024            72252              39840              37773     
    
    

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    Introduced in R2021b