IsoSpecPy 2.5.0__py3-none-win_arm64.whl

IsoSpecPy/IsoSpecPyOld.py

@@ -0,0 +1,290 @@
+# -*- 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>.
+#
+
+
+'''
+Bunch of deprecated functions for 1.0.X compatibility.
+Avoid using them: there is a considerable overhead associated
+with using the old interface... The backward compatibility module
+is also very rudimentary, somewhat incomplete and not very well
+tested too...
+
+The current API is implemented in __init__.py, use that instead
+'''
+
+
+import re
+from .IsoSpecPy import IsoTotalProb, IsoThreshold
+
+DIGIT_PATTERN = re.compile(r"\d+")
+NON_DIGIT_PATTERN = re.compile(r"\D+")
+
+class IsoSpec():
+    def __init__(
+                    self,
+                    _atomCounts,
+                    _isotopeMasses,
+                    _isotopeProbabilities,
+                    _stopCondition,
+                    tabSize = 1000,     # ignored
+                    hashSize = 1000,    # ignored
+                    step = 0.3,         # ignored
+                    trim = True,        # True not supported yet, treated as False anyway
+                    method = 'layered'
+                ):
+
+        isoargs = {
+            "formula"           : None,
+            "get_confs"         : True,
+            "atomCounts"        : _atomCounts,
+            "isotopeMasses"     : _isotopeMasses,
+            "isotopeProbabilities"  : _isotopeProbabilities,
+        }
+
+
+        self.dimNumber                 = len(_atomCounts)
+        self._isotopeNumbers           = [len(x) for x in _isotopeMasses]
+        self.allIsotopeNumber         = sum(self._isotopeNumbers)
+        self._atomCounts               = _atomCounts
+        self._isotopeMasses            = _isotopeMasses
+        self._isotopeProbabilities     = _isotopeProbabilities
+        self._stopCondition            = _stopCondition
+
+        from .__init__ import IsoThreshold
+
+        try:
+            algo = { 'layered' : lambda total_prob: IsoTotalProb(total_prob, **isoargs),
+              'ordered' : lambda total_prob: IsoTotalProb(total_prob, **isoargs),
+              'threshold_absolute' : lambda threshold: IsoThreshold(threshold, True, **isoargs),
+              'threshold_relative' : lambda threshold: IsoThreshold(threshold, False, **isoargs),
+              'layered_estimating' : lambda total_prob: IsoTotalProb(total_prob, **isoargs)
+            }[method]
+        except KeyError:
+            raise Exception("Invalid ISO method")
+
+        # Reference to iso needs to be held in this object: it will deallocate masses/lprobs/etc arrays on C++ side if we
+        # allow GC to collect it prematurely
+        self.iso = algo(_stopCondition)
+
+        self.masses = self.iso.masses
+        self.lprobs = self.iso.lprobs
+        self.probs  = self.iso.probs
+        self.confs  = self.iso.confs
+        self.size   = self.iso.size
+
+        if method == 'ordered' and len(self.masses) > 0:
+            L = sorted(zip(self.masses, self.lprobs, self.probs, self.confs), key = lambda x: -x[1])
+            self.masses, self.lprobs, self.probs, self.confs = zip(*L)
+
+    @staticmethod
+    def IsoFromFormula(formula, cutoff, tabSize = 1000, hashSize = 1000, classId = None, method = 'threshold_relative', step = 0.25, trim = True):
+        # It's much easier to just parse it in python than to use the C parsing function
+        # and retrieve back into Python the relevant object sizes
+        symbols = re.findall(NON_DIGIT_PATTERN, formula)
+        atom_counts = [int(x) for x in re.findall(DIGIT_PATTERN, formula)]
+
+        if not len(symbols) == len(atom_counts):
+            raise ValueError("Invalid formula")
+
+        from .PeriodicTbl import symbol_to_masses, symbol_to_probs
+        try:
+            masses = tuple(symbol_to_masses[symbol] for symbol in symbols)
+            probs = tuple(symbol_to_probs[symbol] for symbol in symbols)
+        except KeyError:
+            raise ValueError("Invalid formula")
+
+        return IsoSpec(atom_counts, masses, probs, cutoff, tabSize, hashSize, step, trim, method)
+
+
+
+    def __len__(self):
+        return self.size
+
+    def getConfsRaw(self):
+        return (self.masses, self.lprobs, self.confs)
+
+#    def get_conf_by_no(self, clist, idx):
+#        idx *= self.allIsotopeNumber
+#        ret = []
+#        for ison in self._isotopeNumbers:
+#            ret.append(tuple(clist[idx:idx+ison]))
+#            idx += ison
+#        return tuple(ret)
+
+
+    def getConfs(self):
+        masses, logProbs, isoCounts = self.getConfsRaw()
+        rows_no = len(masses)
+        masses  = list(masses)
+        logProbs= list(logProbs)
+        confs = []
+        for i in range(rows_no):
+            confs.append([x for sublist in isoCounts[i] for x in sublist])
+        return masses, logProbs, confs
+
+
+    def getConfsNumpy(self):
+        import numpy as np
+        masses, logProbs, configurations = self.getConfsRaw()
+        rows_no = len(masses)
+        if rows_no == 0:
+            return np.array([])
+        cols_no = len(configurations)//len(masses)
+        masses  = np.array(list(masses))
+        logProbs= np.array(list(logProbs))
+        configurations = np.array(list(configurations)).reshape((rows_no,cols_no))
+        return masses, logProbs, configurations
+
+
+    def splitConf(self, l, offset = 0):
+        conf = []
+        idx = self.allIsotopeNumber * offset
+        for i in range(self.dimNumber):
+            conf.append(tuple(l[idx:idx+self._isotopeNumbers[i]]))
+            idx += self._isotopeNumbers[i]
+        return tuple(conf)
+
+    def confStr(self, conf):
+        return '\t'.join([' '.join([str(x) for x in y]) for y in conf])
+
+    def printConfs(self):
+        masses, logProbs, isoCounts = self.getConfsRaw()
+        confs = []
+        step = sum(self._isotopeNumbers)
+        for i in range(len(masses)):
+            confs.append((masses[i], logProbs[i], self.splitConf(isoCounts, i)))
+
+        for conf in confs:
+            print(("Mass = {0}\t and log-prob = {1} and prob = {2}\t and configuration"\
+                  "=\t{3}").format(conf[0], conf[1], math.exp(conf[1]), self.confStr(conf[2])))
+
+
+
+class IsoPlot(dict):
+    def __init__(self, iso, bin_w):
+        self.iso = iso
+        self.bin_w = bin_w
+        masses, logProbs, _isoCounts = iso.getConfsRaw()
+        dd = defaultdict(Summator)
+        for i in range(len(masses)):
+            dd[float(int(masses[i]/bin_w))*bin_w].add(math.exp(logProbs[i]))
+        for key, val in dd.items():
+            self[key] = val.get()
+
+
+def IsoSpecify( formula,
+                cutoff,
+                method= 'layered',
+                output_format = 'numpy_arrays',
+                trim  = True,
+                _step = 0.25,
+                _trim = True,
+                _tabSize  = 1000,
+                _hashSize = 1000    ):
+    """
+    Call IsoSpec on a formula with a given cutoff.
+
+    This function wraps around the IsoSpec class.
+
+    Parameters
+    ----------
+    formula : char
+        a string of a form '< Element Tag 1 >< Count 1 > ... ',
+        e.g. 'C100H202'. Using IUPAC conventions to name elements.
+
+    cutoff : float
+        The cutoff value. See description of the method argument.
+
+    method : char
+        Can take one of the following values: 'layered',
+        'layered_estimating', 'threshold_absolute',
+        'threshold_relative', 'ordered'.
+
+        The threshold versions of the algorithm rely on user
+        providing a precise lower bound on the reported peak heights.
+        This can be specified in absolute terms ('threshold_absolute'),
+        i.e. in terms of the limiting probability of the isotopologue,
+        or as a percentage of the heighest peak ('threshold_relative').
+
+        The layered versions of the algorithm rely on calculating
+        consecutive values of peak thresholds on flight.
+        The ultimate goal is to reach a peak probability that assures
+        that the sum of probabilities of the more probable isotopologues
+        exceeds the provided cutoff value.
+        The sequence of consecutive thresholds can be generated in
+        two ways. The default way, 'layered_estimating', estimates
+        the threshold to joint probability function by a progressive
+        linear spline, check Anal Chem. 2017 Mar 21;89(6):3272-3277.
+        doi: 10.1021/acs.analchem.6b01459. Epub 2017 Mar 8.
+        The other way, 'layered', estimates a threshold as a 30%%
+        quantile of the probabilities gathered in the fringe set, i.e.
+        isotopologues that are direct neighbours of the previously
+        accepted layer. Finally, choosing the 'ordered' version will
+        provide a loglinear version of the algorithm that relies on
+        the priority queue. This version automatically sorts
+        the configurations by their probability.
+
+    trim
+        while using a layered method, should one discard superfluously
+        obtained isotopologues, i.e. such that without them the set of
+        reported isotopologues already is an optimal p-set.
+
+    output_format
+        Should the output be presented as lists ('lists'),
+        or as numpy arrays ('numpy_arrays').
+
+    Returns
+    -------
+    masses
+        masses of isotopologues, either a list or a numpy array.
+
+    logProbs
+        logarithms of probabilities (theoretical heights) of isotopologues,
+        either a list or a numpy array.
+
+    confs
+        counts of isotopologues (extended chemical formulas that
+        include counts of isotopes of elements)
+        """
+
+
+    assert output_format in ('lists', 'numpy_arrays'), "Wrong value of output_format. Should be either 'lists' or 'numpy_arrays'."
+
+    assert method in ('layered', 'ordered', 'threshold_absolute', 'threshold_relative', 'layered_estimating'), "Wrong value of method. Should be among 'layered', 'ordered', 'threshold_absolute', 'threshold_relative', or 'layered_estimating'."
+
+    assert isinstance(cutoff, float), "Provided cut off ain't a float."
+
+    assert isinstance(formula, str), "Provided formula off ain't a string."
+
+    iso = IsoSpec.IsoFromFormula(   formula,
+                                    cutoff,
+                                    tabSize = 1000,
+                                    hashSize = 1000,
+                                    classId = None,
+                                    method = method,
+                                    step = 0.25,
+                                    trim = trim )
+
+    if output_format == 'lists':
+        masses, logProbs, confs = iso.getConfs()
+    else:
+        masses, logProbs, confs = iso.getConfsNumpy()
+
+    # print 'Rev Startek is a silly old chump and his mother dresses up silly.'
+    return masses, logProbs, confs
+
+

