Main Content

faultBandMetrics

Spectral metrics for the specified fault frequency bands of the power spectral density (PSD)

Description

example

spectralMetrics = faultBandMetrics(psd,freqGrid,FB)returns a set of spectral metrics spectralMetrics for the power spectral density (PSD) data psd defined at the frequencies specified in freqGrid for each fault frequency range in FB.

The output spectralMetrics includes peak amplitude, peak frequency, and band powers for each frequency range specified in FB along with the total band power across all frequency bands.

example

spectralMetrics = faultBandMetrics(X,FB) returns a set of spectral metrics spectralMetrics for the PSD and frequency grid data specified in the cell array X. faultBandMetrics assumes that the last column of data in each cell of X contains the frequency grid while the first column contains PSD data. If the data is not in the same order, then use the 'SpectrumColumn' and 'FrequencyColumn' name-value pair arguments to specify the column numbers or names of the PSD data and the frequency grid, respectively. The output spectralMetrics has as many rows as the length of cell array X.

example

spectralMetrics = faultBandMetrics(T,FB) returns a set of spectral metrics spectralMetrics for the PSD and frequency grid data specified in the dataset T.

T can be a table/timetable or an ensemble, where a member variable of matrices or tables should contain the PSD data corresponding to one experiment. The last column of data in the member variable should contain the frequency grid and the first column should contain the PSD data.

If T is not in the same order, then use the 'SpectrumColumn' and 'FrequencyColumn' name-value pair arguments to specify the column numbers or names of the PSD data and the frequency grid, respectively. The output spectralMetrics has as many rows as the number of rows in dataset T.

example

spectralMetrics = faultBandMetrics(___,Name,Value) allows you to specify additional parameters using one or more name-value pair arguments.

example

[spectralMetrics,info] = faultBandMetrics(___) also returns a structure info with additional information about the table or fileEnsembleDatastore object variables used to compute spectralMetrics.

Examples

collapse all

For this example, consider a simple gear set with an 8-toothed pinion on the input shaft meshing with a 42-toothed spur gear on the output shaft. Assume that the input shaft is driven at 20 Hz. The dataset motorSignal.mat contains vibration data for the gear mesh sampled at 1500 Hz.

First, construct the gear mesh frequency bands using the physical characteristics of the gear set. Construct the frequency bands with the first 3 sidebands and specify the 'Domain' as 'order'.

Ni = 8;
No = 42;
FR = 20;
FB = gearMeshFaultBands(FR,Ni,No,'Sidebands',1:3,'Domain','order')
FB = 15×2

    0.9500    1.0500
    0.1405    0.2405
    3.9500    4.0500
    4.9500    5.0500
    5.9500    6.0500
    6.9500    7.0500
    8.9500    9.0500
    9.9500   10.0500
   10.9500   11.0500
    7.3786    7.4786
      ⋮

FB is a 15x2 array which includes the primary frequencies and their sidebands.

Load the vibration data and compute PSD and frequency grid using pspectrum. Use a frequency resolution of 0.5.

load('motorSignal.mat','C');
fs = 1500;
[psd,freqGrid] = pspectrum(C,fs,'FrequencyResolution',0.5);

Now, use the frequency bands and PSD data to compute the spectral metrics.

spectralMetrics = faultBandMetrics(psd,freqGrid,FB)
spectralMetrics=1×46 table
    PeakAmplitude1    PeakFrequency1    BandPower1    PeakAmplitude2    PeakFrequency2    BandPower2    PeakAmplitude3    PeakFrequency3    BandPower3    PeakAmplitude4    PeakFrequency4    BandPower4    PeakAmplitude5    PeakFrequency5    BandPower5    PeakAmplitude6    PeakFrequency6    BandPower6    PeakAmplitude7    PeakFrequency7    BandPower7    PeakAmplitude8    PeakFrequency8    BandPower8    PeakAmplitude9    PeakFrequency9    BandPower9    PeakAmplitude10    PeakFrequency10    BandPower10    PeakAmplitude11    PeakFrequency11    BandPower11    PeakAmplitude12    PeakFrequency12    BandPower12    PeakAmplitude13    PeakFrequency13    BandPower13    PeakAmplitude14    PeakFrequency14    BandPower14    PeakAmplitude15    PeakFrequency15    BandPower15    TotalBandPower
    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    ______________

       0.82564              1             0.1542         0.057165           0.1875         0.011175        0.29169              4            0.055249        0.011486             5           0.0021583        0.070117             6            0.013877         1.0514              7            0.21675        0.0077621             9            0.001577        0.004752             10          0.0010282        0.012155             11          0.0025085         7.7318             7.4375           1.4057           4.2222              7.625           0.79678          0.92456            7.8125           0.1924          0.030489            8.1875          0.0060835        0.069138             8.375          0.012642         0.068649            8.5625          0.012578          2.8848    

