Headless Replay
flits replay re-runs a saved session snapshot without a browser. It reopens
the burst the snapshot names, restores every selection it records — DM, crop,
event window, off-pulse regions, channel mask, spectral extent, calibration
inputs — recomputes the measurements, and can write the same export bundle the
interface produces.
Replay makes supported calculations checkable using the snapshot, original
data, and a compatible software environment. It reports unknown or changed
software provenance before recomputing. The --json report includes these
warnings and the origins of both recomputed and retained results. A software
change can alter a calculation; file readability alone does not guarantee
identical numbers. See software versions and file longevity.
Reproduce an analysis
snapshot gbt_burst_flits_session.json
burst /data/GBT-L/blc_s_guppi_60385_53711_FRB20240114A.fil
dm 527.650000
recomputed width_analysis, results
width_ms 1.8342
fluence_jyms 0.7421
snr 18.63
If the burst has moved since the snapshot was saved, point FLITS at its new home:
Snapshot resolution prefers a copy inside the data directory whose size and SHA-256 match the one recorded at save time, so moving or renaming the file is usually handled without any flag at all. The same data-directory containment that applies to the server applies here.
Verify that the numbers still reproduce
--check recomputes the measurements and compares them against the values
stored in the snapshot, field by field. It exits non-zero if anything differs,
which makes it usable in CI or in a pre-submission check over a burst catalogue.
--check compares numerical fields in the core measurement result; it does
not compare text labels, validate scientific assumptions, or independently
check the stored DM sweep and other retained diagnostics.
Use --tolerance to set the relative tolerance (default 1e-9). A difference
means either the data changed, the environment changed, or a FLITS version
changed a result — all three are worth knowing about before a paper goes out.
# Check a whole directory of snapshots and report the first failure.
for snapshot in sessions/*_flits_session.json; do
flits replay "$snapshot" --check --log-level warning || echo "DIFFERS: $snapshot"
done
Analyses the snapshot recorded
Beyond the core measurements, replay recomputes a recorded width comparison, a session-measured rotation measure, and a sub-burst drift rate. Each is recomputed from the settings the snapshot stored rather than from defaults, which is what makes the drift error bar reproduce exactly — its Monte Carlo is seeded, and the seed travels in the snapshot.
The drift result appears in the --json report under drift, with the drift
rate, its uncertainty, and the DM offset that would account for the measured
slope.
Write an export bundle
Every ready artifact is written into out/, alongside a manifest.json
describing the bundle. Restrict what is produced with --include, which accepts
the same artifact kinds as the interface (json, csv, npz, plots,
window) and can be repeated:
Machine-readable output
--json prints the whole replay report — burst path, DM, what was recomputed,
the measurements, the files written, and any differences found by --check — as
a single JSON document:
That makes it straightforward to build a table across many bursts:
for snapshot in sessions/*.json; do
flits replay "$snapshot" --json --log-level error
done | jq -s '[.[] | {burst: .burst_file, dm: .dm, fluence: .measurements.fluence_jyms}]'
Exit codes
| Code | Meaning |
|---|---|
| 0 | Replay succeeded; with --check, the measurements matched |
| 1 | --check found differences |
| 2 | The snapshot could not be read, or the burst could not be reopened |
What replay does not do
Replay restores selections and recomputes core measurements and recorded width, drift, and in-session polarization analyses. It does not re-run the DM sweep, the temporal or spectral structure analyses, or model fitting — those are expensive and parameterized, and the snapshot keeps their stored results. Run them in the interface when you need them refreshed.