IsoSpecPy/PeriodicTbl.py

@@ -0,0 +1,51 @@
+from .isoFFI import isoFFI
+from collections import defaultdict
+
+
+# There IS a real exported C variable with this exact value,
+# isospec_number_of_isotopic_entries (element_tables.cpp), which would
+# eliminate the hand-duplication below entirely if it were usable -- but
+# cffi's dlopen()-based ABI mode (what isoFFI.py uses; there's no
+# compile-time cffi build step here) cannot read a plain `extern const
+# size_t` global: `NotImplementedError: non-integer constant
+# 'isospec_number_of_isotopic_entries' cannot be accessed from a dlopen()
+# library` (confirmed by trying it directly). Only #define-style integer
+# constants (NUMBER_OF_ISOTOPIC_ENTRIES below) are readable this way, and
+# that one is exactly the hand-typed value that must be kept in sync by hand
+# with ISOSPEC_NUMBER_OF_ISOTOPIC_ENTRIES in element_tables.h -- forgetting
+# to bump it already caused one real bug (the #51/deuterium fix's first
+# pass silently missed "D" here even though the compiled library itself
+# already had it). No independent runtime cross-check is possible in ABI
+# mode, so there's nothing to assert against -- if you add table entries,
+# bump NUMBER_OF_ISOTOPIC_ENTRIES in isoFFI.py's cdef by hand, in the same
+# commit, or elements will silently go missing here again.
+number_of_isotopic_entries = isoFFI.clib.NUMBER_OF_ISOTOPIC_ENTRIES
+
+symbol_to_masses = defaultdict(tuple)
+symbol_to_massNo = defaultdict(tuple)
+symbol_to_probs  = defaultdict(tuple)
+symbol_to_atomic_number = {}
+
+for i in range(number_of_isotopic_entries):
+    symbol = isoFFI.ffi.string(isoFFI.clib.elem_table_symbol[i]).decode("ascii")
+    symbol_to_masses[symbol] += (isoFFI.clib.elem_table_mass[i],)
+    symbol_to_massNo[symbol] += (isoFFI.clib.elem_table_massNo[i],)
+    symbol_to_probs[symbol] += (isoFFI.clib.elem_table_probability[i],)
+    symbol_to_atomic_number[symbol] = isoFFI.clib.elem_table_atomicNo[i]
+
+symbol_to_masses = dict(symbol_to_masses)
+symbol_to_probs = dict(symbol_to_probs)
+
+# Several derivative convenience dicts...
+symbol_to_massprob = dict((key, list(zip(symbol_to_masses[key], symbol_to_probs[key]))) for key in symbol_to_probs.keys())
+
+def crossprod(l1, l2):
+    return sum(x1*x2 for x1, x2 in zip(l1, l2))
+
+symbol_to_avg_mass = dict((key, crossprod(symbol_to_masses[key], symbol_to_probs[key])) for key in symbol_to_probs.keys())
+
+def maxprod(l1, l2):
+    return max(zip(l1, l2), key = lambda x: x[1])[0]
+
+symbol_to_monoisotopic_mass = dict((key, maxprod(symbol_to_masses[key], symbol_to_probs[key])) for key in symbol_to_probs.keys())
+