spectralMetrics is a 1x46 table with peak amplitude, peak frequency and band power calculated for each frequency range in FB. The last column in spectralMetrics is the total band power, computed across all 15 frequencies in FB.

For this example, consider a ball bearing with a pitch diameter of 12 cm with 10 rolling elements. Each rolling element has a diameter of 0.5 cm. The outer race remains stationary as the inner race is driven at 25 Hz. The contact angle of the ball is 0 degrees. The dataset bearingData.mat contains power spectral density (PSD) and its respective frequency data for the bearing vibration signal in a table.

First, construct the bearing frequency bands including the first 3 sidebands using the physical characteristics of the ball bearing.

FR = 25;
NB = 10;
DB = 0.5;
DP = 12;
beta = 0;
FB = bearingFaultBands(FR,NB,DB,DP,beta,'Sidebands',1:3)
FB = 14×2

  118.5417  121.0417
   53.9583   56.4583
   78.9583   81.4583
  103.9583  106.4583
  153.9583  156.4583
  178.9583  181.4583
  203.9583  206.4583
  262.2917  264.7917
  274.2708  276.7708
  286.2500  288.7500
      ⋮

FB is a 14x2 array which includes the primary frequencies and their sidebands.

Load the PSD data. bearingData.mat contains a table X where PSD is contained in the first column and the frequency grid is in the second column, as cell arrays respectively.

load('bearingData.mat','X')
X
X=1×2 table
          Var1                Var2      
    ________________    ________________

    {12001x1 double}    {12001x1 double}

Compute the spectral metrics using the PSD data in table X and the frequency bands in FB.

spectralMetrics = faultBandMetrics(X,FB)
spectralMetrics=1×43 table
    PeakAmplitude1    PeakFrequency1    BandPower1    PeakAmplitude2    PeakFrequency2    BandPower2    PeakAmplitude3    PeakFrequency3    BandPower3    PeakAmplitude4    PeakFrequency4    BandPower4    PeakAmplitude5    PeakFrequency5    BandPower5    PeakAmplitude6    PeakFrequency6    BandPower6    PeakAmplitude7    PeakFrequency7    BandPower7    PeakAmplitude8    PeakFrequency8    BandPower8    PeakAmplitude9    PeakFrequency9    BandPower9    PeakAmplitude10    PeakFrequency10    BandPower10    PeakAmplitude11    PeakFrequency11    BandPower11    PeakAmplitude12    PeakFrequency12    BandPower12    PeakAmplitude13    PeakFrequency13    BandPower13    PeakAmplitude14    PeakFrequency14    BandPower14    TotalBandPower
    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    ______________    ______________    __________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    _______________    _______________    ___________    ______________

         121               121            314.43          56.438            56.438          144.95          81.438            81.438          210.57          106.44            106.44          276.2           156.44            156.44          407.45          181.44            181.44          473.07          206.44            206.44          538.7           264.75            264.75          691.77          276.75            276.75          723.27          288.69             288.69           754.61           312.69             312.69           817.61           324.62             324.62           848.94           336.62             336.62           880.44           13.188             13.188           31.418           7113.4    

spectralMetrics is a 1x43 table with peak amplitude, peak frequency and band power calculated for each frequency range in FB. The last column in spectralMetrics is the total band power, computed across all 14 frequencies in FB.

Consider psdData.zip, a collection of 4 data sets where each file contains separate tables for the tachometer, vibration, and power spectrum data of a bearing. It also contains the read file for the ensemble hReadData.m.

Each dataset contains a table spectrum with 4 columns, where the first column F contains the frequency grid data, and the other three columns named Pxx, Pyy and Pzz contain spectral data.

Extract the compressed files, read the data in the table, and create a fileEnsembleDatastore object using the table data. For more information on creating a file ensemble datastore, see fileEnsembleDatastore.

unzip psdData.zip;
ens = fileEnsembleDatastore(pwd,'.mat');
% Make sure that the function for reading data is on path
addpath(fullfile(matlabroot,'examples','predmaint','main')) 
ens.ReadFcn = @hReadData;
ens.DataVariables = {'tach','vibration','spectrum'};
ens.SelectedVariables = ens.DataVariables;

Assuming fault bands FB, compute the spectral metrics. Specify the spectral column, data variable and frequency columns to be used.

