Welcome · Concepts

Concepts

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.

Working directory

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.

How frames enter the app

New detector images are .tif / .tiff files that appear after the app has started. Typical paths:

• Drag-and-drop onto the middle 2D panel (Drop .tif) — files outside the working directory are copied into it, then queued.
• Copy or save TIFFs into the watch folder from the beamline software or a script.

TIFFs already sitting in the folder at launch 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.

Flat vs tree layout

Under File → Advanced… you choose how discovery and outputs are organized (only when the queue is idle):

• Flat directory (default) — watches only the top-level working directory (not nested folders); outputs (averaged/, subtracted/, analysis folders, …) live under that same root. Suits a single beamline hot folder.
• Tree directory — discovers TIFFs recursively; each TIFF’s outputs sit beside it in its own folder tree. Suits experiments already organized in nested directories.

The task queue

Everything the app does to a TIFF (integrate, subtract, analysis steps) goes through a single sequential queue. The middle status line shows:

• Idle — nothing waiting or running.
• Queue · N — work remaining (incoming files + pending / current jobs), with the current file path when busy.

Jobs for different files are handled one after another (FIFO). If the same TIFF path is revised while still queued, the queue updates that slot instead of stacking duplicate work.

What each TIFF goes through

Think of a per-file pipeline whose length depends on what you have configured:

1. Integrate — always. Before calibration succeeds, this is a coarse proxy curve (pixel-like axis, under averaged_proxy/). After Set calibration, you get calibrated I(q) under averaged/.
2. Subtract — only if you applied Set buffer for the session. Then each sample gets a buffer-subtracted curve under subtracted/, and the middle column shows S + buffer / Sub instead of a single 1D plot.
3. Analyze — only while an analysis window is open (see next section).

Calibration and buffer are session setup, not per-file wizards you repeat for every frame.

Auto processing vs manual control

By default the app is in auto mode: when a TIFF 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).

Pausing auto analysis. On an analysis window, Stop auto-processing / Resume auto-processing suspend or restore automatic TIFF analysis (you can still run manual / wizard actions). Editing Guinier / GNOM parameters or applying a new subtraction scale also moves you into a more manual posture until you resume.

Manual re-run of a file. History Process re-enqueues the selected TIFF through the same live pipeline as a new upload — useful after changing calibration, buffer, or analysis settings.

Session history

After at least one TIFF 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.

TIFF revision (same name, new content)

Beamlines often overwrite sample.tif in place. Liveview treats a replaced (or overwrite-detected) TIFF as a revision of that path: queued work for it is superseded, and the pipeline runs again on the new bytes. In flat 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.

Where results live

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 geometry
• averaged_proxy/, averaged/ — 1D curves before / after calibration
• subtracted/ — buffer-subtracted curves
• guinier_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.

Logs

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.

Pulsing next-step hints

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 Set calibration, then later Set buffer, an empty Drop .tif target, analysis icons, or Resume auto-processing when auto analysis is paused). You can ignore it and use the menus and buttons directly.

Main window (recipes) → · Algorithms → · Troubleshooting →