xpcsviewer-gui 0.1.3

XPCS Viewer: A python-based interactive tool to visualize and model XPCS dataset

Python-based XPCS data analysis and visualization tool.

Features:

• G2 correlation analysis across three tabs (g2 view, g2 Fit, g2 Map)

• SAXS 1D/2D visualization

• Two-time correlation analysis

• Diffusion coefficient extraction (tau-Q analysis)

• Sample stability monitoring

• Mask Editor with Q-map and Q-binning

• HDF5 data support (NeXus format)

GUI Features:

• Light/dark theme support with system detection

• Scalable SVG icons with theme-aware coloring

• Category tab bar grouping 12 analysis tabs

• Session persistence (resume where you left off)

• Command palette (Ctrl+Shift+P) for quick access

• Toast notifications for status updates

• Keyboard shortcut management

• Drag-and-drop file handling

• Theme-aware plots (PyQtGraph & Matplotlib)

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.

GPU Acceleration (Optional)

Default installation uses CPU-only JAX. For GPU acceleration on Linux with an NVIDIA GPU and system CUDA 12+ or 13+:

# Auto-detect system CUDA version (from repo checkout)
make install-jax-gpu

# Or manually install JAX with CUDA support
pip install jax[cuda12-local]    # System CUDA 12.x
pip install jax[cuda13-local]    # System CUDA 13.x

Verify GPU detection:

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

Environment variables for control:

Variable	Description	Default
XPCS_USE_JAX	Enable JAX backend (true, false, auto)	auto
JAX_PLATFORMS	Force CPU/GPU (cpu, cuda)	(auto-detected)
XPCS_GPU_FALLBACK	Allow CPU fallback if GPU fails	true
XPCS_GPU_MEMORY_FRACTION	Maximum GPU memory usage (0.0-1.0)	0.9

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

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:

Variable	Description	Default
XPCS_LOG_LEVEL	Logging verbosity (DEBUG, INFO, WARNING, ERROR)	INFO
XPCS_CACHE_SIZE_MB	Maximum cache size in MB	512
XPCS_THEME	UI theme (light, dark, system)	system

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

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.