Case study: building an analyzer

What the finished tool does

Drop in a CSV or Excel file of acceleration data, or pick a demo signal. The app computes the spectrum, envelope spectrum (with an automatic kurtogram band), spectrogram and cepstrum, estimates running speed, finds harmonic families and sidebands, applies fault rules for unbalance, misalignment, looseness, bearings, gears, blade pass, belts and electrical faults, checks data quality and exports a Word report. Everything runs in the browser; no data leaves the computer.

The build, step by step

1. Write the specification first

   One page: input formats (time column or sampling rate, g or m/s² or mm/s, comma or semicolon, decimal commas), the analyses, the fault list, the outputs, and the rule that it must run offline in one file. The specification also set the structure: a pure calculation engine with no user interface, so it can be tested on its own.

   Build the analysis engine as pure JavaScript functions with no DOM access:
   FFT, windows with amplitude correction, Welch averaged spectrum, peak picking
   with noise-floor estimate, envelope via Hilbert transform, kurtogram, cepstrum, STFT.
   Report amplitudes as peak values and say so in every function's comment.

2. Build a ground-truth generator before the user interface

   The most important step. A demo module creates synthetic signals whose faults are known exactly: an outer-race defect at 3.585 × running speed exciting a 4.2 kHz resonance, an inner-race defect modulated at 1×, a 23-tooth gear with eccentricity sidebands, looseness with sub-harmonics, misalignment, a clipped sensor and pure noise. The engine was then checked against each one.

   Write synthetic signals with known ground truth for each fault in the spec.
   Return the signal and a "truth" object (speed, defect frequency, resonance).
   Then run the engine on each one and print a table: expected vs detected
   frequency, and whether the right finding appears. Fix the engine until all pass.

3. Add diagnostics as transparent rules with evidence

   Each finding carries a title, a summary, the evidence (which peaks, which ratios) and recommended checks. Scores are labelled as a heuristic evidence index, explicitly not a probability. That wording came from a review step, not from the first draft.

4. Then the interface

   Tabs for diagnosis, waveform, spectrum, envelope, spectrogram, cepstrum and report; charts with zoom, harmonic and sideband cursors; a findings list that highlights its evidence on the charts. Because the engine was already verified, interface bugs could not hide calculation bugs.

5. Make loading survive real files

   Real exports have header blocks, units in column names, semicolons, decimal commas, irregular time stamps and Excel sheets. Each problem became a precise follow-up prompt with a sample file, and irregular timing triggers resampling with a visible warning.

6. Data quality before diagnosis

   Clipping, large DC offset, isolated spikes, energy near the Nyquist frequency, a "ski slope" at low frequency and too few shaft revolutions are checked and reported. A clipped signal switches the verdict to "measurement unreliable" instead of reporting harmonics that the clipping created.

7. Reports and limitations

   The Word report states the methods, the assumptions and the limitations of single-channel analysis in plain language, because someone will read it without the app open.

Verification that made it trustworthy

The same approach was used for the Motor Current Analyzer: nine sample fault cases (broken rotor bars, eccentricity, misalignment, bearings, stator shorts, load oscillation, supply distortion, multiple faults) each carry a written "expected" result, so anyone can see whether the tool agrees.

Lessons for your own build

• Engine first, interface second. Verify calculations without the distraction of a user interface.
• Ground truth is the specification you can run. Synthetic signals with known faults are the cheapest tests you will ever write, and the agent can write them for you.
• Make the tool explain itself. Evidence and limitations in the output are what make a reviewer, or an auditor, accept it.
• Small, precise follow-ups. One problem per message, with the input, the expected value and the actual value.