Metadata-Version: 2.4
Name: autosaxs
Version: 3.0.0
Summary: Interactive SAXS pipeline core: calibration, integration, subtraction, ATSAS descriptors, plots, shape fitting, reports. After install, run `autosaxs --help`: epilog lists get-docs, get-skills, get-default-config (export docs and default config into your workspace).
Author-email: "Mikhail S. Lifar" <mikhailkulkov11@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/MikhailLifar/autoSAXS
Project-URL: Repository, https://github.com/MikhailLifar/autoSAXS
Project-URL: Issues, https://github.com/MikhailLifar/autoSAXS/issues
Project-URL: Documentation, https://github.com/MikhailLifar/autoSAXS#readme
Keywords: saxs,small-angle scattering,pyFAI,ATSAS,calibration,integration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase
Requires-Dist: denss>=1.8.0
Requires-Dist: fabio
Requires-Dist: matplotlib
Requires-Dist: mcsas3>=1.0.6
Requires-Dist: numpy<2.4,>=2.0
Requires-Dist: pandas
Requires-Dist: pyFAI
Requires-Dist: PyYAML
Requires-Dist: reportlab
Requires-Dist: sasmodels
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: seaborn
Requires-Dist: squarify
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: import-linter; extra == "dev"
Requires-Dist: pip; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: gui
Requires-Dist: customtkinter; extra == "gui"
Requires-Dist: PyQt5; extra == "gui"
Requires-Dist: watchdog; extra == "gui"
Provides-Extra: llm
Requires-Dist: httpx; extra == "llm"
Requires-Dist: openai; extra == "llm"
Requires-Dist: requests; extra == "llm"
Dynamic: license-file

# autoSAXS

**autoSAXS** is a Python toolkit for reproducible small-angle X-ray scattering (SAXS) pipelines — from detector images to subtracted curves, size distributions, and shape models — usable from a **CLI**, from **Python**, from desktop GUIs or through your favourite AI agent.

<p align="center">
  <img src="https://raw.githubusercontent.com/MikhailLifar/autoSAXS/main/readme-assets/hero_model_dam_frequency.gif" alt="model_dam frequency / occupancy map" width="420"/>
</p>

## Why autoSAXS

- **One skills API for everything** — the same processing steps run as `autosaxs <skill> …` or as Python functions with stable signatures, so scripts, GUIs, and agents share one surface.
- **Unique algorithms** — **automatic calibration** from calibrant frames and **automatic buffer scaling** for robust sample−buffer subtraction, reducing manual tuning at the beamline.
- **Flexible inputs** — path expressions (file, directory, or glob) instead of “one file only,” with consistent expansion rules.
- **Opt-in caching** — re-run interactive work without recomputing unchanged steps.
- **GUIs when you want them** — `guisaxs-skills` (form-driven skill runner) and `guisaxs-liveview` (watch-folder live processing with optional monodisperse / polydisperse analysis).
- **Built for automation** — designed for reproducible beamline-to-analysis workflows and LLM/agent-driven runs via the CLI.
- **Seamless AI integration** — ship a built-in **`saxs-processing`** Cursor/agent skill (`autosaxs get-skills`) so assistants can orchestrate the pipeline from documented procedures.

## Use cases

- Synchrotron or lab SAXS: calibrate geometry, integrate TIFF stacks, average frames, and subtract buffer.
- Monodisperse analysis: Guinier → pair-distance distribution p(r) → optional ab initio shape recovery, 3d primitives modeling or electron density inference.
- Polydisperse analysis: Guinier → size distribution D(R) → optional McSAS or ATSAS MIXTURE.
- Live experiments: watch a folder for new detector images and process them as they arrive.
- Scripting and agents: drive the full pipeline from Python or `autosaxs` without reimplementing I/O conventions.

## Install

Core + CLI:

```bash
python -m pip install autosaxs
autosaxs --help
```

With desktop GUIs (`guisaxs-skills`, `guisaxs-liveview`):

```bash
python -m pip install "autosaxs[gui]"
```

Optional LLM helper stack (`openai` / `httpx` / `requests`):

```bash
python -m pip install "autosaxs[llm]"
```

Helper commands (export docs and defaults into a directory):

