IsoDec

IsoDec assigns charge states and deconvolves isotopically resolved mass spectrometry data. Its native core uses IsoGen for peptide and RNA isotope distributions.

Installation

Install a published wheel:

python -m pip install isodec

IsoDec supports Python 3.9 and newer on 64-bit Windows, Linux, and macOS, including Apple silicon. Native builds are also tested on ARM64 Windows and Linux. Compatible wheels include the native IsoDec and IsoGen libraries. A source build requires CMake 3.22.1 or newer, a C/C++ compiler, FFTW, and an initialized IsoGen submodule:

git clone --recurse-submodules https://github.com/michaelmarty/IsoDec.git
python -m pip install ./IsoDec

Python usage

import numpy as np
from isodec import IsoDecRuntime

spectrum = np.loadtxt("spectrum.txt")
engine = IsoDecRuntime()
peaks = engine.batch_process_spectrum(spectrum, centroided=True)

for peak in peaks:
    print(peak.mz, peak.z, peak.monoiso, peak.matchedintensity)

TXT, DAT, CSV, and NPZ single-scan spectra are supported without UniDec. Raw vendor files, mzML/mzXML, and I2MS import use UniDec's extensive importer stack:

python -m pip install "isodec[unidec]"

Command line

isodec spectrum.txt --centroided -o assigned_peaks.tsv
python -m isodec --help

Development

git submodule update --init --recursive
python -m pip install -e ".[test]"
python -m pytest

Documentation sources live in docs/ and are built with MkDocs. Release and wheel-building details are in PUBLISHING.md.

Fragment matching

Match deconvolved neutral masses to theoretical protein fragments with a 5 ppm default tolerance:

from isodec import match_fragments

match_fragments(pks, "PEPTIDE", ion_types="by", monoisotopic=True)
print(pks.fragment_match_percent, pks.sequence_coverage)
print(pks.fragment_matches)

Each matched peak receives a sequence_match annotation such as "b6". Pass allow_duplicate_assignments=True to retain every valid annotation as a list instead of selecting the assignment with the smallest ppm error. Pass match_multiple_monoisotopics=False to match only each peak's monoiso mass instead of all masses in monoisos.

To view matches along a wrapped sequence, run python tests/show_fragment_matches.py from the IsoDec directory. The demo uses IsoGen's carbonic anhydrase ETD masses. For an embedded view, call plot_fragment_matches(ax, sequence, pks) from isodec.fragment_view with an existing Matplotlib axis. Modified residues are shown in red. The standalone view is sized for a two-column figure; save the returned Matplotlib figure as SVG or PDF for publication.

License and citation

IsoDec is released under the BSD 3-Clause License. See THIRD_PARTY_NOTICES.md for IsoGen, FFTW, and Intel runtime notices. When using IsoDec, please cite Pavek et al., “A Fast Neural Network for Isotopic Charge State Assignment,” J. Am. Chem. Soc. 2025, 147, 21610–21620. Machine-readable metadata is provided in CITATION.cff.

Changelog

2.0.3

• Added fragment matching viewer.

2.0.2

• Added fragmentation matching options.
• Updated to IsoGen 1.1.1 for ProForma fragment masses and corrected z-ion annotations.

2.0.1

• Improved native processing performance with optimized AVX matrix operations, linear-time peak detection, faster isotope matching, and reusable work buffers.
• Moved installed native libraries and executables into isodec/bin; Windows binaries are included with the package.
• Added processing-time and matched-peak reporting for native spectrum runs.
• Added automated MSVC-versus-IntelLLVM performance benchmarking.

2.0.0

• Split IsoDec from UniDec into the standalone isodec package, with IsoGen as a submodule and an independent version and release cycle.
• Added experimental charge-state assignment directly from profile-mode data.
• Added cross-platform tests—including native ARM64 Windows and Linux coverage—documentation, and automated wheel and source distribution publishing.

1.0.0

• Initial IsoDec release with IsoGen integration for isotopic charge-state assignment and deconvolution of mass spectrometry data, distributed as part of UniDec.