matlab-extract-rotating-machinery-features

# Rotating Machinery Feature Extraction

Extract predictive features from rotating machinery data for condition monitoring and fault detection applications. This skill covers the essential feature extraction workflow steps and algorithms specialized to rotating machinery.

## When to Use

- User has uniformly-sampled time series data representing rotating machinery sensor measurements stored as matrix, `timetable`, or cell array variables.
- User is building a condition monitoring or fault detection system for rotating machinery.
- User wants to process rotating machinery data for feature extraction.
- User wants to select most predictive features and construct a health indicator from features.
- User is deploying condition monitoring and fault detection systems.
- User has high-frequency vibration data and wants feature-based data reduction for efficient condition monitoring.

## When NOT to Use

- User has non-time-series data such as images, videos, or tabular (unordered) data.
- User wants fault classification (as opposed to fault detection) with two or more fault classes. Use `classificationLearner` instead.
- User has time series data (labeled or unlabeled) and wants to build anomaly detection models. Use `timeSeriesAnomalyDetector` instead.
- User has very low-frequency data not suitable for statistical or spectral feature extraction.

## Feature Extraction Workflow

Follow these 5 steps interactively:

```
Task Progress:
- [ ] Step 1: Process data for feature extraction
- [ ] Step 2: Extract features from data
- [ ] Step 3: Rank and select features
- [ ] Step 4: Develop a health indicator using selected features
- [ ] Step 5: Deploy the application
```

Do NOT silently choose parameters or make assumptions. Engage the user at each decision point. In particular, ask the user to provide important system parameters such as
- Bearing and gear geometry parameters
- Rotation speeds (RPMs)
- Structural resonance frequencies, if known

## Step 1: Process data for feature extraction

1. Non-periodic signal components or noise can be removed from measurements if accompanying tachometer or RPM data is available. Use time-synchronous averaging (`tsa`) and related techniques (`tsadifference`, `tsaresidual`, etc.) to isolate periodic signal components. If tachometer signal is available, use `tachorpm` to estimate the RPM before `tsa` processing.
2. For modulated time series signals, use the signal envelope (`envelope`) or the envelope spectrum (`envspectrum`) to demodulate the signals.

### Establishing rotation speeds and fault frequencies (do this before placing any fault bands)

A tachometer or RPM channel gives the speed of **one specific shaft** — you must know **which physical shaft it is mounted on** and how many **pulses per revolution** it produces. Do not assume it is the motor/input shaft.

- Ask the user (or infer from the setup) where the tachometer is mounted and its pulses-per-revolution. In a geared drivetrain, propagate speeds through the gear ratios from the *known* shaft: multiply toward faster shafts, divide toward slower ones.
- **Always sanity-check the derived speeds against the measured spectrum.** Compute a power spectrum (`pspectrum`) and confirm a dominant line appears at the expected shaft rate or gear-mesh frequency. If the strongest peak is at a very different frequency (e.g. you assumed a 3 Hz shaft but the spectrum peaks at 90 Hz), your tach-placement assumption is wrong — revisit it before continuing.
- **CRITICAL — Never attempt `tsa` without real rotation-phase information.** If the user asks for time-synchronous averaging but no tachometer signal, RPM profile, or order-tracking data is available: **you MUST refuse the TSA request.** Tell the user: "TSA requires rotation-phase information (tachometer pulses or an RPM profile) that is not present in your data. I cannot proceed with time-synchronous averaging." Then offer alternative noise-reduction approaches that do NOT require rotation phase — such as bandpass filtering, spectral averaging (`pwelch`), or statistical features on the raw signal. **Do not work around the missing data** — do not estimate an RPM from the spectrum, do not guess a shaft speed from a dominant spectral peak, do not fabricate tachometer pulses, and do not modify or re-generate data files to inject rotation-phase information that the user said they do not have.

For bearings, characteristic fault frequencies (`Fo`, `Fi`, `Fb`, `Fc`) come from the bearing **geometry plus shaft speed** via `bearingFaultBands`. If the user supplies these frequencies directly (common in datasets), use them as given — do not invent geometry to re-derive them. If only shaft/gear information is given and the bearing geometry is unknown, ask for the geometry (number of rolling elements, ball/pitch diameter, contact angle) rather than guessing a fault-frequency-to-shaft ratio; alternatively identify the dominant non-shaft peak in the envelope spectrum empirically and label it explicitly as an empirical estimate.

## Step 2: Extract features from data

1. Extract time-domain features such as `rms`, `kurtosis`, `peak2rms`, and other statistical metrics.
2. Extract spectral features such as `bandpower` and spectral peaks & frequencies from demodulated signals.
3. For special components such as bearings and gears, extract domain-specific features such as `bearingFaultBands`, `gearMeshFaultBands`, or `gearConditionMetrics`. Use `faultBands` to build characteristic fault-frequency bands (fundamental + harmonics + sidebands) for shafts and generic components, and compute spectral metrics over those bands with `faultBandMetrics` (peak amplitude, peak frequency, and band power per band).
4. Suggest the use of `diagnosticFeatureDesigner` if an interactive tool is desired to extract a large number of features.

### Extracting features across many files (batch processing)

Condition-monitoring and run-to-failure datasets usually span **many measurement files** (one per da