Data GUI

A Qt viewer for browsing ARTIQ result files and logs. It lists the HDF5 results in a directory, shows their experiment arguments, datasets and fit results, and plots them — using the embedded ndscan plot for ndscan results, and a built-in matplotlib canvas for everything else.

Installation

The only prerequisite is uv, which fetches a suitable Python interpreter (3.12 or newer) and all the Python dependencies itself:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

On Linux you also need the Qt/XCB runtime libraries that PyQt6 loads. On Ubuntu/Debian:

sudo apt install libxcb-cursor0

Running

To run the current version straight off GitHub, without a checkout:

uvx --from git+https://github.com/OxfordIonTrapGroup/Data_GUI data_gui

To run from a local checkout (which is what you want for development, as the GUI then picks up your edits):

git clone https://github.com/OxfordIonTrapGroup/Data_GUI.git
cd Data_GUI
uv run data_gui

uv run creates the virtual environment and installs the pinned dependencies from uv.lock on first use, so there is no separate setup step. Both commands also install ndscan and oitg from their Git repositories.

Results Location

The default results directory is derived from the standard group paths via oitg.paths, controlled by two environment variables:

• OITG_SHARED_AREA: the shared area mount point. Defaults to Z:\ on Windows and ~/steaneShared/ elsewhere, so on Linux/macOS this usually needs to point at wherever the share is actually mounted (for example /Volumes/steaneShared).
• OITG_EXPERIMENT: the experiment name, e.g. lab1_bob. If unset, the GUI falls back to lab1_bob.

Results are then looked up in <shared area>/artiqResults/<experiment>, and the Results root box starts on today's date folder below that, <shared area>/artiqResults/<experiment>/YYYY-MM-DD. Any directory of *.h5 files works, though; use Browse or type a path to point the GUI elsewhere.

Opening Data

1. Start the GUI as above.

2. Check Results root; it defaults to today's results folder, for example:

   Z:\artiqResults\lab1_bob\2026-08-12
   

3. Click Refresh if you changed the path.

4. Select a result file on the left.

If the selected file contains ndscan data, the center panel shows the ndscan plot automatically. If it is not an ndscan file, the GUI falls back to the built-in matplotlib plot area.

Opening Logs

The Logs tab browses dated ARTIQ log files separately from HDF5 result files. By default it opens the log directory next to the results, for example:

Z:\artiqResults\lab1_bob\log

Use Browse if the log folder is somewhere else. The loader scans the selected folder for files with a yyyy-mm-dd date in the name and a log-style filename, including names such as 2026-06-09.log, controller.2026-06-09.log, and log.2026-06-09. The active file named exactly log is also shown, using its last-modified date in the date filter.

• Latest 50: shows the 50 most recent log files across all dates.
• Date: when Latest 50 is off, shows log files for the selected date.
• Filter: searches the selected log file's displayed entries.
• Errors only: enabled by default, showing only ERROR and CRITICAL entries while retaining their multiline details and tracebacks.
• 1am-7am only: shows entries timestamped from 01:00 up to before 07:00.

Multi-line log entries are grouped under the timestamped first line, and warning or error lines are highlighted. Very large matching logs are previewed up to the first 20,000 displayed lines so the GUI stays responsive.

Plot Modes

• Show ndscan Plot: return to the embedded ndscan plot for the selected file.
• Plot Selected: plot the selected dataset(s) using the GUI's built-in matplotlib plotter.
• Plot History: plot scalar datasets across the currently visible result files.

Experiment Parameters

The upper-right panel shows experiment arguments in a table sorted by parameter name. The encoded ndscan_params argument is expanded so each ndscan parameter, override, and scan axis has its own sortable row. Use the search field to filter display names, fully qualified parameter names, or values. Default, override, and scan status appears as a short note after the value instead of occupying a separate column.

Filtering

• The default results path points directly at the current local date folder (Results root/YYYY-MM-DD) and is scanned once automatically when the GUI opens. After startup, use Refresh to scan again. If today's default network folder is unavailable, the GUI reports that status without switching to a fallback. Custom paths selected with Browse or entered manually are only scanned with Refresh.
• 1am-7am only: shows result files whose recorded start time is from 01:00 up to before 07:00 to monitor the nightly automatic calibration.
• Filter: searches visible files by RID, class name, file name, and path.
• Max: limits how many recent files are loaded.

Refresh is cached, so repeated refreshes should be much faster when files have not changed.