# Isotopic Envelope Generation At Fixed Enrichment

> Use when when you have a peptide sequence, MS2 fragment charge states, and a known isotope enrichment fraction (e.g., 1.

- Skill: `holobiomicslab/isotopic-envelope-generation-at-fixed-enrichment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/isotopic-envelope-generation-at-fixed-enrichment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/isotopic-envelope-generation-at-fixed-enrichment/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/isotopic-envelope-generation-at-fixed-enrichment

---


# isotopic-envelope-generation-at-fixed-enrichment

## Summary

Calculate theoretical isotopic peak envelopes (B and Y ion series) for peptide fragments at a specified stable isotope enrichment level, enabling matching of observed MS2 fragment ions to expected isotopic distributions in SIP experiments or natural-abundance proteomics.

## When to use

When you have a peptide sequence, MS2 fragment charge states, and a known isotope enrichment fraction (e.g., 1.07% for natural 13C abundance, or 50% for a SIP-labeled sample), and need to predict the m/z and intensity pattern of B and Y fragment ions to annotate or validate observed fragment peaks in a mass spectrum.

## When NOT to use

- The peptide sequence is unknown or contains ambiguous positions; the algorithm requires an unambiguous chemical formula to compute isotopic distributions.
- Precursor mass is not reliably known or charge state is uncertain; accurate fragment m/z prediction depends on knowing the parent ion charge and mass.
- The sample enrichment fraction is not known or varies across a batch; using a single fixed enrichment assumes homogeneous labeling across all peptides.

## Inputs

- peptide sequence (character string)
- fragment charge states (integer range, e.g., 1:2)
- isotope type (character: 'C13', 'N15', 'O18', etc.)
- isotope probability or enrichment fraction (numeric: 0.0 to 1.0, e.g., 0.0107 for natural, 0.5 for 50% enrichment)
- precursor m/z (numeric, optional for filtering)
- isolation window width (numeric, e.g., 4.0 Da, optional)

## Outputs

- ExpectedBYions table with columns: fragment type (B or Y), position, charge state, theoretical m/z, intensity profile (isotopic envelope), residuePositions
- theoretical m/z and isotopic fine structure for each B and Y ion at specified enrichment

## How to apply

Use Aerith's sequential convolution algorithm to calculate theoretical isotopic envelopes for each fragment (B and Y ions) at the specified enrichment level and charge states. Provide the peptide sequence, fragment charge range (e.g., 1:2), isotope type (e.g., 'C13'), isotope probability (e.g., 0.0107 for natural abundance), and precursor m/z and isolation window width if filtering to expected precursor region. The algorithm computes the fine isotopic structure—including all monoisotopic and higher mass variants—by convolving elemental isotopic distributions. Output an ExpectedBYions table listing each fragment with its calculated m/z, intensity envelope, and optionally residue position. This theoretical table can then be used as a reference for matching experimental peaks via annotatePSM or other ion-matching workflows.

## Related tools

- **Aerith** (Executes sequential convolution algorithm to compute theoretical isotopic peak envelopes for peptide fragments; provides interfaces to specify isotope type, enrichment fraction, and fragment charge states; returns ExpectedBYions table for downstream annotation matching.) — https://github.com/xyz1396/Aerith
- **annotatePSM (Aerith function)** (Matches experimental observed fragment ions (m/z, intensity, charge from MS2 spectrum) against the theoretical B and Y ion envelopes generated by isotopic-envelope-generation; outputs matchedIndices and residuePositions indicating successful fragment assignments.) — https://github.com/xyz1396/Aerith
- **Raxport** (Converts ThermoFisher RAW files to FT2 format containing MS1 and MS2 scans with charge and m/z data; enables reading of experimental spectra that will be matched to theoretical envelopes.) — https://github.com/xyz1396/Raxport.net
- **R (language/environment)** (Runtime environment for Aerith package and data manipulation workflows.)

## Examples

```
# In R, compute theoretical B/Y envelopes for peptide at natural 13C abundance
library(Aerith)
envelopes <- getExpectedBYions(peptide='HSQVFSTAEDNQSAVTIHVLQGER', isotope='C13', enrichment=0.0107, charges=1:2, precursor_mz=1042.5)
```

## Evaluation signals

- ExpectedBYions table contains entries for all expected B and Y fragments at the specified charge states with no missing or NaN m/z values.
- Isotopic envelope intensities sum to 1.0 (or expected total) for each fragment and vary smoothly across isotopic variants consistent with binomial distribution at the specified enrichment fraction.
- Theoretical m/z values match chemical formula predictions: m/z = (mass + charge × proton_mass) / charge, with isotope mass shifts (e.g., +1.003 Da per 13C) evident in higher isotopic variants.
- When matched against observed peaks via annotatePSM, matched fragments show non-negative matchedIndices and correctly identified residuePositions; unmatched peaks have negative matchedIndices.
- Enrichment parameter correctly reflected in isotopic envelope ratios: natural abundance (0.0107) yields weak 13C satellites (~1% intensity), while 50% enrichment yields comparable monoisotopic and +1 isotopic peaks.

## Limitations

- Assumes peptide sequence is error-free and complete; isobaric amino acids (I/L) are not distinguished and contribute identical mass.
- Only MS1 and MS2 scans are supported by the underlying Raxport tool; higher-order fragmentation (MS3+) is not addressed.
- Isotope enrichment is assumed homogeneous across all amino acids in the peptide; differential labeling (e.g., selective 15N in backbone) is not modeled.
- Algorithm does not account for in-source modifications (phosphorylation, oxidation) or missed cleavages; input sequence must represent the observed molecular form.
- Performance depends on fragment charge state accuracy; if precursor charge is misidentified, fragment charge inference may propagate errors into theoretical envelope calculations.

## Evidence

- [abstract] sequential convolution algorithm for peptide fragments: "employs efficient algorithms—including sequential convolution for peptide fragments, Monte Carlo simulation for fine isotopic structures, and FFT-based methods for metabolites"
- [intro] Accept isotope enrichment parameters for SIP experiments: "Aerith supports flexible specification of isotopic abundances for stable isotope probing (SIP) experiments, allowing users to model compounds with any degree of isotopic enrichment"
- [intro] Calculate theoretical B and Y ion isotopic envelopes: "calculate the theoretical isotopic peak envelope of peptide precursors and their B Y ions"
- [other] Example parameters for natural-abundance experiment: "annotatePSM accepts observed peak data (m/z, intensity, charge), peptide sequence, fragment charge states (1:2), isotope type (C13), isotope probability (0.0107 for natural abundance)"
- [readme] Raxport extracts scans from ThermoFisher raw files: "Raxport is a simple program which extracts scans from raw files generated by mass spectrometers from ThermoFisher. It supports both Orbitrap and IonTrap scans."