xpcsviewer-gui 0.1.10

UI notes

• Menu-driven header (no quick-access toolbar); all actions live under the menus/shortcuts.

• Starts maximized with a rectangular layout and a minimum-size floor to prevent cramped controls.

• PySide6 GUI interface with modern theming

• Performance optimizations

Installation

Requirements: Python 3.12+

# Install from PyPI
pip install xpcsviewer-gui

# Or install with uv (recommended)
uv pip install xpcsviewer-gui

JAX and all scientific dependencies (NumPyro, ArviZ, interpax, etc.) are included automatically — no extras needed.

# Auto-detect system CUDA version and install matching JAX
make install-jax-gpu

# 1. Check your CUDA version
nvcc --version    # Note: release 12.x or 13.x

# 2. Remove ALL existing JAX/CUDA packages (prevents plugin conflicts)
pip uninstall -y jax jaxlib \
    jax-cuda13-plugin jax-cuda13-pjrt \
    jax-cuda12-plugin jax-cuda12-pjrt

# 3. Install matching package
pip install "jax[cuda13-local]"   # For CUDA 13.x (SM >= 7.5)
pip install "jax[cuda12-local]"   # For CUDA 12.x (SM >= 5.2)

# 4. Verify
python -c "import jax; print(jax.default_backend(), jax.devices())"
# Expected: gpu [CudaDevice(id=0)]

Usage

GUI (Interactive):

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

# Launch from current directory
xpcsviewer-gui

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

# Short aliases also available: ``xv-gui`` (GUI) and ``xv`` (CLI)

CLI (Batch Processing):

# 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

Citation

Chu et al., “pyXPCSviewer: an open-source interactive tool for X-ray photon correlation spectroscopy visualization and analysis”, Journal of Synchrotron Radiation, (2022) 29, 1122–1129.

Development

# Clone and install (uv recommended)
git clone https://github.com/imewei/XPCSViewer.git
cd XPCSViewer

# With uv (recommended) — installs package + dev/test dependencies
uv sync
make install-hooks      # install pre-commit + commit-msg hooks

# Or with pip (editable install, no dev dependencies)
pip install -e .

# Run tests
make test               # parallel tests (excl. GUI)
make test-fast          # fast tests excluding slow markers

# Build docs
make docs

Data Formats

• NeXus HDF5 (APS-8IDI beamline)

• SAXS 2D/1D data

• G2 correlation functions

• Time series data

Testing

make test              # Run tests
make test-unit         # Unit tests
make test-integration  # Integration tests
make coverage          # Coverage report

Documentation

• Tutorials – Step-by-step learning guides

• How-To Guides – Task-oriented instructions

• API Reference – Auto-generated from docstrings

• Architecture – Design decisions and diagrams

make docs              # Build docs
make docs-autobuild    # Live reload docs

Configuration

Environment variables for customization:

Project Structure

xpcsviewer/
├── module/            # Analysis modules (g2, saxs, twotime, ...)
├── fileIO/            # HDF5 I/O and Q-map utilities
├── simplemask/        # Mask editor & Q-map
├── gui/               # GUI modernization
│   ├── icons.py       # SVG icon loader with theme-aware colors
│   ├── theme/         # Light/dark theming
│   ├── state/         # Session & preferences
│   ├── shortcuts/     # Keyboard shortcuts
│   └── widgets/       # Modern UI widgets (incl. category tab bar)
├── fitting/           # Bayesian fitting (NLSQ 0.6.0)
├── plothandler/       # Theme-aware plotting
├── threading/         # Async workers
├── utils/             # Utilities, validation, exceptions
└── xpcs_file.py       # Core data class

Analysis Features

• Multi-tau G2 correlation with fitting

• Two-time correlation analysis

• SAXS 2D pattern visualization

• SAXS 1D radial averaging

• Sample stability monitoring

• File averaging tools

• Mask editing with drawing tools (Rectangle, Circle, Polygon, Line, Ellipse)

• Q-map generation from detector geometry

• Q-binning (partition) for XPCS analysis

Fitting Module (NLSQ 0.6.0)

Bayesian fitting with NumPyro NUTS sampler and JAX-accelerated NLSQ warm-start:

• Statistical metrics: R², adjusted R², RMSE, MAE, AIC, BIC

• Confidence intervals for parameter uncertainty

• Prediction intervals accounting for observation noise

• Models: single/double/stretched exponential, power law

• Automatic bounds inference and fallback strategies

• Model health diagnostics

• Batch all-Q Bayesian fitting (fit every Q-bin in one background run)

from xpcsviewer.fitting import nlsq_fit
import jax.numpy as jnp

def model(x, tau, baseline, contrast):
    return baseline + contrast * jnp.exp(-2 * x / tau)

result = nlsq_fit(
    model, x_data, y_data, y_errors,
    p0={'tau': 1.0, 'baseline': 1.0, 'contrast': 0.3},
    bounds={'tau': (0.01, 100), 'baseline': (0.9, 1.1), 'contrast': (0.1, 0.5)},
)
print(f"R² = {result.r_squared:.4f}")
print(result.summary())

Gallery

Analysis Modules Showcase

1. SAXS 2D – Integrated Scattering Pattern

   

2. SAXS 1D – Radial Reduction and Analysis

   

3. Stability – Sample Assessment

   

4. I(t) – Intensity vs Time

   

5. g2 – Correlation Function Viewer

   

6. g2 Fit – Correlation Fitting

   

7. g2 Map – Correlation Map

   

8. Diffusion – tau(q) Characterization

   

9. Two-Time – Correlation Maps

   

10. Q-Map – Q-Space Mapping

    

11. Average – File Averaging Toolbox

    

12. Metadata – HDF5 Explorer

    

License

MIT License. See CONTRIBUTING.md for development guidelines.