Quickstart

This guide processes one experiment from a raw free-induction decay to a fitted line list, first in a single command and then stage by stage. It uses the example experiment included with the package.

Example data

examples/blackchirp_data/2638/ is a real Blackchirp experiment provided for testing and exploration: a 15 µs FID of 750,000 points, probe frequency 40.96 GHz, lower sideband. Its active spectral band is 26500–40000 MHz, so the canonical Fourier transform is trimmed to that range. The transform itself is unapodized and native-length.

The commands below write a new exp_2638.ftmw file in the current directory.

Running the whole pipeline

The run command drives a raw source through every stage in order — import, Fourier transform, noise, decay-time calibration, peak detection, window assignment, fitting, timebase calibration, and review — with live per-stage progress. The active-band trim is required:

ftmwpipeline run examples/blackchirp_data/2638/ \
    --trim 26500:40000 \
    --output exp_2638.ftmw

Add --report to also emit the line-list table and an HTML report.

The same end-to-end build from Python, through the class API:

from ftmwpipeline import Pipeline

result = Pipeline.build(
    "examples/blackchirp_data/2638/",
    trim=(26500, 40000),
    output="exp_2638.ftmw",
)
pipe = Pipeline.open(result["pipeline_file"])

or through the functional API:

import ftmwpipeline.api as ftmw

ftmw.run_pipeline(
    "examples/blackchirp_data/2638/",
    "exp_2638.ftmw",
    trim=(26500, 40000),
)

Timebase calibration and start detection run by default; timebase calibration is non-fatal and is skipped with a warning when no instrument clock declaration is available. The build stops at the first stage that fails.

Running the stages individually

Driving the stages one at a time gives control over each step’s parameters and lets you inspect the intermediate results. The three interfaces are interchangeable; the same sequence is shown in each.

At the command line, every stage runs with <stage> run:

ftmwpipeline data import  exp_2638.ftmw examples/blackchirp_data/2638/
ftmwpipeline ft run       exp_2638.ftmw --trim 26500:40000
ftmwpipeline noise run    exp_2638.ftmw
ftmwpipeline tau run      exp_2638.ftmw
ftmwpipeline peaks run    exp_2638.ftmw
ftmwpipeline windows run  exp_2638.ftmw
ftmwpipeline fit run      exp_2638.ftmw

With the Pipeline class, an instance is bound to one file:

from ftmwpipeline import Pipeline

pipe = Pipeline.create("exp_2638.ftmw", source="examples/blackchirp_data/2638/")
pipe.compute_ft(trim=(26500, 40000))
pipe.estimate_noise()
pipe.calibrate_tau()
pipe.detect_peaks()
pipe.assign_windows()
pipe.fit_peaks()

With the functional API, each call takes the file path:

import ftmwpipeline.api as ftmw

ftmw.import_data("exp_2638.ftmw", source="examples/blackchirp_data/2638/")
ftmw.compute_ft("exp_2638.ftmw", trim=(26500, 40000))
ftmw.estimate_noise("exp_2638.ftmw")
ftmw.calibrate_tau("exp_2638.ftmw")
ftmw.detect_peaks("exp_2638.ftmw")
ftmw.assign_windows("exp_2638.ftmw")
ftmw.fit_peaks("exp_2638.ftmw")

Each stage requires its predecessor to be complete and fails with a message naming the missing dependency otherwise. Re-running a stage with new parameters is safe; re-running an earlier stage invalidates the results that depended on it.

Inspecting the result

Check provenance and which stages have run:

ftmwpipeline info exp_2638.ftmw

Visualize a stage’s output with <stage> show — for example the fitted model:

ftmwpipeline fit show exp_2638.ftmw

The equivalent introspection from Python:

pipe = Pipeline.open("exp_2638.ftmw")
print(pipe.info())

Producing a report

review run consolidates the finalized line list; report run then writes it alongside an HTML report:

ftmwpipeline review run exp_2638.ftmw
ftmwpipeline report run exp_2638.ftmw

Where to go next