Software
SAXS Assistant: automated SAXS analysis in Python
A scattering profile takes a trained analyst a few minutes of judgement calls. SAXS Assistant makes those calls explicitly, applies them the same way to every profile in a folder, and flags the results it cannot stand behind.
- What it is
An open-source Python package —
saxs-assistanton PyPI, GPLv3 — that runs a whole SAXS analysis pipeline from one call. It is built on BioXTAS RAW, so it extends workflows that already use RAW rather than replacing them.- Who wrote it
The package is by Cesar Ramirez, first author on the paper describing it. I am a co-author on that paper. This page is a reference for the tool, not a claim on the code: PyPI is canonical for the current API.
- Who it is for
Anyone with more scattering profiles than patience — high-throughput SAXS on biologics or polymeric nanoparticles, where the analysis rather than the beamtime is the bottleneck.
Install
Python 3.7 or newer, locally or in Google Colab.
pip install saxs-assistant
In a Colab notebook, prefix the command with !. Dependencies install
automatically.
Running an analysis
Build an input manifest, then analyse everything in it.
1. Build the input file
Point it at a folder of .dat profiles and it writes an Excel manifest. The folder must
contain only .dat files; anything else in there will error.
from saxs_assistant.runner import prepare_dataframe df = prepare_dataframe(folder_path="path/to/folder", angular_unit="1/A")
The manifest carries three columns — file name, path and
Angular unit, the last being either 1/A or 1/nm — and you
can equally write it by hand.
2. Analyse
from saxs_assistant.runner import analyze_and_plot_all
plot_data, results = analyze_and_plot_all("path/to/input_file.xlsx")
Optional arguments analyse a slice of a large manifest rather than all of it, which matters once a run
takes hours: start_index, end_index and output_dir.
3. Combine sessions
Each run writes to return/, then return_1/, return_2/ and so
on. To merge them into a single results table:
from saxs_assistant.organizer import combine_sessions combine_sessions(base_path="path/to/folder")
What comes back
Parameters per profile, and two PDFs that separate what you can use from what you need to look at.
- Structural parameters
Guinier radius of gyration, the radius of gyration derived from the pair distance distribution function, maximum particle dimension (Dmax), and Kratky features.
- results.xlsx
Every extracted parameter, one row per profile. The call also returns split frames in memory: the solved profiles, and the ones it could not solve or flagged fatally.
- summary_plots.pdf and flagged_plots.pdf
Good fits in one file, problems in the other. The split is the point — you review the flagged PDF and leave the rest alone.
- plot_data.joblib
The raw graph data, so you can re-plot without re-running the analysis.
The parts that make it trustworthy
Automating judgement calls is only useful if the automation knows when it is out of its depth.
- Guinier/PDDF cross-validation
The radius of gyration is obtained two independent ways and the two are required to agree. Disagreement is a reliable indicator of a badly measured dataset, so the check is built into the pipeline instead of being left to the analyst to remember.
- A model trained only on real profiles
Dmax estimation uses a multilayer perceptron trained on 1,940 experimental data files from the Small Angle Scattering Biological Data Bank — no simulated data. Reported test-set performance is R² = 0.90 with a mean absolute error of 11.7 Å. Training on what practitioners actually did is what lets the model stand in for their judgement.
- Clustering, not shape claims
Gaussian mixture model clustering places a profile against SASBDB entries, so you can see which known biomolecular shapes a sample resembles. It quantifies what is in a Kratky plot without pretending to a structure.
- It declines to answer
Low-confidence results are flagged rather than returned silently. That is the behaviour worth wanting in any automated analysis: a pipeline that reports a number it cannot stand behind is worse than one that reports nothing.
The authors are explicit that the tool carries no warranty and that results should be evaluated carefully. It accelerates the analysis; it does not absolve you of reading it.
What to cite
If SAXS Assistant is in your methods section, cite the paper and the tools underneath it.
Cesar Ramirez, … <b>Eman Ahmed</b> … Adam J. Gormley "SAXS Assistant: Automated SAXS analysis for structural discovery in biologics and polymeric nanoparticles" Biophysical Journal 124(21), 3772-3786 (2025). doi:10.1016/j.bpj.2025.09.034
The package also asks that you cite BioXTAS RAW, BIFT and Franke et al., since the pipeline is built on them:
- Hansen, S. Journal of Applied Crystallography 33, 1415–1421 (2000). doi:10.1107/S0021889800012930
- doi:10.1107/S1600576723011019
- doi:10.1107/S0021889809023863
- doi:10.1016/j.bpj.2018.04.018
