MsDecon

msdecon is a Python package for performing simple isotopic deconvolution. It uses a graph-based approach to identify and group peaks belonging to the same isotopic distribution.

Algorithm Overview

The deconvolution algorithm in MsDecon identifies isotopic envelopes by constructing a graph representation of mass spectra and tracing isotopic patterns to detect monoisotopic peaks and assign charge states.

Step 1: Graph Construction

• Nodes: Each peak in the mass spectrum (m/z and intensity) is represented as a node.
• Edges: Edges are created between peaks if the mass difference matches the expected neutron mass shift divided by the charge state:
  [ \Delta m = \frac{1.00866491578}{\text{Charge}} ]
  This is repeated for all charge states within the specified range. Only peaks that fall within the defined tolerance (ppm or Da) are connected.

---

Step 2: Greedy Peak Selection

• The most intense peak is selected first. This peak serves as the starting point for identifying isotopic envelopes.
• Peaks that have already been assigned to an envelope are skipped in subsequent iterations.

---

Step 3: Isotopic Envelope Tracing

• For each charge state, the graph is traversed:

  • Leftward Search (lower m/z) – Finds earlier isotopic peaks.
  • Rightward Search (higher m/z) – Extends the envelope to higher m/z peaks.

• Peaks must not decrease in intensity by more than a specified factor when moving left or right. By default, this factor is 0.6 for leftward search and 0.9 for rightward search (since Isotopic distribution of lower mass analytes can have large drops in intensity between the monoisotopic peak and the first isotopic peak).

---

Step 4: Charge State Selection

• The process is repeated for each charge state in the specified range.
• The charge state that results in the highest total envelope intensity is selected as the best match.

---

Step 5: Output

• Peaks are grouped into isotopic envelopes, and monoisotopic peaks are identified.
• The process continues until all peaks are processed or assigned to envelopes.

Installation

pip install .

Usage

from msdecon.deconvolution import deconvolute

# Example input: list of (mz, intensity) pairs
peaks = [
    (689.6649, 52.0),
    (689.93, 9.0),
    (689.9836, 71.0),
    # ...
]

results = deconvolute(
    peaks,
    tolerance=0.01,
    tolerance_type='da',
    charge_range=(1, 3)
)

for r in results:
    print(f"Monoisotopic Peak: {r.monoisotopic_peak}, Charge: {r.charge}, Total Intensity: {r.total_intensity}")

Documentation

• deconvolute(peaks, tolerance, tolerance_type, charge_range, ...)
  The primary function for isotope envelope deconvolution. Returns a list of DeconvolutedPeak objects.

• DeconvolutedPeak
  A dataclass representing the identified isotopic envelope, including monoisotopic peak, charge state, and total intensity.

• Peak / IsotopeGap
  Internal data structures representing basic MS entities.

• GraphNode / GraphEdge
  Wrappers around the peaks and isotope gap data for use in the underlying graph structure.

Dependencies

• rustworkx for efficient graph operations
• Python 3.8+ (recommended)

Streamlit app

Hosted on Streamlit Cloud (Try Me): msdecon

This repo also contains the source code for a streamlit app which can be used to visualize the deconvolution results. To run the app, use the following command:

pip install requirements.txt
streamlit run streamlit_app.py