FB = [10,20;40,50;60,70]
FB = 3×2

    10    20
    40    50
    60    70

[spectralMetrics,info] = faultBandMetrics(ens,FB, ...
    'SpectrumColumn','Pxx', ...
    'FrequencyColumn','F', ...
    'DataVariable','spectrum');
size(spectralMetrics)
ans = 1×2

     4    10

The output table spectralMetrics contains 4 rows of metrics where each row corresponds to one data set.

info
info = struct with fields:
       DataVariable: 'spectrum'
    FrequencyColumn: 'F'
     SpectrumColumn: 'Pxx'

The structure info contains information about the data variable, frequency column and spectrum column used to compute the metrics.

rmpath(fullfile(matlabroot,'examples','predmaint','main')) % Reset path

Input Arguments

collapse all

Power spectral density (PSD) data, specified as a vector or array. When psd is

  • A vector, then faultBandMetrics converts it to a column vector and treats psd as a single channel.

  • An array, then specify the PSD data column to be used with the 'SpectrumColumn' name-value pair.faultBandMetrics computes spectral metrics only for the PSD data column you specify.

For more information on computing PSD, see pspectrum.

Frequency grid data corresponding to psd, specified as a vector. For more information on computing spectrum frequencies, see pspectrum.

Fault frequency bands, specified as an Nx2 array, where N is the number of fault frequencies. The frequency bands specified in FB must be contained within the range of the frequency grid freqGrid. Also, the frequency units of the values in FB and the vector freqGrid must be the same.

PSD and frequency grid dataset, specified as a cell array of matrices or tables, where each cell contains the PSD data corresponding to one experiment. faultBandMetrics assumes that the last column of data in each cell contains the frequency grid while the first column contains PSD data. If the data is not in the same order, then use the 'SpectrumColumn' and 'FrequencyColumn' name-value pair arguments to specify the column numbers or names of the PSD data and the frequency grid, respectively.

PSD and frequency grid dataset, specified as a timetable, table of tables/timetables or a fileEnsembleDatastore object where each member variable contains the PSD data corresponding to one experiment. faultBandMetrics assumes that the last column of data in the member variable of T contains the frequency grid while the first column contains PSD data. If T is not in the same order, then use the 'SpectrumColumn' and 'FrequencyColumn' name-value pair arguments to specify the column numbers or names of the PSD data and the frequency grid, respectively.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: ...,'SpectrumColumn','Var1'

PSD data column to be used, specified as the comma-separated pair consisting of 'SpectrumColumn' and an integer or a string. faultBandMetrics uses the first column of data by default. If the PSD data is not the first column of your cell array X or dataset T, use 'SpectrumColumn' to specify the column numbers or names of the PSD data column.

When you specify 'DataVariable', you must specify 'SpectrumColumn' as a column of data in it.

When your dataset is in a cell array of matrices, you can use the values 'Var1,'Var2',... to refer to the spectrum data columns.

Frequency grid data column to be used, specified as the comma-separated pair consisting of 'FrequencyColumn' and an integer or string. faultBandMetrics uses the last column of data by default. If the frequency grid data is not the last column of your cell array X or dataset T, use 'FrequencyColumn' to specify the column numbers or names of the frequency grid data column.

When your dataset is in a cell array of matrices, you can use the values ’Var1’,’Var2’,... to refer to the spectrum data columns.

Data variable containing PSD and frequency grid data, specified as the comma-separated pair consisting of 'DataVariable' and a string. Use 'DataVariable' to specify the data variable containing both PSD and frequency grid data when the input dataset is a cell array of tables, a table of tables, tables/timetables of matrices, or a fileEnsembleDatastore object. 'DataVariable' must be valid table variable name.

Output Arguments

collapse all

Spectral metrics, returned as an n-by-m table, where

  • n is the number of rows when dataset is a cell array X, or the number of members (rows) when the data is in a table or an ensemble T

  • m = 3*size(FB,1)+1, that is three metrics per frequency range in FB and the total band power over the frequency range.

faultBandMetrics returns the following spectral metrics for each frequency range in FB:

  • Peak Amplitude — Peak amplitude value for each frequency range in FB.

  • Peak Frequency — Peak frequency value for each frequency range in FB.

  • Band Power — Average power of each frequency range in FB. For more information on band power, see bandpower.

  • Total Band Power — Sum of individual band powers for the set of frequency ranges in FB.

Data assignment information, returned as a structure with the following fields:

  • DataVariable — Data variable being used from X or T

  • FrequencyColumn — Frequency grid data column name

  • SpectrumColumn — PSD data column name

Introduced in R2019b