Metadata-Version: 2.4
Name: xpcsviewer-gui
Version: 0.1.1
Summary: XPCS Viewer: A python-based interactive tool to visualize and model XPCS dataset
Author-email: Miaoqi Chu <mqichu@anl.gov>, Wei Chen <wchen@anl.gov>
Maintainer-email: Miaoqi Chu <mqichu@anl.gov>, Wei Chen <wchen@anl.gov>
License: MIT License
        
        Copyright (c) 2025, Miaoqi Chu
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/imewei/xpcsviewer
Project-URL: Bug Tracker, https://github.com/imewei/xpcsviewer/issues
Project-URL: Documentation, https://github.com/imewei/xpcsviewer/tree/master/docs
Project-URL: Source Code, https://github.com/imewei/xpcsviewer
Project-URL: Changelog, https://github.com/imewei/xpcsviewer/blob/master/HISTORY.rst
Keywords: XPCS,X-ray,photon correlation spectroscopy,synchrotron,visualization,science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: pyside6>=6.10.1
Requires-Dist: numpy>=2.3.0
Requires-Dist: scipy>=1.16.0
Requires-Dist: h5py>=3.15.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: pyqtgraph>=0.14.0
Requires-Dist: pandas>=2.3.0
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: joblib>=1.5.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: psutil>=7.1.0
Requires-Dist: hdf5plugin>=6.0.0
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.13.0; extra == "dev"
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest-xdist[psutil]>=3.8.0; extra == "dev"
Requires-Dist: pytest-benchmark>=5.2.0; extra == "dev"
Requires-Dist: pytest-mock>=3.15.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: pytest-sugar>=1.1.0; extra == "dev"
Requires-Dist: pytest-html>=4.1.1; extra == "dev"
Requires-Dist: pytest-qt>=4.5.0; extra == "dev"
Requires-Dist: hypothesis>=6.148.0; extra == "dev"
Requires-Dist: mypy>=1.19.0; extra == "dev"
Requires-Dist: ruff>=0.14.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.9.0; extra == "dev"
Requires-Dist: pre-commit>=4.5.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=6.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=9.0.0; extra == "test"
Requires-Dist: pytest-qt>=4.5.0; extra == "test"
Requires-Dist: pytest-xdist[psutil]>=3.8.0; extra == "test"
Requires-Dist: pytest-timeout>=2.4.0; extra == "test"
Requires-Dist: pytest-sugar>=1.1.0; extra == "test"
Requires-Dist: pytest-mock>=3.15.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=8.2.0; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser>=4.0.1; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=3.5.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Provides-Extra: validation
Requires-Dist: memory-profiler>=0.61.0; extra == "validation"
Requires-Dist: line-profiler>=5.0.0; sys_platform != "win32" and extra == "validation"
Requires-Dist: py-spy>=0.3.0; sys_platform == "linux" and extra == "validation"
Provides-Extra: performance
Requires-Dist: pytest-benchmark>=5.2.0; extra == "performance"
Requires-Dist: memory-profiler>=0.61.0; extra == "performance"
Requires-Dist: pympler>=1.1; extra == "performance"
Provides-Extra: all
Requires-Dist: xpcsviewer-gui[dev,docs,performance,test,validation]; extra == "all"
Dynamic: license-file

============
XPCS Viewer
============

Python-based XPCS data analysis and visualization tool.

.. image:: https://github.com/imewei/XPCSViewer/actions/workflows/ci.yml/badge.svg
   :target: https://github.com/imewei/XPCSViewer/actions/workflows/ci.yml
   :alt: CI Status

.. image:: https://img.shields.io/badge/python-3.12%2B-blue.svg
   :target: https://python.org
   :alt: Python Version

.. image:: https://img.shields.io/badge/license-MIT-green.svg
   :target: LICENSE
   :alt: License

.. image:: https://img.shields.io/badge/code%20style-ruff-000000.svg
   :target: https://github.com/astral-sh/ruff
   :alt: Ruff

**Features:**

* G2 correlation analysis with fitting
* SAXS 1D/2D visualization
* Two-time correlation analysis
* HDF5 data support (NeXus format)

**GUI Features:**

* Light/dark theme support with system detection
* 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+

.. code-block:: bash

   # Basic installation
   pip install xpcsviewer

   # Complete installation with all features and tools
   pip install xpcsviewer[all]

   # Install with specific optional dependencies
   pip install xpcsviewer[dev]        # Development tools
   pip install xpcsviewer[docs]       # Documentation building
   pip install xpcsviewer[validation] # Profiling and validation tools
   pip install xpcsviewer[performance] # Performance analysis tools

Usage
-----

**GUI (Interactive):**

.. code-block:: bash

   # 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):**

.. code-block:: bash

   # 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
-----------

.. code-block:: bash

   # Clone and install
   git clone https://github.com/imewei/XPCSViewer.git
   cd XPCSViewer
   pip install -e .[dev]

   # Run tests
   make test

   # Build docs
   make docs

Data Formats
------------

* NeXus HDF5 (APS-8IDI beamline)
* SAXS 2D/1D data
* G2 correlation functions
* Time series data

Testing
-------

.. code-block:: bash

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

Documentation
-------------

- `API Reference <https://github.com/imewei/xpcsviewer/tree/master/docs>`_
- `User Guide <https://github.com/imewei/xpcsviewer/blob/master/docs/usage.rst>`_
- `Quick Start <https://github.com/imewei/xpcsviewer/blob/master/docs/user_guide/quickstart.rst>`_

.. code-block:: bash

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

Configuration
-------------

Environment variables for customization:

.. list-table::
   :header-rows: 1
   :widths: 30 50 20

   * - 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
-----------------

.. code-block::

   xpcsviewer/
   ├── module/            # Analysis modules
   ├── fileIO/            # HDF5 I/O
   ├── gui/               # GUI modernization
   │   ├── theme/         # Light/dark theming
   │   ├── state/         # Session & preferences
   │   ├── shortcuts/     # Keyboard shortcuts
   │   └── widgets/       # Modern UI widgets
   ├── plothandler/       # Theme-aware plotting
   ├── threading/         # Async workers
   ├── utils/             # Utilities
   └── 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

Gallery
-------

**Analysis Modules Showcase**

1. **Integrated 2D Scattering Pattern**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/saxs2d.png
      :alt: 2D SAXS pattern visualization

2. **1D SAXS Reduction and Analysis**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/saxs1d.png
      :alt: Radially averaged 1D SAXS data

3. **Sample Stability Assessment**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/stability.png
      :alt: Temporal stability analysis across 10 time sections

4. **Intensity vs Time Series**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/intt.png
      :alt: Intensity fluctuation monitoring

5. **File Averaging Toolbox**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/average.png
      :alt: Advanced file averaging capabilities

6. **G2 Correlation Analysis**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/g2mod.png
      :alt: Multi-tau correlation function fitting

7. **Diffusion Characterization**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/diffusion.png
      :alt: τ vs q analysis for diffusion coefficients

8. **Two-time Correlation Maps**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/twotime.png
      :alt: Interactive two-time correlation analysis

9. **HDF5 Metadata Explorer**

   .. image:: https://raw.githubusercontent.com/imewei/XPCSViewer/master/docs/images/hdf_info.png
      :alt: File structure and metadata viewer

License
-------

MIT License. See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for development guidelines.
