# faultBandMetrics

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

Since R2019b

## Syntax

``spectralMetrics = faultBandMetrics(psd,freqGrid,FB)``
``spectralMetrics = faultBandMetrics(X,FB)``
``spectralMetrics = faultBandMetrics(T,FB)``
``spectralMetrics = faultBandMetrics(___,Name,Value)``
``[spectralMetrics,info] = faultBandMetrics(___)``

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

```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 ⋮ ```

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

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'); 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

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 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'`

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 a column-based variable name such as `'Var1'` or `'Var2'` to specify the spectrum data column. The software interprets `'Var`n`'` as the nth column of each matrix in the cell array.

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 a column-based variable name such as `'Var1'` or `'Var2'` to specify the frequency data column. The software interprets `'Var`n`'` as the nth column of each matrix in the cell array.

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

## Version History

Introduced in R2019b