Coded by Claude from SAXS_IgorCode Irena. Planned, defined, debugged, and validated by Jan Ilavsky.
Python tools for small-angle scattering (SAS) data analysis. A port of the Igor Pro Irena package. Includes interactive GUI tools for fitting, modeling, data merging, and visualization of SAXS/SANS/USAXS data.
Current release: v0.7.0 (public beta)
From PyPI (recommended):
pip install pyirena[gui]This installs pyirena with all GUI dependencies (PySide6, pyqtgraph, etc.). For the
core library only (no GUI), use pip install pyirena.
From source (for development):
git clone https://github.com/jilavsky/pyirena.git
cd pyirena
pip install -e ".[gui]"With conda:
git clone https://github.com/jilavsky/pyirena.git
cd pyirena
conda env create -f environment.yml
conda activate pyirenaenvironment.yml uses conda for Python + scientific stack and pip (inside
conda) for the entire Qt6/GUI stack — this split is deliberate. Do not
run conda install pyside6 in this env, and use Python 3.10 – 3.13
(Python 3.14 wheels are still flaky for compiled bindings).
See docs/installation.md for full details, troubleshooting, and platform notes.
pyirena-guiThis launches the Data Selector, the main entry point for all analysis tools. See docs/gui_quickstart.md for a walkthrough.
Individual tools can also be launched directly:
| Command | Tool |
|---|---|
pyirena-gui |
Data Selector (main entry point) |
pyirena-viewer |
Data Explorer |
pyirena-modeling |
Modeling tool (standalone) |
pyirena-datamerge |
Data Merge tool (standalone) |
pyirena-contrast |
Scattering Contrast Calculator |
Parametric forward-modeling of SAS data. Combine up to 10 populations, each of which can be a Size Distribution, Unified Fit Level, or Diffraction Peak. Fits the combined model to experimental data using least-squares optimization.
- 5 distribution functions: Gaussian, LogNormal, LSW, Schulz-Zimm, Ardell
- 9 form factors: Sphere, Spheroid, Cylinder (aspect ratio / fixed length), Core-Shell Sphere and Spheroid (by core R / shell t / total R)
- 2 structure factors: Born-Green interferences, Hard Sphere (Percus-Yevick)
- Monte Carlo uncertainty estimation
- Modeling GUI guide
Beaucage hierarchical model (1995, 1996) with 1-5 structural levels, each combining Guinier and power-law contributions. Optional Born-Green correlation function.
Indirect Fourier transform to recover particle size distributions from SAS data. Four inversion methods: MaxEnt, Regularization, TNNLS, and Monte Carlo.
13 direct analytical models: Guinier, Guinier-Porod, Porod, Sphere, Spheroid, Debye-Bueche, Treubner-Strey, Power Law, and more. Each with linearization plots and Monte Carlo uncertainty estimation.
Fit diffraction peaks (Gaussian, Lorentzian, Pseudo-Voigt, Log-Normal) on linear
I vs Q scale. Auto-detect peaks via Savitzky-Golay + scipy.signal.find_peaks.
Simultaneous background fitting (constant, linear, cubic, or 5th-order polynomial).
Merge two SAS datasets (e.g., SAXS + WAXS) onto a common Q scale. Optimizes scale factor, flat background, and optional Q-shift using Nelder-Mead.
Browse NXcanSAS HDF5 files, inspect raw data and analysis results, extract and plot datasets, and export to Igor Pro h5xp format. Supports all pyIrena result types (Unified Fit, Sizes, Simple Fits, WAXS Peaks, Modeling).
Open an Igor Pro packed experiment (.pxp or .h5xp) and export each
reduced USAXS/SAXS/WAXS sample as a stand-alone NXcanSAS .h5 file.
Brings legacy and modern Igor data into pyIrena's analysis tools
without re-reducing from raw detector files.
Look up X-ray and neutron scattering length densities for materials by chemical formula. Computes contrast (Delta-rho-squared) between two materials.
Central GUI panel for managing data files and launching analysis tools. Load HDF5 files, select datasets, tabulate results across files, and generate reports.
All analysis tools can be run headlessly from Python scripts or JSON configuration files:
from pyirena.batch import fit_pyirena
results = fit_pyirena(
data_file='sample.h5',
config_file='pyirena_config.json',
)Individual functions: fit_unified, fit_sizes, fit_simple, fit_waxs,
fit_modeling, merge_data.
See docs/batch_api.md for the full scripting guide.
All data and results are stored in HDF5 files using the NXcanSAS format. Fit results are saved alongside raw data, making files self-contained and shareable.
pyirena ships a Model Context Protocol server that exposes its HDF5 readers, parameter aggregation, and headless plotting to any MCP client — Claude Desktop, Claude Code, custom AI agents.
pip install pyirena[mcp]Add to claude_desktop_config.json (or your client's MCP server config):
{
"mcpServers": {
"pyirena": {
"command": "pyirena-mcp",
"env": {
"PYIRENA_DATA_ROOT": "/path/to/your/data",
"PYIRENA_PLOT_CACHE": "/tmp/pyirena-plots",
"PYIRENA_MAX_ARRAY_POINTS": "500"
}
}
}
}The agent can then call tools like pyirena_summarize_folder,
pyirena_tabulate_parameter, pyirena_plot_iq, pyirena_read_modeling etc.
to answer questions about analysis results in plain language. The underlying
pyirena.api module is also usable as a regular Python library, with unprefixed
names (api.summarize_folder, api.plot_iq, …) — no MCP needed.
Full instructions, including configs for Claude Desktop, Claude Code, and AnythingLLM:
- docs/ai_integration.md — install & configure
- docs/ai_tools_reference.md — tool reference for AI agents (system-prompt material)
| Topic | File |
|---|---|
| Installation | docs/installation.md |
| Quick start (GUI) | docs/gui_quickstart.md |
| Modeling GUI guide | docs/modeling_gui.md |
| Unified Fit GUI guide | docs/unified_fit_gui.md |
| Unified Fit features & parameters | docs/unified_fit_features.md |
| Size Distribution methods | docs/sizes_methods.md |
| Simple Fits GUI guide | docs/simple_fits_gui.md |
| WAXS Peak Fit GUI guide | docs/waxs_peakfit_gui.md |
| Data Merge GUI guide | docs/data_merge_gui.md |
| Data Explorer guide | docs/hdf5_viewer_gui.md |
| Import Igor Experiment (.pxp / .h5xp → NeXus) | docs/igor_pxp_import.md |
| Contrast Calculator guide | docs/scattering_contrast_gui.md |
| NXcanSAS file format | docs/NXcanSAS_UnifiedFit_Format.md |
| Batch fitting API | docs/batch_api.md |
| Usage guide (scripting) | docs/usage_guide.md |
| AI integration (MCP) — install & configure | docs/ai_integration.md |
| AI integration (MCP) — tool reference for agents | docs/ai_tools_reference.md |
| Developer: adding form factors | docs/developer_adding_form_factors.md |
| Developer: adding structure factors | docs/developer_adding_structure_factors.md |
| Testing | docs/testing.md |
| Distribution / packaging | docs/distribution.md |
| Contributing | CONTRIBUTING.md |
| Changelog | CHANGELOG.md |
MIT -- see LICENSE.
- Author: Jan Ilavsky -- ilavsky@aps.anl.gov
- Affiliation: X-ray Science Division, Argonne National Laboratory
- Issues: https://github.com/jilavsky/pyirena/issues