IsoSpecPy/__init__.py

@@ -0,0 +1,19 @@
+from .IsoSpecPy import *
+import importlib.metadata
+
+__version__ = importlib.metadata.version("IsoSpecPy")
+
+# Old, deprecated name, for compatibility with 1.9.X only
+IsoLayered = IsoTotalProb
+
+# For backward compatibility with 1.0.X:
+class CompatIsoWrapper(object):
+    def __init__(self):
+        from .IsoSpecPyOld import IsoSpec, IsoSpecify, IsoPlot
+        self.IsoSpec = IsoSpec
+        self.IsoSpecify = IsoSpecify
+        self.IsoPlot = IsoPlot
+
+
+IsoSpecPy = CompatIsoWrapper()
+

IsoSpecPy/__main__.py

@@ -0,0 +1,25 @@
+from . import __version__
+
+if __name__ == "__main__":
+    import argparse
+    from pathlib import Path
+
+    parser = argparse.ArgumentParser(description="IsoSpecPy: Python interface to IsoSpec++ library, a fast and memory-efficient library for computing isotopic distributions.")
+    parser.add_argument('--version', '-v', action='version', version=__version__)
+    parser.add_argument('--libpath', action='store_true',
+                        help='Print the path to the loaded C++ library and exit.')
+    parser.add_argument('--include', action='store_true',
+                        help='Print the include path for the headers of the C++ library and exit.')
+    args = parser.parse_args()
+
+    if args.libpath:
+        try:
+            from .isoFFI import IsoFFI
+            ffi = IsoFFI()
+            print(Path(ffi.libpath).resolve())
+        except ImportError as e:
+            print(f"Error loading IsoSpecPy: {e}")
+        exit(0)
+
+    if args.include:
+        print(Path(__file__).parent.resolve())

