Skip to content

XPS Analyzer

A mathematically rigorous, type-safe Python package for automated X-ray Photoelectron Spectroscopy data analysis. Built with Pydantic v2 validation, NumPy vectorization, and non-linear optimization via lmfit.

Python 3.10+ License: MIT Code style: ruff Tests Coverage
Get Started User Guide API Reference

Design Principles

Immutability by Default

Raw spectral data is never modified in place. Every operation returns a deep copy via model_copy(deep=True), preserving full provenance.

Runtime Validation

Pydantic v2 enforces array dimension consistency, positive energy values, and physically meaningful parameter ranges at every stage.

Algorithmic Transparency

Shirley, Tougaard, and Voigt implementations are documented with their mathematical formulations. No black-box approximations.

Separation of Concerns

Six independent modules — data loading, preprocessing, analysis, reference data, export, and visualization — each with a single responsibility.

Explicit Configuration

All algorithmic parameters (convergence tolerances, broadening models, RSF databases) have documented defaults and are fully overridable via TOML profiles.

Interoperable I/O

Export results to CSV, Excel, or JSON. Custom NumPy encoder preserves array types in JSON serialization. Streamlit GUI for interactive exploration.

Quick Example

from xps_analyzer import load_single_file
from xps_analyzer.analysis import shirley_background, fit_voigt, calculate_atomic_concentration
from xps_analyzer.export import export_to_excel

# Load spectrum with automatic format detection
dataset = load_single_file("data/raw/samples/sample.txt")
c1s = dataset.get_spectrum("C 1s")

# Background subtraction (Shirley iterative integral)
c1s_nobg = shirley_background(c1s, inplace=False)

# Voigt profile fitting with Levenberg-Marquardt
fit = fit_voigt(c1s_nobg, position=284.8, fwhm=1.2)

# Atomic quantification via Scofield RSF
concentration = calculate_atomic_concentration(dataset, rsf_database="scofield")

# Export results
export_to_excel({"fit": fit, "concentration": concentration}, "results.xlsx")

Core Pipeline

graph LR
    A[Raw Data Files] --> B[data_loader]
    B --> C[preprocessing]
    C --> D[analysis]
    D --> E[background]
    D --> F[peak_fitting]
    D --> G[quantification]
    E --> H[export]
    F --> H
    G --> H
    H --> I[CSV / Excel / JSON]
    style A fill:#e8eaf6,stroke:#283593
    style I fill:#e8eaf6,stroke:#283593
355
Tests
93%
Coverage
6
Core Modules
v0.8
Current Version

License

Distributed under the MIT License. See LICENSE for details.

Author: Jesus Flores Lacarra — jss.263.fsc@gmail.com