faultBandMetrics

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

Syntax

spectralMetrics = faultBandMetrics(psd,freqGrid,FB)

spectralMetrics = faultBandMetrics(X,FB)

spectralMetrics = faultBandMetrics(T,FB)

spectralMetrics = faultBandMetrics(___,Name,Value)

[spectralMetrics,info] = faultBandMetrics(___)

Description

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.

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.

spectralMetrics = faultBandMetrics(T,FB) returns a set of spectral metrics spectralMetrics for the PSD and frequency grid data specified in the data set 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 data set T.

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

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

Examples

Frequency Bands and Spectral Metrics of Gear Train

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 data set 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.

Ni = 8;
No = 42;
FR = 20;
FB = gearMeshFaultBands(FR,Ni,No,'Sidebands',1:3)

FB = 15×2

   19.0000   21.0000
    2.8095    4.8095
   79.0000   81.0000
   99.0000  101.0000
  119.0000  121.0000
  139.0000  141.0000
  179.0000  181.0000
  199.0000  201.0000
  219.0000  221.0000
  147.5714  149.5714
  151.3810  153.3810
  155.1905  157.1905
  162.8095  164.8095
  166.6190  168.6190
  170.4286  172.4286
      ⋮

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.0054125             19          0.0051216        0.55167             4.25          0.41848        0.0022699             81          0.0029792       0.0012756           99.438        0.0019134       0.0023457           119.25        0.0032812       0.0030216           139.75        0.0036398       0.0015424           180.06        0.0021249       0.0023163           200.81        0.0029269        0.013511            221           0.012079        0.0037697           148.06          0.003914         0.0020528           151.56          0.0025637        0.0021721            156.5          0.0022927        0.0020822           162.81          0.0015729        0.0015305           168.25          0.001575         0.0010234           170.44          0.0013135        0.46577    

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.

Frequency Bands and Spectral Metrics of Ball Bearing

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 data set 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
  310.2083  312.7083
  322.1875  324.6875
  334.1667  336.6667
   10.7292   13.2292
      ⋮

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      
    ________________    ________________

    {12001×1 double}    {12001×1 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.

Compute Fault Band Metrics from Ensemble Datastore

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 data set 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');
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:
     SpectrumColumn: 'Pxx'
    FrequencyColumn: 'F'
       DataVariable: 'spectrum'

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

Input Arguments

psd — Power spectral density data

vector | array

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.

freqGrid — Frequency grid data

vector

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

FB — Fault frequency bands

Nx2 array

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.

X — PSD and frequency grid data set

cell array of matrices | cell array of tables

PSD and frequency grid data set, 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.

T — PSD and frequency grid data set

timetable | table of tables/timetables | fileEnsembleDatastore object

PSD and frequency grid data set, 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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

SpectrumColumn — PSD data column to be used

first column of data set (default) | integer | string

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 data set 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 data set is in a cell array of matrices, you can use a column-based variable name such as 'Var1' or 'Var2' to specify the spectrum data column. The software interprets 'Varn' as the nth column of each matrix in the cell array.

FrequencyColumn — Frequency grid data column to be used

last column of data set (default) | integer | string

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 data set T, use 'FrequencyColumn' to specify the column numbers or names of the frequency grid data column.

When your data set is in a cell array of matrices, you can use a column-based variable name such as 'Var1' or 'Var2' to specify the frequency data column. The software interprets 'Varn' as the nth column of each matrix in the cell array.

DataVariable — Data variable containing PSD and frequency grid data

'Var1' (default) | string

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 data set 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

spectralMetrics — Spectral metrics

table

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

• n is the number of rows when data set 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.

info — Data assignment information

structure

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

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Data stored in fileEnsembleDatastore and workspaceEnsemble objects, as well as data in the form of a tall array are not supported.

Version History

Introduced in R2019b