This page is a mental model of how guisaxs-liveview behaves — for someone who already understands SAXS (frames → I(q) → subtraction → Guinier / GNOM / …) and wants to know how the app organizes that work. It is not a click-by-click manual; recipes live on the Main window and wizard pages. Scientific procedures: Algorithms.
The working directory (path under the menu bar; tooltip shows the full path) is the folder
the app watches and, in the usual flat layout, where pipeline outputs are written. Session settings
(watch mode, calibration, buffer / subtraction options) are remembered under that folder in
.guisaxs_liveview/session.yaml.
File → Open working directory… switches folders: the current session is saved, the app restarts on the new directory, and any saved session there is reloaded. You cannot switch while a skill is still running.
The right column Intake toggles choose where new samples board the pipeline:
.tif / .tiff); full path integrate → optional subtract → analysis..dat under averaged/); skip integrate; optional subtract → analysis.
Until a buffer is set the middle column shows a single 1D canvas; with buffer configured it shows the
integrated curve plus S + buffer / Sub below. Proxy curves (averaged_proxy/ or
type: integrated_proxy_1d) are rejected..dat under subtracted/); analysis only; a single Sub canvas.The active mode is persisted in session.yaml. Mixed sessions are allowed: history is keyed by
exact path; Process re-runs from that entry’s boarding rung (not the current toggle).
Watchers only accept the current mode’s inputs and never change the toggle. A drop may
auto-switch: .dat while in 2D → switch to 1D or Sub from classification; .tif while in
1D/Sub → switch to 2D. If you are already in 1D or Sub and drop a .dat, the manual toggle
wins (no 1D↔Sub auto-switch). Pipeline products written by the app are not treated as new intake.
Files that appear after the app has started (or are dropped) are queued. Typical paths:
averaged/ or
subtracted/ according to boarding), then queued.averaged/; Sub: subtracted/).Files already sitting in the folder at launch (or when switching intake) are not auto-queued. To process them, drop them again, overwrite them, or use history Process after they have been seen once in this session.
Curve classification (for auto-switch out of 2D): prefer autosaxs metadata (autoSAXS: true and
type: int / type: sub); otherwise basename prefix sub → Sub, else → 1D.
Under File → Advanced… you choose how TIFF discovery and TIFF outputs are organized (only when the queue is idle):
averaged/, subtracted/, analysis folders, …) live under
that same root. Suits a single beamline hot folder.Curve drops always land under <watchdir>/averaged/ or <watchdir>/subtracted/
regardless of flat/tree TIFF mode.
Everything the app does to a sample (integrate, subtract, analysis steps) goes through a single sequential queue. The middle status line shows:
Jobs for different files are handled one after another (FIFO). If the same path is revised while still queued, the queue updates that slot instead of stacking duplicate work.
Think of a per-file pipeline whose length depends on boarding and what you have configured:
averaged_proxy/). After Calibrate, you get calibrated
I(q) under averaged/.subtracted/, and the middle column shows S + buffer /
Sub instead of a single 1D plot. Sub boarding skips this step.Calibration and buffer are session setup for 2D (and buffer for 1D); left-column controls that are unused in the current intake are hidden.
By default the app is in auto mode: when a sample reaches the front of the queue, the current pipeline runs without further clicks.
Arming analysis. Opening the monodisperse or polydisperse window from the right-column icons arms that analysis chain for new files while the window stays open. Closing the window disarms it. With neither open, only integrate (+ subtract if configured) runs. Both windows may be open; each keeps its own chain and output tree (Monodisperse / Polydisperse). Guinier and GNOM (p(r) / D(R)) run in the liveview queue; shape / MIXTURE modeling runs in a separate app opened via Start modeling, then Confirm there.
Pausing auto analysis. On an analysis window, Stop auto-processing / Resume auto-processing suspend or restore automatic analysis (you can still run manual / wizard actions). App-wide shortcuts: Ctrl+X Auto→Manual, Ctrl+P Manual→Auto. Editing / confirming a Guinier, P(r), or D(R) Adjust wizard, or applying a new subtraction scale, also moves you into Manual until you resume.
Manual re-run of a file. History Process re-enqueues the selected sample through the same live pipeline from its boarding rung — useful after changing calibration, buffer, or analysis settings. If you are in Manual, clicking Process also resumes Auto so the re-queued sample can run. (Ctrl+P only resumes Auto; it does not trigger Process.)
Settings → Appearance… sets the shared UI font size (Small / Medium / Large presets plus a slider and point-size spin box, with live preview). Apply / OK persist it; Cancel restores the last applied size.
After at least one sample finishes in this run, the middle column shows < / > and
Process. Stepping history reloads that file’s plots from disk for review; it does not
re-run skills by itself (missing artifacts leave plots empty). While you are looking at an older entry,
the live “tail” of new files does not force the view forward until you step to the latest again.
History keys are exact paths (TIFF or .dat).
Beamlines often overwrite sample.tif in place (and the same idea applies to watched
.dat files). Liveview treats a replaced (or overwrite-detected) path as a revision:
queued work for it is superseded, and the pipeline runs again on the new bytes. In flat 2D mode a poll
watcher also helps catch NFS-style overwrites of existing names. Process on history is the
explicit version of the same idea. After a successful re-run, that path is treated as the latest
session entry.
Under the output root (working directory in flat mode; next to the TIFF in tree mode):
runs/latest/ — last skill request/result logs (request.yml,
result.yml, stdout.log, stderr.log)calibration/ — integrator and refined geometryaveraged_proxy/, averaged/ — 1D curves before / after calibrationsubtracted/ — buffer-subtracted curvesguinier_mono/, guinier_poly/, fit_distances/,
fit_sizes/, model_bodies/, dammif/, denss/,
mixture/ — analysis products when those chains are armed (often per-TIFF subfolders)Shared wizard configs (for example fit_distances.conf) sit next to per-stem folders.
Calibration / buffer source files keep their original paths; they are not copied into the working dir
unless you drop them there yourself.
The right column Logs panel has two tabs: Full (skill stdout/stderr plus app messages) and App (arming, queue notices, and other application-level lines). Use App when you want a quieter trail of what the GUI decided; use Full when a skill fails and you need the underlying tool output.
A blue pulsing border on a control is not a separate mode — it is a soft hint for the next likely setup action (for example Calibrate, then later Set buffer, an empty drop target, analysis icons, or Resume auto-processing when auto analysis is paused). Unused left-column groups are hidden in 1D/Sub intake so coaching skips them. You can ignore the pulse and use the menus and buttons directly.