IsoGen

IsoGen is a toolbox for predicting isotope distributions from protein, RNA, DNA, neutral-mass, and elemental-formula inputs.

It includes absolute FFT and BRAIN calculations plus a neural network prediction.

Pretrained models are included for both peptides and RNA based on either average mass or sequence. DNA prediction uses the RNA model due to the similarity of their elemental compositions.

The FFT methods are absolute and are limited only by the accuracy of the data you put in. They are a little faster, especially on larger species.

The BRAIN method is an absolute calculation based on a polynomial recurrence. It provides an alternative to FFT for peptide, RNA, and DNA sequence or neutral-mass inputs.

The NN methods are very accurate and can be faster on smaller species. The primary advantage of these is that they can be retrained on non-standard isotope distributions.

License

IsoGen is released under the BSD 3-Clause License. See LICENSE for details.

Additional license information is available in THIRD_PARTY_NOTICES.md for FFTW and Intel compiler runtime libraries.

PLEASE CITE THIS SOFTWARE IN ANY PUBLICATIONS THAT USE IT AND RELEVANT BACKGROUND LITERATURE BELOW. Machine-readable citation metadata is available in CITATION.cff.

IsoGen is currently in preprint, please cite:

Pavek, J.G.; Grimes, J.; Frey, B.L.; Welham, N.V.; Smith, L.M.; Marty, M.T. "Neural Network Prediction of Isotopic Distributions" ChemRxiv 2026, doi:10.26434/chemrxiv.15006709/v1

The FFT method is derived from the following citation:

Rockwood, A.L.; Palmblad, M. Isotopic Distributions. In Mass Spectrometry Data Analysis in Proteomics, Matthiesen, R. Ed.; Humana Press, 2013; pp 65–99.

The BRAIN method is derived from these citations:

Dittwald, P.; Claesen, J.; Burzykowski, T.; Valkenborg, D.; Gambin, A. "BRAIN: A Universal Tool for High-Throughput Calculations of the Isotopic Distribution for Mass Spectrometry" Analytical Chemistry 2013, 85, 1991–1994

Dittwald, P.; Valkenborg, D. "BRAIN 2.0: Time and Memory Complexity Improvements in the Algorithm for Calculating the Isotope Distribution" Journal of the American Society for Mass Spectrometry 2014, 25, 588–594

Contact

If you have any questions, please email mtmarty@utexas.edu or open a ticket on GitHub.

Installation

Install a published wheel from PyPI:

python -m pip install pyisogen

IsoGen requires Python 3.10 or newer. The native library is loaded through ctypes and does not depend on a particular CPython minor-version ABI.

Published platform wheels include a native library built from the bundled C sources for Windows x64 and ARM64, Linux x86_64 and ARM64, and macOS (Intel and Apple Silicon). The wheels include the required FFTW 3 runtime, so a compiler, CMake, and a separate FFTW installation are not needed when a compatible wheel is available.

If pip cannot find a compatible wheel, it falls back to the source distribution and automatically builds the native library with CMake. A source build requires a C/C++ compiler, CMake 3.22.1 or newer, and the FFTW 3 development libraries. Installation stops with a native-build error when those prerequisites are unavailable.

Usage

From Python:

import isogen

protein = isogen.isodist("ACDEFGHIK", type="PEPTIDE", isolen=64)
protein_brain = isogen.isodist(
    "ACDEFGHIK", type="PEPTIDE", isolen=64, method="BRAIN"
)
rna = isogen.isodist("AUGCAGUACGUA", type="RNA", isolen=64)
dna = isogen.isodist("ATGCAGTACGTA", type="DNA", isolen=64)
glucose_mass_dist = isogen.isodist("C6H12O6", type="ATOM", isolen=32)
modified = isogen.isodist("M[Oxidation]")
legacy = isogen.isodist("M[Oxidation]", use_modifications=False)
labeled = isogen.isodist("K[UNIMOD:259]")

The output is a numpy array of shape (isolen, 2) with the first column containing the monoisotopic mass and the second column containing the relative intensity. The isolen parameter controls the number of isotopic peaks returned. To return an m/z axis, pass a charge of one or greater. The default positive polarity uses (M + zH) / z; pass polarity="negative" for (M - zH) / z:

protein_mz = isogen.isodist(
    "ACDEFGHIK", type="PEPTIDE", isolen=64, charge=2
)

IsoGen provides FFT, BRAIN, and neural-network methods for peptides and RNA. The default is the exact FFT calculation. BRAIN selects the polynomial recurrence calculation, while NN uses the neural-network model to predict the distribution from a peptide or RNA sequence or neutral mass.

The PEPTIDE model is trained on peptide sequences, while the RNA model is trained on RNA sequences. The DNA type uses the RNA model, and

The public ATOM type uses the FFT method; no neural-network formula model is available.

ProForma modification composition is included in peptide envelopes by default. Set use_modifications=False to calculate the legacy unmodified envelope while retaining known mass shifts. Unsupported or mass-only annotations print warnings to standard error and are ignored individually for intensities. Fixed isotope labels are supported; bundled NN models and BRAIN compositions outside CHNOS/P warn and use FFT when needed. Custom residue-count models warn and ignore modifications in intensities. The CLI opt-out is --ignore-modifications.

Custom neural-network models

Use isodist_custom to generate a distribution from a binary model file rather than one of IsoGen's bundled neural-network models:

from pathlib import Path

import isogen

model_file = Path("models/my_peptide_model_64.bin")
custom = isogen.isodist_custom(
    "ACDEFGHIK",
    model_file=model_file,
    isolen=64,
    type="PEPTIDE",
)

The function accepts peptide, RNA, and DNA sequences or numeric neutral masses. It always uses the neural-network method. The model must have the correct input size for the selected input and type, and its output size must equal isolen. Peptide sequence models have 20 inputs, RNA/DNA sequence models have 4 inputs, and neutral-mass models have 5 inputs. Invalid, unreadable, or incompatible model files raise ValueError. As with isodist, the result has shape (isolen, 2), containing neutral masses and relative intensities. It also accepts the charge and polarity keywords to return the same charge-adjusted m/z axes as isodist.

Training custom models

Install the training dependencies before importing the training modules:

python -m pip install -e ".[training]"

Training data is stored in NumPy .npz archives. Sequence models expect a seqs array and mass models expect a masses array. Every archive also needs a dists array with shape (number_of_examples, isolen). Each row of dists is the target relative-intensity distribution for its corresponding sequence or neutral mass. For example:

import numpy as np

np.savez_compressed(
    "peptide_training.npz",
    seqs=np.asarray(["ACDE", "PEPTIDE", "MARTY"]),
    dists=np.asarray(peptide_target_distributions, dtype=np.float32),
)

np.savez_compressed(
    "mass_training.npz",
    masses=np.asarray([1_000.0, 5_000.0, 10_000.0]),
    dists=np.asarray(mass_target_distributions, dtype=np.float32),
)

Use the engine matching the kind of input the model will receive. The helper below directs generated models to a separate directory instead of overwriting the models installed with IsoGen:

from pathlib import Path

from isogen.isogenmass import IsoGenMassEngine
from isogen.isogenpep import IsoGenPepEngine
from isogen.isogenrna import IsoGenRNAEngine
from isogen.isogenrna_averagine import IsoGenRNAveragineEngine


model_dir = Path("trained_models")
model_dir.mkdir(exist_ok=True)


def set_model_directory(engine):
    """Set the output directory before a model is initialized or loaded."""
    engine.model.working_dir = str(model_dir)
    for model in engine.models:
        model.working_dir = str(model_dir)


# Peptide sequences: 20-element amino-acid composition input.
pep = IsoGenPepEngine(isolen=64)
set_model_directory(pep)
pep.train("peptide_training.npz", epochs=20, forcenew=True)

# RNA sequences: 4-element A/C/G/U composition input. This model is also
# used for DNA inference after IsoGen converts thymine to uracil.
rna = IsoGenRNAEngine(isolen=64)
set_model_directory(rna)
rna.train("rna_training.npz", epochs=20, forcenew=True)

# Peptide-like neutral masses: 5-element mass encoding.
mass = IsoGenMassEngine(isolen=64)
set_model_directory(mass)
mass.train_multiple(
    ["mass_training.npz"],
    inputname="masses",
    epochs=20,
    forcenew=True,
)

# RNA-like neutral masses: 5-element mass encoding.
rna_mass = IsoGenRNAveragineEngine(isolen=64)
set_model_directory(rna_mass)
rna_mass.train_multiple(
    ["rna_mass_training.npz"],
    inputname="masses",
    epochs=20,
    forcenew=True,
)

IsoGenPepEngine supports output lengths 16, 64, and 128; IsoGenRNAEngine supports 64 and 128; IsoGenMassEngine models intended for isodist_custom support 8, 32, 64, and 128; and IsoGenRNAveragineEngine supports 32, 64, and 128. The output length used to construct the engine must match the width of dists and the isolen passed to isodist_custom.

After training, each engine saves a PyTorch .pth checkpoint and a raw .bin model in trained_models. The .pth file is used to resume Python training; pass the .bin file to isodist_custom. The generated filenames are isogenpep_model_<isolen>.bin, isogenrna_model_<isolen>.bin, isogenmass_model_<isolen>.bin, and isogen_rnaveragine_model<isolen>.bin, respectively:

custom = isogen.isodist_custom(
    "ACDEFGHIK",
    model_file=model_dir / "isogenpep_model_64.bin",
    isolen=64,
    type="PEPTIDE",
)

Passing forcenew=True starts from newly initialized weights. Use forcenew=False to resume from a matching .pth checkpoint in the configured model directory. IsoGenMassEngine.train(...) and IsoGenRNAveragineEngine.train(...) can also generate standard FFT targets from random masses when a custom target archive is not needed.

Peptide ions and RNA termini

To calculate all selected peptide fragment envelopes in one call, use calc_pep_fragment_isodists:

batch = isogen.calc_pep_fragment_isodists(
    "S[Acetylation]HHS", fragmentation_type="ETD", isolen=128
)
for label, mass, intensities in zip(batch.labels, batch.masses, batch.intensities):
    print(label, mass, intensities)

The batch uses fragment-specific C/H/N/O/S compositions, including supported terminal ions and modifications with known formulas. A mass-only modification or ambiguous composition raises ValueError. Intensities are normalized to the most intense isotope; masses are neutral monoisotopic origins.

For peptide fragments, pass the fragment sequence and select its neutral terminal composition with ion_type. IsoGen supports intact H2O (the default) and the peptide a, b, c, x, y, and z ion types:

b6 = isogen.isodist("PEPTID", type="PEPTIDE", ion_type="b")
y6 = isogen.isodist("EPTIDE", type="PEPTIDE", ion_type="y")

Supply the N-terminal subsequence for a/b/c ions and the C-terminal subsequence for x/y/z ions. Returned values are neutral masses, not charge-adjusted m/z.

RNA does not currently accept named RNA fragment-ion series through ion_type. For an intact or manually truncated RNA sequence, configure the supported terminal chemistry with threeend and fiveend:

rna_5_triphosphate = isogen.isodist(
    "AUGC",
    type="RNA",
    threeend="OH",
    fiveend="TP",
)

The available 5' settings are hydroxyl (OH), monophosphate (MP, default), and triphosphate (TP); the supported explicit 3' setting is hydroxyl (OH, default). These peptide-ion and RNA-terminal options adjust the mass-axis origin. The sequence-model intensity vector retains its standard terminal composition.

Modified proteins

Protein mass axes accept supported ProForma annotations using UniMod, PSI-MOD, RESID, explicit mass shifts, formulas, and terminal or global fixed modifications:

oxidized = isogen.isodist("EM[Oxidation]E", type="PEPTIDE", isolen=64)
psi_mod_mass = isogen.calc_pep_monoisotopic_mass(
    "EM[MOD:00719]E"
)
fixed_cysteine_mass = isogen.calc_pep_monoisotopic_mass(
    "<[Carbamidomethyl]@C>ACDC"
)

J, O, and U have defined masses; B and Z use the midpoint of their two possible residues. X requires an explicit known mass gap such as X[+367.0537]. Resolved modification compositions also change the isotope envelope. Mass-only or unsupported annotations keep their mass-axis behavior but are ignored for intensities with a warning on standard error. Set use_modifications=False to use the legacy unmodified envelope. See the mass-calculation documentation for the supported subset and current limitations.

From the command line:

isogen dist ACDEFGHIK --type PEPTIDE --isolen 64
isogen dist C6H12O6 --type ATOM --isolen 32
isogen plot

See python -m isogen --help for all options.

The source repository also builds a native development executable named isogen_test.exe on Windows (isogen_test on Linux). It can be run from the repository's bin directory with isogen_test.exe -mass 10000, but it is not installed by the Python wheel. Use the isogen console command for installed packages.

Documentation

Read the full IsoGen documentation. The documentation sources are also available in the repository's docs directory. To preview them locally:

python -m pip install -e ".[docs]"
python -m mkdocs serve

Tests

The test suite uses Pyteomics as an independent mass reference. Pyteomics is only part of the optional test dependencies and is not installed with IsoGen:

python -m pip install -e ".[test]"
python -m pytest

The Windows release workflow builds the x64 native wheel with both MSVC and the Intel oneAPI compiler. Both wheels run the complete unit test suite on a clean Windows runner, after which representative FFT, NN, and BRAIN workloads are compared for numerical agreement and performance. The Intel wheel is the x64 release artifact; the MSVC wheel and JSON benchmark results are kept as workflow artifacts for comparison. The ARM64 release wheel is built with MSVC and tested on a native Windows ARM64 runner.

Development and model-training modules have additional dependencies:

python -m pip install -e ".[training]"

Future Ideas

Add XL-MOD/GNO support for modified-protein composition-aware isotope distributions.

Consider a configurable limit for combinatorial ambiguous-fragment variants, probability-weighted fragment masses from ProForma localization scores, and support for fragment charge states, neutral losses, and labile diagnostic ions.

Explore reverse models to infer something about the sequence or input type from the isotope distribution. Perhaps explore the bounds of what a reasonable peptide sequence may be.

CHANGELOG

1.1.3

Added ability to calculate peptide fragment isotope distributions with calc_pep_fragment_isodists. This function accepts a peptide sequence and returns the neutral monoisotopic masses and relative intensities for all selected fragment ions in one call. It supports ProForma modifications, known terminal ions, and neutral H2O loss.

Integrated terminal ion support and proforma modifications into the isodist function for peptide fragments. The ion_type parameter allows selection of intact H2O (default) and peptide a, b, c, x, y, and z ions. ProForma modifications are supported in the fragment sequence.

1.1.2

Added native Windows and Linux ARM64 wheels to the release workflow.

1.1.1

calc_pep_fragments now accepts ProForma sequences. Ambiguous fragments are omitted by default or returned with numbered keys such as b2#1 and b2#2 using ambiguous_rule="both".

Added z' aliases and fragmentation-method presets for CID, HCD, SID, IRMPD, ETD, ECD, EThcD, BYCZ*, UVPD, UVPD4, UVPD6, and UVPD9 fragment ladders.

1.1.0

Added ProForma modified-protein mass support for UniMod, PSI-MOD, RESID, and ambiguous or unusual amino acids.

1.0.11

Added calc_pep_fragments to mass.py to allow for peptide fragment mass calculations. This isn't directly related to isotope distributions, but it is useful for other proteomics applications.

1.0.10

Added charge and polarity as parameters that can be passed to isodist and isodist to calculate m/z rather than mass as the axis.

Added a script for testing different model dimensions and encoding types.

1.0.9

Fixed FFT RNA length calculation, which speeds up smaller RNA calculations with FFT.

Also, improved install cmake to default to bin directory.

Added timing_test_rna.py for RNA timing tests.

Added bin files for windows builds.

1.0.8

Updated to add ARM64 to build and address FFTW potential issues.

1.0.7

Updated Windows build to Intel compiler to improve speed.

1.0.6

Minor changes to improve versioning and build structure.

1.0.5

Updated citation info.

Reformatted build to pull version from _version.py file.

1.0.4

Moved native-library packaging to scikit-build-core so Windows, Linux, and macOS wheels compile the bundled C sources automatically with CMake.

Added native macOS wheels for Intel and Apple Silicon, including bundled FFTW runtime dependencies.

Expanded Python compatibility from Python 3.13-only to Python 3.10 and newer.

Added automatic native compilation when pip falls back to the source distribution, with clearer errors for missing build prerequisites or runtime libraries.

1.0.3

Added the BRAIN polynomial-recurrence isotope calculation for peptide, RNA, and DNA sequence and neutral-mass inputs.

Added method="BRAIN" to the Python API and command-line interface.

Dramatically improved BRAIN performance by about double using some computational tricks the AI found.

Added side-by-side FFT, NN, and BRAIN protein-sequence example plots.

Added runtime-dispatched AVX2/FMA neural-network acceleration on supported x86 processors, with a portable scalar fallback.

Improved native normalization and large-input regression coverage.

Added a timing test script for internal use.

1.0.2

Added support for custom models with isogen_custom function and new C bindings for custom models.

1.0.1

Small updates to README.md

1.0.0

Initial release. Rewrote significantly from UniDec build using AI tool to improve the release and add in atomic formula support.