Crate isospec 

Fine-structure isotopic distributions of molecules, computed by IsoSpec.

The C++ library is compiled from source by the build script (a C++20 compiler is needed); this crate is a safe API over it.

Overview

A molecule is an Iso: from a formula, a peptide sequence (with Unimod modifications), a Composition or raw isotope data. Its isotopic distribution is then computed

• whole, as an Envelope (arrays of masses and probabilities): the isotopologues above a probability threshold, the smallest set covering a given total probability, a simulated measurement, or binned on a mass grid; envelopes can be added, convolved, binned and compared (Wasserstein distances);
• or one isotopologue at a time, by a generator: ThresholdGenerator, LayeredGenerator, OrderedGenerator (strictly decreasing probability) and StochasticGenerator. Generators iterate over Peaks (for peak in generator), or step one isotopologue at a time with advance(), which also gives each one’s configuration.

use isospec::{Iso, Threshold, ThresholdGenerator};

// The smallest set of isotopologues of a peptide covering 99.9%.
let iso = Iso::from_formula("C254H377N65O75S6")?;
let mut env = iso.envelope().total_prob(0.999)?;
env.sort_by_mass();
println!("{} peaks, {:.4} Da to {:.4} Da", env.len(), env.masses()[0], env.masses()[env.len() - 1]);

// Or streamed, never stored.
let n = ThresholdGenerator::new(iso, 1e-3, Threshold::Relative)?.into_iter().count();
assert!(n > 0);

Threads

Every type can be sent to another thread. Iso, Envelope and UnimodTable can be shared: their &self methods may run concurrently. Generators are stateful and are not Sync.

Errors

Invalid input is an Error, never undefined behaviour: the C++ library’s exceptions are caught at the boundary, and the arguments the C++ cannot check itself (slice lengths) are checked before calling it. The ErrorKind names the exception class.

Modules

isa

The instruction-set level the library’s SIMD kernels run at.

Structs

Composition

Element counts: a molecular formula, or a difference between two (a modification’s delta, say), so counts may be negative.

Conf

An isotopologue’s configuration, owned. See ConfRef.

ConfRef

An isotopologue’s configuration, borrowed: for each element of the molecule, how many atoms are of each of its isotopes (in the order of the element’s isotopes, lightest first for table elements).

Element

A chemical element of IsoSpec’s built-in table, with its stable isotopes’ masses and natural abundances.

ElementSpec

One element of a molecule given by its isotopes rather than by symbol: for labelled or otherwise non-natural elements. See Iso::from_isotopes and Iso::add_element; made with ElementSpec::new.

Envelope

An isotopic distribution as arrays: a mass and a probability per peak, and optionally each peak’s isotopologue configuration.

EnvelopeBuilder

Options for computing an Envelope from an Iso: whether to keep configurations. Start one with Iso::envelope.

Error

An error from IsoSpec: its kind and the library’s message.

ExpandedComposition

A composition resolved to the flat isotope arrays IsoSpec computes on: one entry per element in isotope_numbers and atom_counts, and one per isotope, element after element, in masses and probabilities.

Iso

A molecule, as IsoSpec computes on it: for each element, its atom count and its isotopes’ masses and abundances.

Isotope

One isotope of an Element.

LayeredGenerator

Isotopologues in layers of decreasing probability: each layer’s are less probable than the previous layer’s, in no particular order within a layer. Runs through the whole distribution if not stopped; stop once enough probability is covered.

LayeredOptions

Options of a LayeredGenerator: start from default and change what you need.

Match

The result of Envelope::wasserstein_match.

OrderedGenerator

Isotopologues in strictly decreasing order of probability. Slower than the others (a priority queue); use it when the order itself matters.

Peak

One isotopologue as a generator reports it.

Peaks

The isotopologues of a generator, as an iterator: see the generators’ IntoIterator. Peaks come from the library 256 at a time.

PeptideOptions

How a peptide sequence is read: see Composition::from_peptide and Iso::from_peptide. Start from default and change what you need.

StochasticGenerator

A simulated measurement: molecules molecules sampled from the distribution, reported as the isotopologues that received any, each with its count in Peak::prob.

StochasticOptions

Options of stochastic sampling: StochasticGenerator and Envelope::stochastic. Start from default and change what you need.

ThresholdGenerator

Every isotopologue with probability above a threshold, in no particular order. The fastest generator.

ThresholdOptions

Options of a ThresholdGenerator: start from default and change what you need, so that options added later leave your code compiling.

UnimodEntry

One entry of a UnimodTable.

UnimodTable

A table of Unimod modifications: id → name, monoisotopic mass delta and composition delta. Used to resolve [UNIMOD:<id>] in peptide sequences.

Enums

ErrorKind

What went wrong, by the C++ exception class the library threw (or, for arguments the Rust side rejects before calling in, the class it would have thrown).

Masses

Which isotope masses a molecule is built with.

Threshold

Whether a probability threshold is absolute or relative to the most probable isotopologue.

Constants

LIBRARY_VERSION

The version of the bundled IsoSpec C++ library.

Functions

simd_level

What the SIMD kernels run as on this machine: see isa::simd_level.

Type Aliases

Result

Result with this crate’s Error.