IsoSpecPy/approximations.py

@@ -0,0 +1,122 @@
+"""Here we store formulas for approximating numbers of isotopologues and subisotopologues."""
+from math import exp, log, lgamma, pi
+
+from .IsoSpecPy import IsoParamsFromFormula
+
+
+def log_multinomial_confs_cnt(n, i):
+	"""Return the natural logarithm of the number of configurations of the multinomial distribution.
+
+	There are n independent trials of an experiment that results in one of the i outcomes.
+	For each outcome, count how many times it occured.
+	These counts then follow the multinomial distribution.
+
+	Args:
+		n (int): The number of trials.
+		i (int): The number of possible outcomes.
+	"""
+	return lgamma(n + i) - \
+		   lgamma(n + 1) - \
+		   lgamma(i)
+
+def test_log_multinomial_confs_cnt():
+	x = log_multinomial_confs_cnt(10,3)
+	assert abs(x - 4.189655) < 10**(-5)
+
+
+
+def log_V_simplex(n, i):
+	r"""Get the natural logarithm of the volume of a simplex {(x_1,..,x_{i-1}): \sum_{j=1}^i = n}.
+
+	Args:
+		n (int): The number of atoms of the element.
+		i (int): The number of isotopes of the element.
+	"""
+	return (i-1)*log(n) - lgamma(i)
+
+
+def test_log_V_simplex():
+	x = log_V_simplex(10,3)
+	assert abs(x - 3.912023) < 10**(-5)
+
+
+def V_simplex(n, i):
+	r"""Get the volume of a simplex {(x_1,..,x_{i-1}): \sum_{j=1}^i = n}.
+
+	Args:
+		n (int): The number of atoms of the element.
+		i (int): The number of isotopes of the element.
+	"""
+	return exp(log_V_simplex(n,i))
+
+def log_V_ellipsoid(n, R2, probs):
+	"""Get the natural logarithm of the volume of the ellipsoid.
+
+	The ellipsoid is defined by x' W^{-1} x <= R2,
+	where W = diag(probs[0:-1]) - probs[0:-1] * probs[0:-1]'
+	and R2 is the square of the radius.
+	diag(probs) is a matrix with values probs[0:-1] on the diagonal,
+	and probs[0:-1] * probs[0:-1]' is a projection on probs[0:-1].
+	Since probabilities are nonzero and sum to one, then det W != 0.
+	Also, the expression does not really depend upon the choice of one of the
+	ommited probability term, e.g. the outcome would stay the same if we remover p[1].
+
+	Args:
+		n (int): The number of atoms of the element.
+		R2 (float): The square of the radius of the ellipsoid.
+		probs (list): List with the natural frequencies of isotopes.
+	"""
+	i = len(probs)
+	log_det = sum(log(p) for p in probs) 
+	return (log_det + (i-1)*(log(n) + log(R2) + log(pi)))/2.0 - lgamma((i+1)/2.0)
+
+
+def test_log_V_ellipsoid():
+	assert abs(log_V_ellipsoid(100, 10, [.2,.3,.5]) - 6.299206) < 10**(-5)
+
+
+def V_ellipsoid(n, R2, probs):
+	"""Get the volume of the ellipsoid."""
+	return exp(log_V_ellipsoid(n, R2, probs))
+
+def log_subisotopologue_cnt(atoms_cnt, isotope_frequencies, ellipsoid_R2):
+	"""Get the natural logarithm of the approximate number of subisotopologues.
+
+	Args:
+		atoms_cnt (int): The number of atoms of the given element.
+		isotope_frequencies (list): The natural frequencies of isotopes (sum to one).
+		ellipsoid_R2 (float): The radius of the ellipsoid used to approximate the optimal P-set.
+	"""
+	isotopes_cnt = len(isotope_frequencies)
+	return log_multinomial_confs_cnt(atoms_cnt, isotopes_cnt) + \
+		   log_V_ellipsoid(atoms_cnt, ellipsoid_R2, isotope_frequencies) - \
+		   log_V_simplex(atoms_cnt, isotopes_cnt)
+
+def test_log_subisotopologue_cnt():
+	assert abs(log_subisotopologue_cnt(100, [.2,.3,.5], 10) - 6.328959) < 10**(-5)
+
+
+def subisotopologue_cnt(atoms_cnt, isotope_frequencies, ellipsoid_R2):
+	"""Get the approximate number of subisotopologues."""
+	return exp(log_subisotopologue_cnt(atoms_cnt, isotope_frequencies, ellipsoid_R2))
+
+
+def approximate_subisotopologues(molecule, P):
+	"""Approximate the number of subisotopologues.
+
+	Args:
+		molecule (str): A string with molecule, e.g. 'C100H202'.
+		P (float): The joint probability threshold.
+	"""
+	from scipy.stats import chi2
+	assert P >= 0 and P <= 1, 'That is not a probability.'
+	mol = IsoParamsFromFormula(molecule)
+	chi2_df = sum(len(p) for p in mol.probs) - len(mol.probs)
+	R2 = chi2.ppf(q=P, df=chi2_df)
+	return {e: subisotopologue_cnt(n, p, R2) for n, p, e in \
+			zip(mol.atomCounts, mol.probs, mol.elems)}
+
+
+if __name__ == '__main__':
+	print(approximate_subisotopologues('C100H202', .999))
+	print(approximate_subisotopologues("C100H100", .999))

IsoSpecPy/confs_passthrough.py

@@ -0,0 +1,16 @@
+
+
+
+
+class ConfsPassthrough(object):
+    def __init__(self, confs_parser, size):
+        self.confs_parser = confs_parser
+        self.size = size
+
+    def __len__(self):
+        return self.size
+
+    def __getitem__(self, idx):
+        return self.confs_parser(idx)
+
+