- `autosaxs get-docs` — write the short `README.md` and detailed `autosaxs-docs/skills_reference.md`
- `autosaxs get-skills` — write Cursor-style `saxs-processing/` skill
- `autosaxs get-default-config` — copy bundled `config_base.conf`

From git `main` (development): `python -m pip install "autosaxs @ git+https://github.com/MikhailLifar/autoSAXS.git"` or `autosaxs -U`

## Main features

Pipeline stages exposed as skills: **calibrate → integrate / average → subtract → analyze → model → report**, including Guinier, Kratky, `fit-distances` (p(r)), `fit-sizes` (D(R)), `model-dam`, `model-bodies`, `model-density` (DENSS), `model-dr-mc` (McSAS), `model-mixture`, and reporting helpers.

Apps: 
**guisaxs-skills** (catalog + forms + isolated CLI runs, beta version)
**guisaxs-liveview** (queued live integration, buffer subtraction, optional analysis wizards).

Full per-skill documentation: [`autosaxs-docs/skills_reference.md`](autosaxs-docs/skills_reference.md).

## Quick start

Monodisperse protein walkthrough using [`examples/monodisperse_protein/`](examples/monodisperse_protein/) (AgBh calibrant, mask, sample + buffer TIFFs). `--q-min` / `--q-max` are the buffer-matching window in nm⁻¹ — pick them from the sample+buffer overlay; `4.8`–`5.8` fits this example.

### Python

```python
from pathlib import Path
from autosaxs.skill import calibrate, integrate, subtract, process_monodisperse

ex = Path("examples/monodisperse_protein")

calibrate(
    ex / "AgBh700_96.9_calib.tif",
    output_dir=str(ex / "calibration"),
    mask=ex / "mask-20260706_133745.txt",
    wavelength=1.445,
)
integrate(
    f"{ex / 'ihs27_buffer.tif'}, {ex / 'ihs27_sample.tif'}",
    ex / "calibration" / "integrator",
    output_dir=str(ex / "integrated"),
)
subtract(
    ex / "integrated" / "int_ihs27_sample.dat",
    ex / "integrated" / "int_ihs27_buffer.dat",
    output_dir=str(ex / "subtracted"),
    q_min=4.8,
    q_max=5.8,
)
process_monodisperse(ex / "subtracted" / "sub_ihs27_sample.dat")
```

### CLI

```bash
cd examples/monodisperse_protein

autosaxs calibrate AgBh700_96.9_calib.tif \
  --mask mask-20260706_133745.txt --wavelength 1.445 -o calibration/

autosaxs integrate "ihs27_buffer.tif, ihs27_sample.tif" \
  calibration/integrator/ -o integrated/

autosaxs subtract integrated/int_ihs27_sample.dat integrated/int_ihs27_buffer.dat \
  --q-min 4.8 --q-max 5.8 -o subtracted/

autosaxs process-monodisperse subtracted/sub_ihs27_sample.dat
```

### Online GUI

```bash
guisaxs-liveview
```

## Acknowledgements

autoSAXS builds on the SAXS ecosystem rather than replacing it:

- **[pyFAI](https://pyfai.readthedocs.io/)** — detector geometry, calibration, and 1D integration.
- **[ATSAS](https://www.embl-hamburg.de/biosaxs/download.html)** — tools such as `autorg`, `datgnom`, `gnom`, `dammif`, `mixture`, and `bodies` (external install; recommended **ATSAS 3.2.1**). Importing autoSAXS **warns** if ATSAS is missing; skills that shell out to ATSAS **raise** immediately when it is unavailable.
- **[DENSS](https://www.tdgrant.com/denss)** — electron-density reconstruction (`model_density`); pulled in via the `denss` PyPI dependency.
- **[McSAS](https://github.com/BAMresearch/McSAS) / McSAS3** — Monte Carlo polydisperse sizing (`model_dr_mc`).

## Contacts

- **Mikhail S. Lifar** — `mikhailkulkov11@gmail.com`
- Affiliation: The Smart Materials Research Institute, Southern Federal University (Rostov-on-Don)
- Project: [github.com/MikhailLifar/autoSAXS](https://github.com/MikhailLifar/autoSAXS)

## Contributing

Issues and pull requests are welcome on GitHub. Bug reports, clearer docs, and new skill coverage all help. Licensed under the **Apache License 2.0**.
