IsoSpecPy 2.5.0__py3-none-win32.whl

IsoSpecPy/IsoSpecPy.py

@@ -0,0 +1,1088 @@
+# -*- coding: utf-8 -*-
+#
+#   Copyright (C) 2015-2020 Mateusz Łącki and Michał Startek.
+#
+#   This file is part of IsoSpec.
+#
+#   IsoSpec is free software: you can redistribute it and/or modify
+#   it under the terms of the Simplified ("2-clause") BSD licence.
+#
+#   IsoSpec is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+#   You should have received a copy of the Simplified BSD Licence
+#   along with IsoSpec.  If not, see <https://opensource.org/licenses/BSD-2-Clause>.
+#
+
+from .isoFFI import isoFFI
+import re
+import types
+from . import PeriodicTbl
+from .confs_passthrough import ConfsPassthrough
+from collections import namedtuple, OrderedDict
+import math
+
+regex_pattern = re.compile('([A-Z][a-z]?)(-?[0-9]*)')
+ParsedFormula = namedtuple('ParsedFormula', 'atomCounts masses probs elems')
+
+
+
+
+def ParseFormula(formula):
+    """Parse a chemical formula.
+
+    Args:
+        formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O"
+
+    Returns:
+        A tuple containing element symbols and atomCounts of elements in the parsed formula.
+    """
+    global regex_pattern
+
+    ret = OrderedDict()
+
+    last = 0
+    for match in re.finditer(regex_pattern, formula):
+        elem, cnt = match.groups()
+        if elem in ret:
+            raise ValueError("""Invalid formula: {} (repeating element: "{}")""".format(formula, elem))
+        ret[elem] = int(cnt) if cnt != '' else 1
+        if last!=match.start():
+            raise ValueError("""Invalid formula: {}  (garbage inside: "{}")""".format(formula, formula[last:match.start()]))
+        if elem not in PeriodicTbl.symbol_to_masses:
+            raise ValueError("""Invalid formula: {} (unknown element symbol: "{}")""".format(formula, elem))
+        last = match.end()
+
+    if len(formula) != last:
+        raise ValueError('''Invalid formula: {}  (trailing garbage: "{}")'''.format(formula, formula[last:]))
+
+    if len(ret) == 0:
+        raise ValueError("Invalid formula (empty)")
+
+    return ret
+
+def ParsePeptideSequence(sequence, unimod_db_path=None):
+    """Parse a peptide sequence, recognizing SAGE-style [UNIMOD:<id>]
+    modification brackets: `[UNIMOD:<id>]-SEQUENCE` for an N-terminal mod,
+    `X[UNIMOD:<id>]` for an internal one (immediately after the modified
+    residue), `SEQUENCE-[UNIMOD:<id>]` for a C-terminal one -- exactly the
+    notation/placement this monorepo's SAGE fork writes
+    (crates/sage/src/peptide.rs). Everything parse_fasta_c already tolerated
+    (spacers, whitespace, indeterminate-formula codes) is still silently
+    ignored; only '[' is now meaningful, and must open a well-formed bracket.
+
+    Despite this function's name being the honest one -- unlike ParseFASTA
+    below (kept only for backward compatibility), this has never parsed an
+    actual FASTA file (no '>' header, no multi-record support); it has only
+    ever accepted a bare peptide sequence string. Co-author Michał Startek
+    has completely no idea how things are supposed to be called; see
+    docs/ai/unimod.md.
+
+    Args:
+        sequence (str): a peptide sequence, optionally annotated with
+            [UNIMOD:<id>] modification brackets.
+        unimod_db_path (str, optional): path to an override Unimod
+            composition-delta table (same CSV shape as data/unimod.csv).
+            None (default) uses the table embedded at compile time.
+
+    Returns:
+        An OrderedDict of element symbol -> atom count, e.g. {"C": 42, "H":
+        66, "N": 10, "O": 17, "S": 2} for a Carbamidomethyl-modified
+        sequence -- general over whatever elements the sequence's
+        modifications touch (not just CHNOSSe, unlike the plain
+        amino-acid-only path this supersedes).
+
+        Two properties of that dict are worth knowing before you rely on
+        them. Only elements with a non-zero net count appear: a sequence with
+        no sulphur has no "S" key at all, rather than "S": 0. And key order
+        differs between the two internal paths -- a bracket-free sequence
+        comes back in CHNOSSe order, one carrying a [UNIMOD:<id>] bracket in
+        element-table (atomic number) order, since the general path
+        accumulates over the whole periodic table. Treat the result as a
+        mapping, not as a sequence of pairs in a promised order.
+
+        Like parse_fasta_c before it, this returns the *residue* composition:
+        the terminal H2O of a free peptide is NOT included, so the masses of
+        an Iso built from it are 18.0106 Da lighter than the neutral peptide.
+        Add water explicitly if you want the real molecule -- e.g.
+        IsoSpecPy.IsoTotalProb(0.99, peptide_sequence=seq, formula="H2O1").
+        (The C++ Iso::FromFASTAWithMods takes an add_water argument and
+        defaults it to True, so the two differ by a water unless you say so.)
+
+        Counts are signed: a modification whose delta removes more atoms of
+        an element than the bare sequence provides gives a negative count
+        (ParsePeptideSequence("G[UNIMOD:11]") -> H: -1, S: -1). That is
+        rejected later, when a composition is turned into an Iso, not here.
+
+    Raises:
+        ValueError: the sequence contains a malformed [UNIMOD:<id>] bracket,
+            or references an id not present in the active table (covers both
+            a genuinely unknown id and one this fork's shipped table
+            deliberately excludes -- isotope-labeled or glycan/
+            derivatization "brick" modifications, see docs/ai/unimod.md --
+            alike; both are simply not resolvable to an atom-count delta).
+    """
+    if isinstance(sequence, str):
+        sequence = sequence.encode("ascii")
+    db_path = isoFFI.ffi.NULL if unimod_db_path is None else str(unimod_db_path).encode("ascii")
+
+    composition = isoFFI.clib.parseFastaWithModsC(sequence, db_path)
+    if composition == isoFFI.ffi.NULL:
+        raise ValueError(
+            "Invalid peptide sequence or unresolvable [UNIMOD:<id>] reference: {}".format(sequence)
+        )
+    try:
+        size = isoFFI.clib.compositionSizeC(composition)
+        symbols = isoFFI.clib.compositionSymbolsC(composition)
+        counts = isoFFI.clib.compositionCountsC(composition)
+        od = OrderedDict()
+        for i in range(size):
+            symbol = isoFFI.ffi.string(symbols[i]).decode("ascii")
+            od[symbol] = counts[i]
+        return od
+    finally:
+        isoFFI.clib.deleteCompositionC(composition)
+
+
+def ParseFASTA(fasta, unimod_db_path=None):
+    """Compatibility alias for ParsePeptideSequence -- see its docstring for
+    the naming note. Prior to this version, this function ignored '[',
+    digits, and ':' in its input entirely, silently mis-parsing any
+    UNIMOD-bracket-containing string as extra phantom amino acids (every
+    letter in "UNIMOD" happens to be a valid 1-letter amino-acid code); that
+    was a bug, not a feature, and is now fixed by routing through the same
+    mods-aware parser as ParsePeptideSequence.
+
+    A bracket-free sequence yields the same counts, in the same CHNOSSe
+    order, as it always did -- with one difference: elements whose count is
+    zero are no longer emitted. This function used to return "C", "H", "N",
+    "O" and "S" keys unconditionally (plus "Se" when non-zero), so
+    ParseFASTA("A")["S"] was 0 and is now a KeyError. Use .get(sym, 0).
+    """
+    return ParsePeptideSequence(fasta, unimod_db_path=unimod_db_path)
+
+
+# (symbol, use_nominal_masses) -> (masses, probs), each a tuple over that
+# element's isotopes. Filled lazily from expandCompositionC, so every value in
+# here is what the C++ tables said -- this is a memo of the C++ resolution, not
+# a second copy of it. Without it, every IsoParamsFromDict call paid for the
+# cffi round trip (per-symbol ffi.new, the accessor calls, three ffi.unpack):
+# 24.7us per call for a 5-element formula against 3.3us for the plain dict
+# lookups it replaced, of which the C++ expansion itself is only 2.6us.
+# Unknown symbols raise and are never stored, so they fail on every call.
+_isotopes_by_symbol = {}
+
+
+def _resolve_symbol(symbol, use_nominal_masses):
+    ffi = isoFFI.ffi
+    try:
+        symbol_buf = ffi.new("char[]", symbol.encode("ascii"))
+    except (UnicodeEncodeError, AttributeError):
+        raise ValueError("Invalid formula (element symbols must be ASCII strings)")
+    # The "char[]" belongs to cffi and must outlive the call: the "char*[]"
+    # holds a borrowed pointer into it.
+    symbol_ptrs = ffi.new("char*[]", [symbol_buf])
+    # The count is irrelevant to the isotopes: expand_composition_into copies
+    # it through untouched.
+    count_buf = ffi.new("int[]", [1])
+
+    expanded = isoFFI.clib.expandCompositionC(symbol_ptrs, count_buf, 1, use_nominal_masses)
+    if expanded == ffi.NULL:
+        raise ValueError("Invalid formula")
+    try:
+        # ffi.unpack, not ffi.cast("double[N]", ...): N varies with the
+        # element and cffi's type cache is keyed on the exact type string, so
+        # embedding a runtime size in one defeats that cache on every call.
+        n = isoFFI.clib.expandedIsotopeNumbersC(expanded)[0]
+        masses = tuple(ffi.unpack(isoFFI.clib.expandedIsotopeMassesC(expanded), n))
+        probs = tuple(ffi.unpack(isoFFI.clib.expandedIsotopeProbabilitiesC(expanded), n))
+    finally:
+        isoFFI.clib.deleteExpandedCompositionC(expanded)
+
+    return masses, probs
+
+
+def IsoParamsFromDict(formula, use_nominal_masses = False):
+    """Produces a set of IsoSpec parameters from a chemical formula.
+
+    The symbol-to-isotopes resolution happens in C++ (cwrapper.h's
+    expandCompositionC -> composition.h's expand_composition_into), not here.
+    This function used to walk PeriodicTbl's dicts itself, which made it a
+    second implementation of a rule the C++ core already owned -- and it
+    existed only because the C ABI had no entry point between setupIso (which
+    demands the caller already know every isotope mass) and the
+    sequence-only isoFromFasta. It has one now. Each symbol is resolved
+    through it once and memoized (_isotopes_by_symbol).
+
+    Args:
+        formula (dict): a parsed chemical formula, e.g. {"C": 2, "H": 6, "O": 1}
+        use_nominal_masses (boolean): use masses of elements rounded to integer numbers (nominal masses)
+
+    Returns:
+        ParsedFormula: a tuple containing atomCounts, masses and marginal probabilities of elements in the parsed formula.
+        Element order follows the dict's own iteration order, as it always did.
+
+    Raises:
+        ValueError: an element symbol the library's tables don't know.
+    """
+
+    use_nominal_masses = bool(use_nominal_masses)
+    symbols, atomCounts, masses, probs = [], [], [], []
+    for symbol, atomCount in formula.items():
+        key = (symbol, use_nominal_masses)
+        resolved = _isotopes_by_symbol.get(key)
+        if resolved is None:
+            resolved = _resolve_symbol(symbol, use_nominal_masses)
+            _isotopes_by_symbol[key] = resolved
+        symbols.append(symbol)
+        atomCounts.append(atomCount)
+        masses.append(resolved[0])
+        probs.append(resolved[1])
+
+    return ParsedFormula(atomCounts, masses, probs, symbols)
+
+
+def IsoParamsFromFormula(formula, use_nominal_masses = False):
+    """Produces a set of IsoSpec parameters from a chemical formula.
+
+    Args:
+        formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O"
+        use_nominal_masses (boolean): use masses of elements rounded to integer numbers (nominal masses)
+
+    Returns:
+        ParsedFormula: a tuple containing atomCounts, masses and marginal probabilities of elements in the parsed formula.
+    """
+    parsed = ParseFormula(formula)
+    return IsoParamsFromDict(parsed, use_nominal_masses = use_nominal_masses)
+
+
+class Iso(object):
+    """Virtual class representing an isotopic distribution."""
+    def __init__(self, formula="",
+                 get_confs=False,
+                 atomCounts=None,
+                 isotopeMasses=None,
+                 isotopeProbabilities=None,
+                 use_nominal_masses = False,
+                 fasta = "",
+                 charge = 1.0,
+                 # New arguments go after charge, never between fasta and it:
+                 # this signature's positional order is public, and inserting
+                 # here would silently shift charge for anyone passing it
+                 # positionally.
+                 peptide_sequence = "",
+                 unimod_db_path = None):
+        """Initialize Iso.
+
+        Args:
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            get_confs (boolean): should we report counts of isotopologues?
+            atomCounts (list): a list of atom counts (alternative to 'formula').
+            isotopeMasses (list): a list of lists of masses of elements with counts in 'atomCounts'.
+            isotopeProbabilities (list): a list of lists of probabilities of elements with counts in 'atomCounts'.
+            use_nominal_masses (boolean): should the masses be rounded to the closest integer values.
+            fasta (str): a peptide sequence, optionally with [UNIMOD:<id>] modification
+                brackets -- see ParsePeptideSequence's docstring (this is the same argument
+                as peptide_sequence, kept under its original name for backward compatibility;
+                despite the name, this has never accepted an actual FASTA file).
+            charge (float): charge state of the molecule: all masses will be divided by this value to obtain the m/z values.
+            peptide_sequence (str): the honestly-named alias of 'fasta' -- pass one or the
+                other, not both.
+            unimod_db_path (str, optional): override Unimod composition-delta table for
+                resolving [UNIMOD:<id>] references in 'fasta'/'peptide_sequence' (same CSV
+                shape as data/unimod.csv). None (default) uses the compile-time embedded table.
+
+        Note that neither 'fasta' nor 'peptide_sequence' adds the terminal H2O of a free
+        peptide -- see ParsePeptideSequence's docstring. Pass formula="H2O1" alongside the
+        sequence for the neutral molecule's masses.
+        """
+
+        self.iso = None
+
+        if len(fasta) > 0 and len(peptide_sequence) > 0:
+            raise ValueError(
+                "'fasta' and 'peptide_sequence' are the same argument under two names -- pass only one"
+            )
+        sequence = peptide_sequence if len(peptide_sequence) > 0 else fasta
+
+        if len(sequence) > 0:
+            molecule = ParsePeptideSequence(sequence, unimod_db_path=unimod_db_path)
+        else:
+            molecule = OrderedDict()
+
+        if len(formula) > 0:
+            if isinstance(formula, dict):
+                df = formula
+            else:
+                df = ParseFormula(formula)
+            for symbol, count in df.items():
+                molecule[symbol] = molecule.get(symbol, 0) + count
+
+        for sym, cnt in molecule.items():
+            if cnt < 0:
+                raise Exception("Negative count of element " + sym + ": " + str(cnt))
+
+        if len(molecule) == 0 and not all([atomCounts, isotopeMasses, isotopeProbabilities]):
+            raise Exception("Either formula, fasta or ALL of: atomCounts, isotopeMasses, isotopeProbabilities must not be None")
+
+        if len(molecule) > 0:
+            self.atomCounts, self.isotopeMasses, self.isotopeProbabilities, _ = IsoParamsFromDict(molecule, use_nominal_masses = use_nominal_masses)
+        else:
+            self.atomCounts, self.isotopeMasses, self.isotopeProbabilities = [], [], []
+
+        if not (atomCounts is None):
+            self.atomCounts.extend(atomCounts)
+
+        if not (isotopeMasses is None):
+            self.isotopeMasses.extend(isotopeMasses)
+
+        if not (isotopeProbabilities is None):
+            self.isotopeProbabilities.extend(isotopeProbabilities)
+
+        for sublist in self.isotopeProbabilities:
+            for prob in sublist:
+                if not (0.0 < prob <= 1.0):
+                    raise ValueError("All isotope probabilities p must fulfill: 0.0 < p <= 1.0")
+
+        self.isotopeNumbers = tuple(map(len, self.isotopeMasses))
+        if self.isotopeNumbers != tuple(map(len, self.isotopeProbabilities)):
+            raise ValueError("isotopeMasses and isotopeProbabilities must have the same number of isotopes per element")
+        if len(self.atomCounts) != len(self.isotopeNumbers) or len(self.isotopeNumbers) != len(self.isotopeProbabilities):
+            raise ValueError("atomCounts, isotopeMasses, and isotopeProbabilities must all have the same length")
+
+        self.dimNumber = len(self.isotopeNumbers)
+
+        self.get_confs = get_confs
+        self.ffi = isoFFI.clib
+
+        offsets = []
+
+        i = 0
+        for j in range(self.dimNumber):
+            newl = []
+            for k in range(self.isotopeNumbers[j]):
+                newl.append(i)
+                i += 1
+            offsets.append(tuple(newl))
+        self.offsets = tuple(offsets)
+
+        # "int[]" (open array) + a separate count keeps this call to a single,
+        # fixed type string cached after its first use, instead of parsing a
+        # fresh "int[N]" through cffi's C parser on every single Iso() built
+        # -- N here varies with the formula and cffi's type cache is keyed on
+        # the exact string, so embedding N in it defeats that cache entirely.
+        self.conf_space = isoFFI.ffi.new("int[]", sum(self.isotopeNumbers))
+
+        self.iso = self.ffi.setupIso(self.dimNumber, self.isotopeNumbers,
+                                     self.atomCounts,
+                                     [i/charge for s in self.isotopeMasses for i in s],
+                                     [i for s in self.isotopeProbabilities for i in s])
+
+    def __del__(self):
+        try:
+            if self.iso is not None:
+                self.ffi.deleteIso(self.iso)
+                self.iso = None
+        except AttributeError:
+            pass
+
+    def getLightestPeakMass(self):
+        """Get the lightest peak in the isotopic distribution."""
+        return self.ffi.getLightestPeakMassIso(self.iso)
+
+    def getLightestPeakLProb(self):
+        """Get the log probability of the lightest peak in the isotopic distribution."""
+        return self.ffi.getLightestPeakLProbIso(self.iso)
+
+    def getLightestPeakConf(self):
+        """Get the isotopic configuration of the lightest peak in the isotopic distribution."""
+        self.ffi.getLightestPeakSignature(self.iso, self.conf_space)
+        return self.parse_conf(self.conf_space)
+
+    def getHeaviestPeakMass(self):
+        """Get the heaviest peak in the isotopic distribution."""
+        return self.ffi.getHeaviestPeakMassIso(self.iso)
+
+    def getHeaviestPeakLProb(self):
+        """Get the log probability of the heaviest peak in the isotopic distribution."""
+        return self.ffi.getHeaviestPeakLProbIso(self.iso)
+
+    def getHeaviestPeakConf(self):
+        """Get the isotopic configuration of the heaviest peak in the isotopic distribution."""
+        self.ffi.getHeaviestPeakSignature(self.iso, self.conf_space)
+        return self.parse_conf(self.conf_space)
+
+    def getMonoisotopicPeakMass(self):
+        """Get the monoisotopic mass of the peak."""
+        return self.ffi.getMonoisotopicPeakMassIso(self.iso)
+
+    def getMonoisotopicPeakLProb(self):
+        """Get the log probability of the monoisotopic peak in the isotopic distribution."""
+        return self.ffi.getMonoisotopicPeakLProbIso(self.iso)
+
+    def getMonoisotopicPeakConf(self):
+        """Get the isotopic configuration of the monoisotopic peak in the isotopic distribution."""
+        self.ffi.getMonoisotopicPeakSignature(self.iso, self.conf_space)
+        return self.parse_conf(self.conf_space)
+
+    def getModeLProb(self):
+        """Get the log probability of the most probable peak(s) in the isotopic distribution."""
+        return self.ffi.getModeLProbIso(self.iso)
+
+    def getModeMass(self):
+        """Get the mass of the most probable peak.
+
+        If there are more, return only the mass of one of them."""
+        return self.ffi.getModeMassIso(self.iso)
+
+    def getTheoreticalAverageMass(self):
+        return self.ffi.getTheoreticalAverageMassIso(self.iso)
+
+    def variance(self):
+        return self.ffi.getIsoVariance(self.iso)
+
+    def stddev(self):
+        return self.ffi.getIsoStddev(self.iso)
+
+    def getMarginalLogSizeEstimates(self, prob):
+        cbuf = isoFFI.clib.getMarginalLogSizeEstimates(self.iso, prob)
+        # cbuf is already "double *" (cdef'd below): index it directly rather
+        # than casting through a fresh "double[N]" string, which would need a
+        # full, uncached cffi/pycparser parse for every distinct dimNumber.
+        ret = [cbuf[i] for i in range(self.dimNumber)]
+        isoFFI.clib.freeReleasedArray(cbuf)
+        return ret
+
+    def parse_conf(self, cptr, starting_with = 0):
+        return tuple(tuple(cptr[i+starting_with] for i in o) for o in self.offsets)
+
+    def _get_parse_conf_fun(self):
+        # Can't just use the above function as lambda, as the entire class instance will be in closure
+        offsets = self.offsets
+        def pc(cptr, starting_with = 0):
+            return tuple(tuple(cptr[i+starting_with] for i in o) for o in offsets)
+        return pc
+
+
+class IsoDistribution(object):
+    """Isotopoic distribution with precomputed vector of masses and probabilities."""
+    def np_masses(self):
+        """Return computed masses as a numpy array."""
+        try:
+            import numpy as np
+        except ImportError as e:
+            raise Exception(str(e) + "\nThis requires numpy to be installed.")
+        return np.frombuffer(isoFFI.ffi.buffer(self.masses))
+
+    def np_probs(self):
+        """Return computed probabilities as a numpy array."""
+        try:
+            import numpy as np
+        except ImportError as e:
+            raise Exception(str(e) + "\nThis requires numpy to be installed.")
+        return np.frombuffer(isoFFI.ffi.buffer(self.probs))
+
+    def __iter__(self):
+        if hasattr(self, "confs") and self.confs is not None:
+            for i in range(self.size):
+                yield(self.masses[i], self.probs[i], self.confs[i])
+        else:
+            for i in range(self.size):
+                yield (self.masses[i], self.probs[i])
+
+    def __getitem__(self, idx):
+        try:
+            return (self.masses[idx], self.probs[idx], self.confs[idx])
+        except (AttributeError, TypeError):
+            return (self.masses[idx], self.probs[idx])
+
+    def __len__(self):
+        """Get the number of calculated peaks."""
+        return self.size
+
+    def _get_conf(self, idx):
+        return self.parse_conf(self.raw_confs, starting_with = self.sum_isotope_numbers * idx)
+
+    def __del__(self):
+        pass
+
+    def __init__(self, cobject = None, probs = None, masses = None, get_confs = False, iso = None):
+        self.mass_sorted = False
+        self.prob_sorted = False
+        self._total_prob = float('nan')
+
+        if cobject is not None:
+            self.size = isoFFI.clib.confs_noFixedEnvelope(cobject)
+
+            # The *WithDeleter getters hand the array over without copying it:
+            # the library's own buffers are SIMD-aligned, and a large one is
+            # mapped straight from the OS, so plain free() is not necessarily the
+            # right way to give them back. Each getter therefore writes out the
+            # (size, deleter) pair that releases this particular array, and we
+            # bind both into the ffi.gc destructor.
+            def wrap(typename, getter, attrname, mult = 1):
+                size_out = isoFFI.ffi.new("size_t*")
+                deleter_out = isoFFI.ffi.new("IsoSpecArrayDeleter*")
+                what = getter(cobject, size_out, deleter_out)
+                # Reinterpreting `what` as an array of exactly the right length
+                # would normally mean asking cffi to parse "typename[N]" -- but
+                # N varies on every call, so cffi's per-string type cache never
+                # hits and each call falls through to a full, uncached parse.
+                # Route the *length* through a plain byte buffer instead: the
+                # "typename *" cast and the "typename[]" open-array type are
+                # both fixed strings, parsed (and cached) once for the life of
+                # the process, no matter how many distinct N show up here.
+                n = self.size * mult
+                ptr = isoFFI.ffi.cast(typename + ' *', what)
+                if what != isoFFI.ffi.NULL:
+                    # An empty envelope owns nothing, and has nothing to release.
+                    # The destructor is attached to the plain pointer, not to
+                    # the sized array below: cffi's from_buffer() cdata does
+                    # not support ffi.gc() directly (it corrupts the array's
+                    # length -- verified separately). Attaching it here
+                    # instead works because the array keeps its backing
+                    # buffer alive, and the buffer keeps this pointer alive,
+                    # so the destructor still fires exactly when the array
+                    # itself is finally dropped.
+                    nbytes = size_out[0]
+                    deleter = deleter_out[0]
+                    ptr = isoFFI.ffi.gc(ptr, lambda p: isoFFI.clib.freeReleasedArrayWithDeleter(p, nbytes, deleter))
+                x = isoFFI.ffi.from_buffer(
+                    typename + '[]',
+                    isoFFI.ffi.buffer(ptr, n * isoFFI.ffi.sizeof(typename)))
+                setattr(self, attrname, x)
+
+            wrap("double", isoFFI.clib.massesFixedEnvelopeWithDeleter, "masses")
+            wrap("double", isoFFI.clib.probsFixedEnvelopeWithDeleter, "probs")
+
+            if get_confs:
+                # Must also be a subclass of Iso...
+                self.sum_isotope_numbers = sum(iso.isotopeNumbers)
+                wrap("int", isoFFI.clib.confsFixedEnvelopeWithDeleter, "raw_confs", mult = self.sum_isotope_numbers)
+                self.confs = ConfsPassthrough(lambda idx: self._get_conf(idx), self.size)
+                self.parse_conf = iso._get_parse_conf_fun()
+
+        elif probs is not None or masses is not None:
+            if probs is None or masses is None:
+                raise ValueError("masses and probs must both be provided together")
+            if len(probs) != len(masses):
+                raise ValueError("masses and probs must have the same length")
+            self.size = len(probs)
+            # "double[]" (open array) infers its length from the initializer,
+            # so this is one fixed, cacheable type string regardless of size
+            # -- see the matching note on conf_space above.
+            self.probs  = isoFFI.ffi.new("double[]", probs)
+            self.masses = isoFFI.ffi.new("double[]", masses)
+        else:
+            raise ValueError("IsoDistribution requires at least one of: cobject, or masses+probs")
+
+    def _get_cobject(self):
+        if hasattr(self, 'raw_confs') and self.raw_confs is not None:
+            return isoFFI.clib.setupFixedEnvelopeWithConfs(self.masses, self.probs, self.raw_confs, len(self.masses), self.sum_isotope_numbers, self.mass_sorted, self.prob_sorted, self._total_prob)
+        else:
+            return isoFFI.clib.setupFixedEnvelope(self.masses, self.probs, len(self.masses), self.mass_sorted, self.prob_sorted, self._total_prob)
+
+    def copy(self):
+        x = self._get_cobject()
+        c = isoFFI.clib.copyFixedEnvelope(x)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        ret = IsoDistribution(cobject = c)
+        ret._total_prob = self._total_prob
+        ret.mass_sorted = self.mass_sorted
+        ret.prob_sorted = self.prob_sorted
+        isoFFI.clib.deleteFixedEnvelope(c, False)
+        return ret
+
+    def __add__(self, other):
+        x = self._get_cobject()
+        y = other._get_cobject()
+        cobject = isoFFI.clib.addEnvelopes(x, y)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        isoFFI.clib.deleteFixedEnvelope(y, True)
+        ret = IsoDistribution(cobject = cobject)
+        isoFFI.clib.deleteFixedEnvelope(cobject, False)
+        return ret
+
+    def __mul__(self, other):
+        x = self._get_cobject()
+        y = other._get_cobject()
+        cobject = isoFFI.clib.convolveEnvelopes(x, y)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        isoFFI.clib.deleteFixedEnvelope(y, True)
+        ret = IsoDistribution(cobject = cobject)
+        isoFFI.clib.deleteFixedEnvelope(cobject, False)
+        return ret
+
+    def total_prob(self):
+        if math.isnan(self._total_prob):
+            co = self._get_cobject()
+            self._total_prob = isoFFI.clib.getTotalProbOfEnvelope(co)
+            isoFFI.clib.deleteFixedEnvelope(co, True)
+        return self._total_prob
+
+    def normalize(self):
+        co = self._get_cobject()
+        isoFFI.clib.normalizeEnvelope(co)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        self._total_prob = 1.0
+
+    def normalized(self):
+        ret = self.copy()
+        ret.normalize()
+        return ret
+
+    def add_mass(self, d_mass):
+        isoFFI.clib.array_add(self.masses, self.size, d_mass)
+
+    def mul_mass(self, d_mass):
+        isoFFI.clib.array_mul(self.masses, self.size, d_mass)
+
+    def add_mul_mass(self, add, mul):
+        isoFFI.clib.array_fma(self.masses, self.size, mul, add*mul)
+
+    def mul_add_mass(self, mul, add):
+        isoFFI.clib.array_fma(self.masses, self.size, mul, add)
+
+    def scale(self, factor):
+        '''Multiplies the pribabilities of spectrum by factor. Works in place.'''
+        co = self._get_cobject()
+        isoFFI.clib.scaleEnvelope(co, factor)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        self._total_prob *= factor
+
+    def scaled(self, factor):
+        '''Returns a copy of the spectrum where each probability was multiplied by factor.'''
+        ret = self.copy()
+        ret.scale(factor)
+        return ret
+
+    def resample(self, ionic_current, beta_bias=1.0):
+        co = self._get_cobject()
+        isoFFI.clib.resampleEnvelope(co, ionic_current, beta_bias)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        self._total_prob = float(ionic_current)
+        self.prob_sorted = False
+
+    def sort_by_prob(self):
+        if not self.prob_sorted:
+            co = self._get_cobject()
+            isoFFI.clib.sortEnvelopeByProb(co)
+            isoFFI.clib.deleteFixedEnvelope(co, True)
+            self.mass_sorted = False
+            self.prob_sorted = True
+
+    def sort_by_mass(self):
+        if not self.mass_sorted:
+            co = self._get_cobject()
+            isoFFI.clib.sortEnvelopeByMass(co)
+            isoFFI.clib.deleteFixedEnvelope(co, True)
+            self.mass_sorted = True
+            self.prob_sorted = False
+
+    def _recalculate_everything(self):
+        self._total_prob = float('nan')
+        self.mass_sorted = False
+        self.prob_sorted = False
+
+    def empiric_average_mass(self):
+        co = self._get_cobject()
+        ret = isoFFI.clib.empiricAverageMass(co)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        return ret
+
+    def empiric_variance(self):
+        co = self._get_cobject()
+        ret = isoFFI.clib.empiricVariance(co)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        return ret
+
+    def empiric_stddev(self):
+        co = self._get_cobject()
+        ret = isoFFI.clib.empiricStddev(co)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        return ret
+
+    def wassersteinDistance(self, other):
+        x = self._get_cobject()
+        y = other._get_cobject()
+        ret = isoFFI.clib.wassersteinDistance(x, y)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        isoFFI.clib.deleteFixedEnvelope(y, True)
+        self.mass_sorted = True
+        self.prob_sorted = False
+        other.mass_sorted = True
+        other.prob_sorted = False
+        if math.isnan(ret):
+            raise ValueError("Both spectra must be normalized before Wasserstein distance can be computed.")
+        return ret
+
+    def orientedWassersteinDistance(self, other):
+        x = self._get_cobject()
+        y = other._get_cobject()
+        ret = isoFFI.clib.orientedWassersteinDistance(x, y)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        isoFFI.clib.deleteFixedEnvelope(y, True)
+        self.mass_sorted = True
+        self.prob_sorted = False
+        other.mass_sorted = True
+        other.prob_sorted = False
+        if math.isnan(ret):
+            raise ValueError("Both spectra must be normalized before Wasserstein distance can be computed.")
+        return ret
+
+    def abyssalWassersteinDistance(self, other, abyss_depth, other_scale = 1.0):
+        x = self._get_cobject()
+        y = other._get_cobject()
+        ret = isoFFI.clib.abyssalWassersteinDistance(x, y, abyss_depth, other_scale)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        isoFFI.clib.deleteFixedEnvelope(y, True)
+        self.mass_sorted = True
+        self.prob_sorted = False
+        other.mass_sorted = True
+        other.prob_sorted = False
+        return ret
+
+    def abyssalWassersteinDistanceGrad(self, others, scales, grad, abyss_depth_exp, abyss_depth_the):
+        assert len(others) + 1 == len(scales) == len(grad)
+        cobjs = [self._get_cobject()]
+        cobjs.extend(other._get_cobject() for other in others)
+        ret = isoFFI.clib.abyssalWassersteinDistanceGrad(cobjs, scales, grad, len(others), abyss_depth_exp, abyss_depth_the)
+        for cobj in cobjs:
+            isoFFI.clib.deleteFixedEnvelope(cobj, True)
+        self.mass_sorted = True
+        self.prob_sorted = False
+        for other in others:
+            other.mass_sorted = True
+            other.prob_sorted = False
+        return ret
+
+    def wassersteinMatch(self, other, flow_dist, other_scale = 1.0):
+        x = self._get_cobject()
+        y = other._get_cobject()
+        ret = isoFFI.clib.wassersteinMatch(x, y, flow_dist, other_scale)
+        isoFFI.clib.deleteFixedEnvelope(x, True)
+        isoFFI.clib.deleteFixedEnvelope(y, True)
+        self.mass_sorted = True
+        self.prob_sorted = False
+        other.mass_sorted = True
+        other.prob_sorted = False
+        return (ret.res1, ret.res2, ret.flow)
+
+    def binned(self, width = 1.0, middle = 0.0):
+        co = self._get_cobject()
+        cbo = isoFFI.clib.binnedEnvelope(co, width, middle)
+        isoFFI.clib.deleteFixedEnvelope(co, True)
+        ret = IsoDistribution(cobject = cbo)
+        isoFFI.clib.deleteFixedEnvelope(cbo, False)
+        self.mass_sorted = True
+        self.prob_sorted = False
+        ret.mass_sorted = True
+        ret.prob_sorted = False
+        return ret
+
+
+    @staticmethod
+    def LinearCombination(envelopes, intensities):
+        envelope_objs = [x._get_cobject() for x in envelopes]
+        if type(intensities) != list:
+            intensities = list(intensities)
+        cobject = isoFFI.clib.linearCombination(envelope_objs, intensities, len(envelope_objs))
+        for x in envelope_objs:
+            isoFFI.clib.deleteFixedEnvelope(x, True)
+        ret = IsoDistribution(cobject = cobject)
+        isoFFI.clib.deleteFixedEnvelope(cobject, False)
+        return ret
+
+
+    def plot(self, plot_type = "bars", show = True, **matplotlib_args):
+        """Plot the isotopic distribution.
+
+        Args:
+            **matplotlib_args: arguments for matplotlib plot.
+        """
+        try:
+            from matplotlib import pyplot as plt
+        except ImportError as e:
+            raise ImportError(str(e) + "\nPlotting spectra requires matplotlib to be installed.")
+        if plot_type == "bars":
+            if "linewidth" not in matplotlib_args:
+                matplotlib_args['linewidth'] = 1.0
+            plt.vlines(list(self.masses), [0], list(self.probs), **matplotlib_args)
+        elif plot_type == "profile":
+            self.sort_by_mass()
+            plt.plot(list(self.masses), list(self.probs), **matplotlib_args)
+        plt.xlabel("Mass (Da)")
+        plt.ylabel("Intensity (relative)")
+        if show:
+            plt.show()
+
+
+
+
+def IsoThreshold(threshold,
+                 formula="",
+                 absolute=False,
+                 get_confs=False,
+                 **kwargs):
+    """Initialize the IsoDistribution isotopic distribution by threshold.
+
+    Args:
+        threshold (float): value of the absolute or relative threshold.
+        formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+        absolute (boolean): should we report peaks with probabilities above an absolute probability threshold, or above a relative threshold amounting to a given proportion of the most probable peak?
+        get_confs (boolean): should we report counts of isotopologues?
+        **kwds: named arguments to IsoSpectrum.
+    """
+    iso = Iso(formula = formula, get_confs = get_confs, **kwargs)
+    tabulator = isoFFI.clib.setupThresholdFixedEnvelope(iso.iso, threshold, absolute, get_confs)
+    ido = IsoDistribution(cobject = tabulator, get_confs = get_confs, iso = iso)
+    isoFFI.clib.deleteFixedEnvelope(tabulator, False)
+    return ido
+
+
+def IsoTotalProb(prob_to_cover,
+                 formula="",
+                 get_minimal_pset=True,
+                 get_confs=False,
+                 **kwargs):
+        """Initialize the IsoDistribution isotopic distribution by total probability.
+
+        Args:
+            prob_to_cover (float): minimal total probability of the reported peaks.
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            get_minimal_pset (boolean): should we trim the last calculated layer of isotopologues so that the reported result is as small as possible?
+            get_confs (boolean): should we report the counts of isotopologues?
+            **kwargs: named arguments to the superclass.
+        """
+        iso = Iso(formula=formula, get_confs=get_confs, **kwargs)
+        tabulator = isoFFI.clib.setupTotalProbFixedEnvelope(iso.iso, prob_to_cover, get_minimal_pset, get_confs)
+        ido = IsoDistribution(cobject = tabulator, get_confs = get_confs, iso = iso)
+        isoFFI.clib.deleteFixedEnvelope(tabulator, False)
+        return ido
+
+
+def IsoStochastic(no_molecules,
+                 formula="",
+                 precision=0.9999,
+                 beta_bias=5.0,
+                 get_confs=False,
+                 **kwargs):
+        """Initialize the isotopic distribution by stochastic sampling, simulating a measured mass spectrum
+        with a given number of ions. Each configuration is drawn independently according to its isotopic
+        probability, producing integer ion counts rather than exact probabilities.
+
+        Args:
+            no_molecules (uint): number of ions to simulate (ionic current).
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            precision (float): total probability of the envelope used for sampling. Between 0.0 and 1.0.
+            beta_bias (float, nonnegative): fiddling with this parameter does not change the result, but might make computations slightly faster (or likely, much, much slower if you screw it up...)
+            get_confs (boolean): should we report the counts of isotopologues?
+            **kwargs: named arguments to the superclass.
+        """
+        iso = Iso(formula=formula, get_confs=get_confs, **kwargs)
+        tabulator = isoFFI.clib.setupStochasticFixedEnvelope(iso.iso, no_molecules, precision, beta_bias, get_confs)
+        ido = IsoDistribution(cobject = tabulator, get_confs = get_confs, iso = iso)
+        isoFFI.clib.deleteFixedEnvelope(tabulator, False)
+        return ido
+
+
+def IsoBinned(bin_width,
+                 formula="",
+                 target_total_prob=0.9999,
+                 bin_middle=0.0,
+                 **kwargs):
+        """Initialize the isotopic distribution as a binned (histogram) envelope.
+        Configurations are grouped into bins of equal width and their probabilities summed.
+
+        Args:
+            bin_width (float): width of each bin in Da.
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            target_total_prob (float): total probability of configurations to include before binning. Between 0.0 and 1.0.
+            bin_middle (float): offset of bin centres from zero.
+            **kwargs: named arguments to the superclass.
+        """
+        iso = Iso(formula=formula, get_confs=False, **kwargs)
+        tabulator = isoFFI.clib.setupBinnedFixedEnvelope(iso.iso, target_total_prob, bin_width, bin_middle)
+        ido = IsoDistribution(cobject = tabulator, get_confs = False, iso = iso)
+        isoFFI.clib.deleteFixedEnvelope(tabulator, False)
+        return ido
+
+
+class IsoGenerator(Iso):
+    """Virtual class alowing memory-efficient iteration over the isotopic distribution.
+
+    This iterator will stop only after enumerating all isotopologues.
+    """
+    def __init__(self, formula="", get_confs=False, **kwargs):
+        """Initialize the IsoGenerator.
+
+        Args:
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            get_confs (boolean): should we report the counts of isotopologues?
+            **kwargs: named arguments to the superclass.
+        """
+        self.cgen = None
+        super(IsoGenerator, self).__init__(formula=formula, get_confs=get_confs, **kwargs)
+        self.firstuse = True
+
+    def __iter__(self):
+        if not self.firstuse:
+            raise NotImplementedError("Multiple iterations through the same IsoGenerator object are not supported. Either create a new (identical) generator for a second loop-through, or use one of the non-generator classes, which do support being re-used.")
+        self.firstuse = False
+        cgen = self.cgen
+        if self.get_confs:
+            while self.advancer(cgen):
+                self.conf_getter(cgen, self.conf_space)
+                yield (self.mass_getter(cgen), self.xprob_getter(cgen), self.parse_conf(self.conf_space))
+        else:
+            while self.advancer(cgen):
+                yield (self.mass_getter(cgen), self.xprob_getter(cgen))
+
+    def __del__(self):
+        super(IsoGenerator, self).__del__()
+
+
+class IsoThresholdGenerator(IsoGenerator):
+    """Class alowing memory-efficient iteration over the isotopic distribution up till some probability threshold.
+
+    This iterator will stop only after reaching a probability threshold.
+    """
+    def __init__(self, threshold, formula="", absolute=False, get_confs=False, reorder_marginals = True, **kwargs):
+        """Initialize IsoThresholdGenerator.
+
+        Args:
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            absolute (boolean): should we report peaks with probabilities above an absolute probability threshold, or above a relative threshold amounting to a given proportion of the most probable peak?
+            get_confs (boolean): should we report the counts of isotopologues?
+            **kwargs: named arguments to the superclass.
+        """
+        super(IsoThresholdGenerator, self).__init__(formula=formula, get_confs=get_confs, **kwargs)
+        self.threshold = threshold
+        self.absolute = absolute
+        self.cgen = self.ffi.setupIsoThresholdGenerator(self.iso,
+                                                        threshold,
+                                                        absolute,
+                                                        1000,
+                                                        1000,
+                                                        reorder_marginals)
+        self.advancer = self.ffi.advanceToNextConfigurationIsoThresholdGenerator
+        self.xprob_getter = self.ffi.probIsoThresholdGenerator
+        self.mass_getter = self.ffi.massIsoThresholdGenerator
+        self.conf_getter = self.ffi.get_conf_signatureIsoThresholdGenerator
+
+    def __del__(self):
+        """Destructor."""
+        try:
+            if self.cgen is not None:
+                self.ffi.deleteIsoThresholdGenerator(self.cgen)
+                self.cgen = None
+        except AttributeError:
+            pass
+        super(IsoThresholdGenerator, self).__del__()
+
+
+class IsoLayeredGenerator(IsoGenerator):
+    """Class alowing memory-efficient iteration over the isotopic distribution up till some joint probability of the reported peaks."""
+    def __init__(self, formula="", get_confs=False, reorder_marginals = True, t_prob_hint = 0.99, **kwargs):
+        """Initialize IsoLayeredGenerator.
+
+        Args:
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            get_confs (boolean): should we report the counts of isotopologues?
+            reorder_marginals (boolean): should the marginal distributions be reordered for efficiency?
+            t_prob_hint (float): hint for the target total probability, used to size internal buffers.
+            **kwargs: named arguments to the superclass.
+        """
+        super(IsoLayeredGenerator, self).__init__(formula=formula, get_confs=get_confs, **kwargs)
+        self.cgen = self.ffi.setupIsoLayeredGenerator(self.iso, 1000, 1000, reorder_marginals, t_prob_hint)
+        self.advancer = self.ffi.advanceToNextConfigurationIsoLayeredGenerator
+        self.xprob_getter = self.ffi.probIsoLayeredGenerator
+        self.mass_getter = self.ffi.massIsoLayeredGenerator
+        self.conf_getter = self.ffi.get_conf_signatureIsoLayeredGenerator
+
+    def __del__(self):
+        try:
+            if self.cgen is not None:
+                self.ffi.deleteIsoLayeredGenerator(self.cgen)
+                self.cgen = None
+        except AttributeError:
+            pass
+        super(IsoLayeredGenerator, self).__del__()
+
+class IsoOrderedGenerator(IsoGenerator):
+    """Class representing an isotopic distribution with peaks ordered by descending probability.
+
+    This generator return probilities ordered with descending probability.
+    It it not optimal to do so, but it might be useful.
+
+    WARNING! This algorithm work in O(N*log(N)) vs O(N) of the threshold and layered algorithms.
+    Also, the order of descending probability will most likely not reflect the order of ascending masses.
+    """
+    def __init__(self, formula="", get_confs=False, **kwargs):
+        """Initialize IsoOrderedGenerator.
+
+        Args:
+            formula (str): a chemical formula, e.g. "C2H6O1" or "C2H6O".
+            get_confs (boolean): should we report the counts of isotopologues?
+            **kwargs: named arguments to the superclass.
+        """
+        super(IsoOrderedGenerator, self).__init__(formula=formula, get_confs=get_confs, **kwargs)
+        self.cgen = self.ffi.setupIsoOrderedGenerator(self.iso, 1000, 1000)
+        self.advancer = self.ffi.advanceToNextConfigurationIsoOrderedGenerator
+        self.xprob_getter = self.ffi.probIsoOrderedGenerator
+        self.mass_getter = self.ffi.massIsoOrderedGenerator
+        self.conf_getter = self.ffi.get_conf_signatureIsoOrderedGenerator
+
+    def __del__(self):
+        try:
+            if self.cgen is not None:
+                self.ffi.deleteIsoOrderedGenerator(self.cgen)
+                self.cgen = None
+        except AttributeError:
+            pass
+        super(IsoOrderedGenerator, self).__del__()
+
+
+class IsoStochasticGenerator(IsoGenerator):
+    def __init__(self, no_molecules, formula="", precision=0.9999, beta_bias = 1.0, get_confs=False, **kwargs):
+        super(IsoStochasticGenerator, self).__init__(formula=formula, get_confs=get_confs, **kwargs)
+        self.threshold = precision
+        self.no_molecules = no_molecules
+        self.cgen = self.ffi.setupIsoStochasticGenerator(self.iso,
+                                                        no_molecules,
+                                                        precision,
+                                                        beta_bias)
+        self.advancer = self.ffi.advanceToNextConfigurationIsoStochasticGenerator
+        self.xprob_getter = self.ffi.probIsoStochasticGenerator
+        self.mass_getter = self.ffi.massIsoStochasticGenerator
+        self.conf_getter = self.ffi.get_conf_signatureIsoStochasticGenerator
+
+    def __del__(self):
+        """Destructor."""
+        try:
+            if self.cgen is not None:
+                self.ffi.deleteIsoStochasticGenerator(self.cgen)
+                self.cgen = None
+        except AttributeError:
+            pass
+        super(IsoStochasticGenerator, self).__del__()
+
+
+def get_simd_level():
+    """Report what the bundled C++ library's vectorised kernels are running as.
+
+    The wheels carry several builds of the inner loops and choose one from the
+    CPU at import time, so this is a property of the machine as much as of the
+    build. Use it to tell an installation that vectorises from one that silently
+    does not -- on Windows, for instance, where the standard library provides no
+    <experimental/simd> and everything falls back to the scalar path.
+
+    Returns:
+        str: one of "scalar" (not vectorised at all), "sse2", "avx", "avx2",
+             "avx512", "neon", or "simd" for a vector unit the library has no
+             name for. New tokens may appear as instruction sets are added, so
+             treat an unfamiliar one as "some vector unit" rather than an error.
+    """
+    return isoFFI.ffi.string(isoFFI.clib.activeSimdLevel()).decode("ascii")
+