Skip to content

About

Python client for X-ray Atlas

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

xrayatlas

Python client for X-ray Atlas, the collaborative database of Near-Edge X-ray Absorption Fine Structure (NEXAFS) spectra.

xrayatlas pulls NEXAFS datasets, metadata, auxiliary files, and optical models from an Atlas deployment, and builds, publishes, shares, forks, reviews, compares, cites, and locks optical models. The client never fits peaks, never computes optical constants, and never normalizes spectra itself: normalization is computed by the server, and the peaks and tensor payloads you upload come from your own analysis code.

Documentation: https://xrayatlas.wsu.edu/docs/python

Install

pip install xrayatlas
# or
uv add xrayatlas

Requires Python 3.10 or newer. Dependencies: numpy, pandas, httpx, and pydantic.

Sign in

Public datasets and public models read anonymously. Writes need a token, which the xatlas CLI issues and stores in a credential file this client shares:

xatlas login

xa.login() runs the same command from Python. The client reads $XDG_CONFIG_HOME/xatlas/credentials.json (default ~/.config/xatlas/credentials.json); XRAYATLAS_TOKEN and XRAYATLAS_HOST override the file. A token is attached only for the host it was issued for, and is never printed or written into the HTTP cache or a lockfile.

Quickstart

import xrayatlas as xa

ds = xa.datasets.get("d/abcd2345")  # current version, pinned and cached
frame = ds.spectra()  # pandas DataFrame of the derived channels the dataset has
geometries = ds.geometries()  # distinct (theta_deg, phi_deg) pairs; (90, 45) != (45, 90)

model = xa.models.get("m/k7m2xq4n")  # latest published version
peaks = model.peaks  # one row per stored peak
channels = model.normalized(ds)  # server-computed normalized channels for a linked dataset

xa.lock("analysis.lock")  # pin every dataset and model version this session read

Guides

Topic What it covers
Datasets Load by Atlas id or UUID, version pins, search, spectra, auxiliary files, BibTeX
Models Read published models: normalization, peaks, linked datasets, lineage, tensors
Build and publish The xa.model(...) builder, drafts, publishing, sharing, forking, reviews
Compare Align peaks and normalized channels across models
Reproduce Lockfiles with xa.lock and xa.restore
Concepts Datasets, versions, models, and what the server computes
Errors The AtlasError hierarchy and when each error is raised
Reference Full API reference

Runnable scripts for each workflow live in examples/.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run mypy src

Releases publish to PyPI automatically when a merge to main changes version in pyproject.toml (uv version --bump patch|minor|major); see .github/workflows/release.yml.

License

BSD-3-Clause. See LICENSE.

About

Python client for X-ray Atlas

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages