spxtacular

spxtacular is a Python library for general mass-spectrum processing across proteomics, metabolomics, lipidomics, glycomics, and oligonucleotide analysis. Its chainable Spectrum API covers denoising, isotope deconvolution, charge assignment, neutral-mass conversion, matching, scoring, interoperability, and interactive visualization.

Part of the tacular-omics ecosystem alongside peptacular, paftacular, and mzmlpy.

Install

pip install spxtacular

# Optional: Numba JIT acceleration
pip install spxtacular[numba]

# Optional: share spectra as compact URL-safe tokens (spectrl)
pip install spxtacular[spectrl]

# Optional: raw-file readers — Bruker .d, mzML, Thermo .raw
pip install spxtacular[bruker]      # tdfpy — DReader
pip install spxtacular[mzml]        # mzmlpy — MzmlReader
pip install spxtacular[thermo]     # fisher-py — ThermoReader (also needs a .NET runtime)
pip install spxtacular[readers]     # all three readers

# Everything (numba + readers + spectrl + interoperability adapters)
pip install spxtacular[all]

Quick start

import numpy as np
import spxtacular as spx

# A 2+ envelope near m/z 500 and a 3+ envelope near m/z 801, over a noise floor.
mz = np.array([
    352.1100, 418.4400, 476.9200,
    500.2573, 500.7590, 501.2606,
    655.3100, 733.0800,
    801.3073, 801.6417, 801.9762, 802.3106,
    918.6500, 1102.4000,
])
intensity = np.array([
    820.0, 1350.0, 690.0,
    100000.0, 51973.0, 11066.0,
    1580.0, 1015.0,
    52335.0, 60000.0, 34070.0, 12544.0,
    745.0, 1240.0,
])

spec = spx.Spectrum(mz=mz, intensity=intensity)

# Full pipeline: denoise → deconvolute → neutral mass
neutral = (
    spec
    .denoise(method="mad")
    .deconvolute(charge_range=(1, 5), tolerance=15, tolerance_type="ppm", min_score=0.4)
    .decharge()
)

for peak in neutral.peaks:
    print(peak)
# Peak(mz=998.5000, int=1.52e+05, z=0, score=1.000)
# Peak(mz=2400.8999, int=1.46e+05, z=0, score=0.998)

neutral.plot(title="Neutral masses").show()

Reading raw files works the same for every format — Reader picks DReader, MzmlReader, or ThermoReader from the path suffix:

with spx.Reader("run.mzML") as reader:   # or spx.Reader("/data/sample.d") / spx.Reader("run.raw")
    print(reader.access_strategy)         # embedded, extracted, rapidgzip, plain, or None
    for spec in reader.ms1:              # .ms1/.ms2 are iterable *and* indexable
        ...

Gzipped mzML uses automatic disk-backed access by default. Create a self-indexed gzip artifact with spx.write_indexed_mzml_gzip("run.mzML", "run.indexed.mzML.gz").

Features

Deconvolution pipeline

# 1. Find isotope clusters → assign monoisotopic m/z + charge + Bhattacharyya score
decon = spec.deconvolute(charge_range=(1, 5), tolerance=10, tolerance_type="ppm")

# charge > 0  → assigned cluster
# charge = -1 → singleton / unassigned
# score 0–1   → isotope profile quality (0.0 for singletons)

# 2. Keep only high-confidence clusters
filtered = decon.filter(min_score=0.5)

# 3. Convert to neutral masses (drops singletons)
neutral = filtered.decharge()

Choose an average-composition model for the analyte class, or supply a custom IsotopeModel. Peptides remain the default for backward compatibility:

lipid_neutral = spec.deconvolute(
    isotope_model="lipid",
    ionization_model="[M+Na]+",
).decharge()

Polarity and adducts are explicit while charge arrays remain positive magnitudes. Deconvolution records the selected carrier so decharge() reuses the same mass equation:

negative = spec.deconvolute(ionization_model="[M-H]-").decharge()
sodiated = spec.deconvolute(ionization_model="[M+Na]+").decharge()

custom = spx.IonizationModel(
    name="potassiated",
    polarity="positive",
    carrier_mass=38.963158,
    carrier="K",
)
potassiated = spec.deconvolute(ionization_model=custom).decharge()

Visualization

Every plot is drawn from one theme module — a palette checked with a colour-vision-deficiency validator in both light and dark modes. Intensities are shown relative to the base peak by default, direct labels are capped and collision-avoided (the rest stay in the hover), and table_view() renders the same data as an accessible HTML table for keyboard and screen-reader users.

import peptacular as pt
import spxtacular as spx

spx.theme.set_plot_theme("dark")   # global default: "light" (default) or "dark"

frags = pt.fragment("PEPTIDE", ion_types=("b", "y"), charges=(1, 2))

fig = spec.annotate(frags)                                   # annotated fragment spectrum
ladder = spx.sequence_coverage_plot(spec, "PEPTIDE", frags)  # backbone coverage ladder
html = spx.table_view(spx.build_annot_plot_table(spec, frags))

spx.save_figure(fig, "spectrum.html")   # .png/.svg/.pdf also work — those need kaleido

matchms and spectrum_utils

Install spxtacular[matchms], spxtacular[spectrum-utils], or spxtacular[interop] for both. The integrations are lazy optional adapters, so the base package does not import either stack.

import spxtacular as spx

# matchms pipelines, similarities, Spec2Vec, MS2DeepScore, etc.
matchms_spec = spx.to_matchms(spec, extra_metadata={"smiles": "CCO"})
restored = spx.from_matchms(matchms_spec)

# spectrum_utils ProForma annotation and Matplotlib / Altair plots
su_spec = spx.to_spectrum_utils(ms2_spec)
su_spec.annotate_proforma("PEPTIDE/2", 10, "ppm")

The matchms bridge stable-sorts peaks and includes conventional metadata plus a namespaced payload that preserves spxtacular's richer fields on return conversion. The spectrum_utils bridge is necessarily lossy: its model holds one precursor and no per-peak charge, ion mobility, isotope score, or acquisition metadata. It warns when populated fields are dropped, and its upstream model stores intensities as float32.

Sharing spectra

With the optional [spectrl] extra, encode a complete spectrum (peaks, charges, ion mobility, and MSn metadata) into a single compact, URL-safe token — or a ready-to-share link — with no backend required.

token = spec.to_spectrl_token()                       # spectrl.v1.… token
restored = spx.Spectrum.from_spectrl_token(token)

url = spec.to_spectrl_url("https://example.com/view")  # …#spectrl.v1.… (shareable)
restored = spx.Spectrum.from_spectrl_url(url)

Documentation

Full documentation with API reference, guides, and interactive plots is available at tacular-omics.github.io/spxtacular.

• Spectrum API
• Deconvolution
• Readers
• Matching & Scoring
• Visualization
• API Reference

Citing and contributing

Citation metadata is available in CITATION.cff. A version-specific Zenodo DOI will be added after the release is archived. Bug reports, support questions, and contributions are welcome; see CONTRIBUTING.md for the development workflow and community guidelines.

License

MIT