Quick Start

A 5-minute introduction to the main ways you can use XPCS Viewer: the GUI, the CLI, and the Python API.

What you’ll learn

  • Launch the graphical interface and navigate the main window

  • Run command-line batch processing

  • Load an XPCS dataset with the Python API

  • Extract G2 and SAXS data from a file

Launch the GUI

XPCS Viewer includes a PySide6 GUI for interactive exploration. Launch it from the terminal:

# Launch GUI in current directory
xpcsviewer-gui

# Launch GUI with data path
xpcsviewer-gui /path/to/hdf/data

# With debug logging
xpcsviewer-gui --log-level DEBUG

The GUI opens a main window with a source file list on the left and analysis tabs on the right. The typical workflow is:

  1. Select files from the Source list (left panel)

  2. Add to Target with Ctrl+Shift+A or drag-and-drop

  3. Choose an analysis tab (SAXS 2D, G2, Twotime, etc.)

  4. Results display in the interactive plot area

CLI Batch Processing

For scripted or automated pipelines, use the xpcsviewer command:

# Show available commands
xpcsviewer --help

# Generate twotime plots for all phi angles at q=0.05
xpcsviewer twotime --input /data --output /results --q 0.05

# Generate high-resolution PDF plots
xpcsviewer twotime -i /data -o /results --phi 45 --dpi 300 --format pdf

Load Data with the Python API

The XpcsFile class is the main entry point for programmatic access. It reads HDF5 files produced by XPCS correlators:

from xpcsviewer import XpcsFile

# Load XPCS dataset
xf = XpcsFile("data.hdf")
print(f"Analysis type: {xf.atype}")

Extract G2 and SAXS Data

from xpcsviewer.module import g2mod

# Get G2 data from multiple files
xf_list = [XpcsFile(f) for f in ["file1.h5", "file2.h5"]]
q, tel, g2, g2_err, labels = g2mod.get_data(xf_list)

from xpcsviewer import XpcsFile

xf = XpcsFile("data.h5")

# 1D SAXS (returns q, Iq, xlabel, ylabel)
q, Iq, xlabel, ylabel = xf.get_saxs1d_data()

# Or access the raw dictionary
q_values = xf.saxs_1d["q"]
intensities = xf.saxs_1d["Iq"]

# 2D SAXS
saxs_2d = xf.saxs_2d

Key Shortcuts

  • Ctrl+O: Open folder

  • Ctrl+R: Reload data

  • Ctrl+P: Command Palette

  • Ctrl+Shift+A: Add to target

  • Ctrl+L: View logs

Next Steps