openauc-io

Open-source Python tools for ingesting, validating, plotting, generating, and archiving analytical ultracentrifugation data.

Documentation · Quickstart · CLI guide · Report a bug · Ask a question

Current capabilities

• Generic long- and wide-format CSV/TSV ingestion
• Typed canonical AUC experiment model
• Structural validation and analysis-readiness reporting
• Shared and per-scan radial-axis support
• Scan plotting without interpolation or regridding
• Checksum-verified AUCX archives
• Deterministic illustrative synthetic data generation
• Python API and command-line interface

[!IMPORTANT] No scientific AUC analysis is implemented. openauc-io does not currently perform sedimentation fitting, molecular-weight estimation, meniscus detection, convection assessment, scientific quality control, or physically validated Lamm-equation simulation.

Installation

Not on PyPI. From a clone:

git clone https://github.com/ronfinn/openauc-io.git
cd openauc-io
uv sync --all-groups
uv run openauc version          # 0.1.0a1

Or install a locally built wheel:

uv build
uv pip install dist/openauc-0.1.0a1-py3-none-any.whl

Requires Python 3.11, 3.12 or 3.13. Full detail: Installation.

End-to-end example

import openauc
from openauc.plotting import plot_scans

experiment = openauc.load("examples/data/demo_experiment")
print(experiment.summary())

report = experiment.validate()
ax = plot_scans(experiment)

experiment.export("experiment.aucx")
restored = openauc.load("experiment.aucx")
assert restored.to_dict() == experiment.to_dict()

CLI quickstart

uv run openauc generate demo.aucx --format aucx --scenario moving-boundary \
  --scans 20 --points 300 --seed 42
uv run openauc inspect  demo.aucx
uv run openauc validate demo.aucx --readiness
uv run openauc convert  examples/data/demo_experiment archive.aucx

Exit codes: 0 success, 1 structural validation failed, 2 input error, 3 output exists. See the CLI reference.

Scope

The first alpha provides generic long/wide CSV/TSV import, JSON/YAML manifests, a canonical experiment model, structural validation, scan summaries, basic plotting, the versioned .aucx archive with checksums and provenance, synthetic data generation, a CLI, and documentation.

This project is not a replacement for SEDFIT, SEDPHAT, UltraScan, GUSSI or other established AUC analysis software. It performs no sedimentation modelling or fitting. It is an independent, clean-room implementation and does not copy code or interfaces from those tools.

Four ideas are kept deliberately distinct: representation, structural validation, analysis readiness, and scientific suitability — the last of which is always reported as NOT_ASSESSED. See Scientific boundaries.

Documentation

Build the site locally:

uv run mkdocs serve      # http://127.0.0.1:8000/

Development

uv sync --all-groups
uv run ruff check .        # lint
uv run ruff format .       # format
uv run mypy                # type-check (strict)
uv run pytest              # tests
uv run mkdocs build --strict

Or run all of those source-tree gates in one command:

uv run python scripts/release_check.py

It checks the source tree only — it builds, tags, releases and publishes nothing. Building and verifying real distribution artifacts, clean-environment smoke testing, tagging, the GitHub release and the PyPI upload are separate steps, all documented in the release checklist.

See CONTRIBUTING.md and the Architecture Decision Records under docs/decisions/.

Licence

Apache License 2.0. Copyright 2026 Ron Finn. See LICENSE and NOTICE.

Citation

If you use openauc-io, please cite it using the metadata in CITATION.cff.