pyirena 0.4.3

Python tools for small-angle scattering data analysis.

pyIrena

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)

---

Installation

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 pyirena

See docs/installation.md for full details, troubleshooting, and platform notes.

---

Running the GUI

pyirena-gui

This 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

---

Analysis Tools

Modeling

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

Unified Fit

Beaucage hierarchical model (1995, 1996) with 1-5 structural levels, each combining Guinier and power-law contributions. Optional Born-Green correlation function.

• Unified Fit GUI guide
• Unified Fit features & parameters

Size Distribution

Indirect Fourier transform to recover particle size distributions from SAS data. Four inversion methods: MaxEnt, Regularization, TNNLS, and Monte Carlo.

• Size Distribution methods

Simple Fits

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.

• Simple Fits GUI guide

WAXS Peak Fit

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).

• WAXS Peak Fit GUI guide

Data Merge

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.

• Data Merge GUI guide

HDF5 Viewer / Data Extractor

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).

• HDF5 Viewer guide

Scattering Contrast Calculator

Look up X-ray and neutron scattering length densities for materials by chemical formula. Computes contrast (Delta-rho-squared) between two materials.

• Contrast Calculator guide

Data Selector

Central GUI panel for managing data files and launching analysis tools. Load HDF5 files, select datasets, tabulate results across files, and generate reports.

---

Batch Scripting API

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.

---

NXcanSAS I/O

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.

• NXcanSAS format details

---

Documentation

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

---

License

MIT -- see LICENSE.

Contact

• Author: Jan Ilavsky -- [e-mail]
• Affiliation: X-ray Science Division, Argonne National Laboratory
• Issues: https://github.com/jilavsky/pyirena/issues