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.3.2 (first 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 pyirenaSee 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 |
HDF5 Viewer / Data Extractor |
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. Supports all pyIrena result types (Unified Fit, Sizes, Simple Fits, WAXS Peaks, Modeling).
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.
| 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 |
| HDF5 Viewer guide | docs/hdf5_viewer_gui.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 |
| 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