ftmwpipeline Documentation
ftmwpipeline processes Fourier transform microwave (FTMW) spectroscopy
data, from a raw free-induction decay to a calibrated table of fitted spectral
lines. Each experiment is one self-contained, portable .ftmw file that
progresses through a sequence of stages — import, Fourier transform, noise
estimation, decay-time calibration, peak detection, window assignment, peak
fitting, and review — with every stage’s result and its provenance recorded in
the file.
The pipeline is built for spectroscopists who need to know not only how to run an analysis but what each stage does and why its results can be trusted. The stage pages describe the algorithms, the assumptions behind them, and the statistical basis for the reported peak parameters and uncertainties.
Where to start
Overview — the purpose and design philosophy, the
.ftmwfile model, the three user-facing interfaces, and the stage pipeline at a glance.Installation — install the package and its dependencies.
Quickstart — process an experiment end to end.
Settings and presets — how stage parameters are resolved across keyword arguments, presets, and the values persisted in the file.
Input Formats — bring data from any instrument into the pipeline: the native HDF5 and CSV input formats, the metadata sidecar, and declaring instrument clock sources.
The pipeline stages, in the order an experiment moves through them:
Stage 0: Data Import — load a raw FID from an instrument format.
Stage 1: Fourier Transform — compute the canonical frequency-domain spectrum.
Stage 2: Noise Estimation — estimate the per-bin noise.
Stage 2b: Decay-Time Calibration — calibrate the molecular decay time and recommend a line shape.
Stage 3: Peak Detection — detect peaks.
Stage 4: Window Assignment — assign disjoint analysis windows.
Stage 5: Peak Fitting — fit the peaks in each window.
Stage 6: Review, Reports, and Finalization — review, report, and finalize the line list.
Methods and validation notes go deeper on why specific algorithmic choices can be trusted, with figures and numbers regenerated from the example data:
Noise estimation at high signal-to-noise — why naive noise estimation fails on high signal-to-noise, line-dense spectra, and how the scatter estimator is validated.
Matched filter as a peak detector — why the weak-line gap pass detects with an exponentially-apodized transform, derived and validated on synthetic ground truth and the example experiment.
Complex-edge coherence statistic — the phase-coherent edge test behind window assignment: its closed-form null, threshold calibration, and the active-FT frame it must be scored in.
Stage 5 fitting: gates, blends, and SNR-aware acceptance — the peak-fitting acceptance gate: why it is window-size invariant, how it handles blends, and the SNR-aware health check validated across the example experiments.
Timebase self-calibration — measuring the digitizer scale error from the clock spurs’ phase, its Cramér–Rao precision bound, and how the frequency correction reaches the line list.