Merge pull request #6 from MetaSys-LISBP/dev

Dev to 2.1.0

README.md

@@ -30,6 +30,7 @@ Check out the [Tutorials](https://isocor.readthedocs.io/en/latest/tutorials.html
 * **correction of tracer purity**,
 * shipped as a library with both a **graphical and command line interface**,
 * mass-spectrometer and resolution agnostic,
+* can be applied to singly- and multiply-charged ions
 * can be used with any tracer element (having two or more isotopes)
 * account for the contribution of derivatization steps (if any),
 * open-source, free and easy to install everywhere where Python 3 and pip run,

doc/conf.py

@@ -54,10 +54,10 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.0'
+version = '2.1'
 # The full version, including alpha/beta/rc tags.
 # Do not forget to update PyPi (setup.py) version
-release = '2.0.5'
+release = '2.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/faq.rst

@@ -24,19 +24,19 @@ What are the alternatives to IsoCor?
 You will find scripts for correction of HRMS data out there, but we won’t recommend any since,
 to the best of our knowledge, they implement algorithms that partly fail for high-resolution datasets (see IsoCor v2 publication).
 
-+--------------+----------+----------------------+---------------------------------------------------------------------+------------------------------------------------------------------+---------------------------+
-| Tool         | Has GUI? | MS resolution?       | Tracers?                                                            | Reference                                                        | Comment                   |
-+==============+==========+======================+=====================================================================+==================================================================+===========================+
-| AccuCor      | No       | All                  | :sup:`2`\ H, :sup:`13`\ C, :sup:`15`\ N                             | `Su et al. 2017 <https://doi.org/10.1021/acs.analchem.7b00396>`_ | Faulty at High-resolution |
-+--------------+----------+----------------------+---------------------------------------------------------------------+------------------------------------------------------------------+---------------------------+
-| PyNAC        | No       | UltraHigh only       | :sup:`2`\ H, :sup:`13`\ C, :sup:`15`\ N                             | `Carreer et al. 2013 <https://doi.org/10.3390/metabo3040853>`_   | none                      |
-+--------------+----------+----------------------+---------------------------------------------------------------------+------------------------------------------------------------------+---------------------------+
-| IsoCorrectoR | No       | Low & UltraHigh only | All                                                                 | `GitHub project <https://github.com/chkohler/IsoCorrectoR>`__    | none                      |
-+--------------+----------+----------------------+---------------------------------------------------------------------+------------------------------------------------------------------+---------------------------+
-| ElemCor      | Yes      | All                  | :sup:`2`\ H, :sup:`13`\ C, :sup:`15`\ N, :sup:`18`\ O, :sup:`34`\ S | `GitHub project <https://github.com/4dsoftware/elemcor>`__       | Faulty at High-resolution |
-+--------------+----------+----------------------+---------------------------------------------------------------------+------------------------------------------------------------------+---------------------------+
-| IsoCor       | Yes      | All                  | All                                                                 | `GitHub project <https://github.com/MetaSys-LISBP/IsoCor_v2>`__  | none                      |
-+--------------+----------+----------------------+---------------------------------------------------------------------+------------------------------------------------------------------+---------------------------+
++--------------+----------+----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
+| Tool         | Has GUI? | MS resolution?       | Tracers?                                                            | Reference                                                            | Comment                   |
++==============+==========+======================+=====================================================================+======================================================================+===========================+
+| AccuCor      | No       | All                  | :sup:`2`\ H, :sup:`13`\ C, :sup:`15`\ N                             | `Su et al. 2017 <https://doi.org/10.1021/acs.analchem.7b00396>`_     | Faulty at High-resolution |
++--------------+----------+----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
+| PyNAC        | No       | UltraHigh only       | :sup:`2`\ H, :sup:`13`\ C, :sup:`15`\ N                             | `Carreer et al. 2013 <https://doi.org/10.3390/metabo3040853>`_       | none                      |
++--------------+----------+----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
+| IsoCorrectoR | No       | Low & UltraHigh only | All                                                                 | `Heinrich et al. 2018 <https://doi.org/10.1038/s41598-018-36293-4>`_ | none                      |
++--------------+----------+----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
+| ElemCor      | Yes      | All                  | :sup:`2`\ H, :sup:`13`\ C, :sup:`15`\ N, :sup:`18`\ O, :sup:`34`\ S | `GitHub project <https://github.com/4dsoftware/elemcor>`_            | Faulty at High-resolution |
++--------------+----------+----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
+| IsoCor v2    | Yes      | All                  | All                                                                 | `GitHub project <https://github.com/MetaSys-LISBP/IsoCor>`_          | none                      |
++--------------+----------+----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
 
 .. note:: If you would like your software to appear in this list, please get in touch with us.
 
@@ -74,6 +74,13 @@ when defining these formulas. Details on the elemental formulas to be declared i
 can be found in :ref:`Tutorial section on formulas <formulas>`.
 
 
+Is it possible to correct multiply-charged molecules?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Yes, IsoCor takes into account the charge when constructing the correction matrix. 
+The charge state of each metabolite should be declared in the corresponding database file, 
+as detailed in :ref:`Input data`.
+
+
 Should I tailor natural abundance of isotopes for my experiment?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The abundance of each isotope in

doc/index.rst

@@ -30,6 +30,7 @@ and can be downloaded as a `PDF file <https://readthedocs.org/projects/isocor/do
 * **correction of tracer purity**,
 * shipped as a library with both a **graphical and command line interface**,
 * mass-spectrometer and :ref:`resolution <resolution>` agnostic,
+* can be applied to singly- and multiply-charged ions
 * can be used with any tracer element (having two or more isotopes)
 * account for the contribution of derivatization steps (if any),
 * open-source, free and easy to install everywhere where Python 3 and pip run,

doc/showcase_isocor.ipynb

@@ -46,7 +46,7 @@
    "outputs": [],
    "source": [
     "corrector = isocor.mscorrectors.MetaboliteCorrectorFactory(\"C3PO\", tracer=\"13C\")\n",
-    "corrector_HR = isocor.mscorrectors.MetaboliteCorrectorFactory(\"C3PO\", tracer=\"13C\", resolution=1e4, mz_of_resolution=400)"
+    "corrector_HR = isocor.mscorrectors.MetaboliteCorrectorFactory(\"C3PO\", tracer=\"13C\", resolution=1e4, mz_of_resolution=400, charge=1)"
    ]
   },
   {
@@ -352,7 +352,7 @@
    "outputs": [],
    "source": [
     "# Let's do something silly\n",
-    "isocor.MetaboliteCorrectorFactory(\"C3PO\", '13C', resolution=0.1, mz_of_resolution= 400)"
+    "isocor.MetaboliteCorrectorFactory(\"C3PO\", '13C', resolution=0.1, mz_of_resolution= 400, charge=1)"
    ]
   },
   {
@@ -363,7 +363,7 @@
    "source": [
     "# it is forbidden to half-define a isocorrector\n",
     "try:\n",
-    "    isocor.MetaboliteCorrectorFactory(\"C3PO\", '13C', mz_of_resolution= 400)\n",
+    "    isocor.MetaboliteCorrectorFactory(\"C3PO\", '13C', mz_of_resolution= 400, charge=1)\n",
     "except Exception as e:\n",
     "    print(e.__class__, e)"
    ]

doc/tests.rst

@@ -6,7 +6,7 @@ Unit tests
 Isotope correction is a complex task and we use (some) unit tests to make sure
 that critical features are not compromised during development.
 
-A total of 307 tests has been designed to test IsoCor from individual steps
+A total of 318 tests has been designed to test IsoCor from individual steps
 (e.g. calculation of theoretical :ref:`mass fractions <mass fractions>` or correction matrices) to the
 entire correction process.
 Importantly, most of the tests compare intermediate (e.g. correction matrix) or
@@ -39,6 +39,16 @@ Isotopic clusters
    :members:
 
 
+Minimal mass difference to distinguish two isotopic species
+--------------------------------------------------------------------------------
+
+.. automodule:: isocor.tests.test_m_min_constant
+   :members:
+
+.. automodule:: isocor.tests.test_m_min_orbitrap
+   :members:
+
+
 Correction matrix
 --------------------------------------------------------------------------------
 

doc/tutorials.rst

@@ -49,6 +49,7 @@ The measurement file is a TSV file with one row by :ref:`isotopologue <isotopolo
 :derivative: The derivative name (optional) that represents the derivative moiety, as it is referred in the derivative database (*derivatives.dat*); e.g. "TMS".
 :isotopologue: The index of the peak measured, as an integer; e.g. '0' for the M0 peak that does not have any mass shift.
 :area: The measured :ref:`mass fractions <mass fractions>`; e.g. "4242.42".
+:resolution (optional): The MS resolution of the corresponding :ref:`mass fractions <mass fractions>`; e.g. "60000". Note the *all* mass fractions of a given isotopic cluster must have the same resolution.
 
 :download:`Example file <../isocor/data/Data_example.tsv>`.
 
@@ -116,9 +117,10 @@ This file stores **elemental formulas of the metabolites**.
 
 It is a TSV file with the following columns:
 
-:name: Metabolite name or abbreviation, e.g: "pyruvic acid" or "PYR".
+:name: Metabolite name or abbreviation; e.g. "pyruvic acid" or "PYR".
 :formula: Elemental formula of the metabolite moiety of the molecular entity that
-          gives rise to the measured :ref:`isotopic cluster <isotopic cluster>`; e.g: "C\ :sub:`3`\ H\ :sub:`4`\ O\ :sub:`3`\ ". See also :ref:`Formulas`.
+          gives rise to the measured :ref:`isotopic cluster <isotopic cluster>`; e.g. "C\ :sub:`3`\ H\ :sub:`4`\ O\ :sub:`3`\ ". See also :ref:`Formulas`.
+:charge: Charge state of the detected ion; e.g. "-1" for singly-charge ions or "-2" for doubly-charge ions.
 
 :download:`Example file <../isocor/data/Metabolites.dat>`.
 
@@ -135,9 +137,9 @@ MS analysis.
 
 It is a TSV file with the following columns:
 
-:name: Derivative name or abbrevation, e.g: "t-butyldimethyl-silylation" or "M-57".
+:name: Derivative name or abbrevation; e.g. "t-butyldimethyl-silylation" or "M-57".
 :formula: Elemental formula of the derivative moiety of the molecular entity that
-          gives rise to the measured :ref:`isotopic cluster <isotopic cluster>`; e.g: "Si\ :sub:`2`\ C\ :sub:`8`\ H\ :sub:`21`\ ". See also :ref:`Formulas`.
+          gives rise to the measured :ref:`isotopic cluster <isotopic cluster>`; e.g. "Si\ :sub:`2`\ C\ :sub:`8`\ H\ :sub:`21`\ ". See also :ref:`Formulas`.
 
 :download:`Example file <../isocor/data/Derivatives.dat>`.
 
@@ -174,7 +176,7 @@ in terms of isotopic tracer, sample processing,
 :Isotopic tracer: The tracer used for your experiment. Available tracers are imported from *isotopes.dat* database file.
 :Resolution: :ref:`Resolution` of the MS analyzer.
 :Resolution measured at: m/z at which the :ref:`resolution <resolution>` is given.
-:Resolution formula: The relationship between the operating :ref:`resolution <resolution>` and the resolution at m/z of the measured metabolite moiety depends on the MS analyzer, which has to be selected.
+:Resolution formula: The relationship between the operating :ref:`resolution <resolution>` and the resolution at m/z of the measured metabolite moiety depends on the MS analyzer, which has to be selected. If 'datafile' is selected, resolution should be provided for all mass fractions in the measurements file.
 :Tracer purity: Correct for the presence of unlabeled atoms at labeled positions, using the relative abundance of each isotope of the tracer element at labeled positions. Default is to assume a perfect purity (i.e. tracer isotope=1).
 :Correct natural abundance of the tracer element: Correct for natural abundance of the tracer element at unlabeled positions. Default is no correction.
 :Output data path: Path to the :ref:`Output data`. A log file with the same name will be created in the same directory, with a '.log' extension.
@@ -342,6 +344,9 @@ for FT-ICR and Orbitrap analyzers.
 We have also implemented an option to set a "constant resolution", i.e. which is considered to be
 independent of the m/z.
 
+Finally, the option "datafile" allows users to provide resolution of each mass fraction directly in the measurements file. Note that resolution must be the same for *all*
+peaks of a given isotopic cluster.
+
 .. note::
           If you want to use IsoCor with a high-resolution MS instrument
           that is not currently supported

isocor/__init__.py

@@ -4,7 +4,7 @@
 for conveniance.
 """
 
-__version__ = '2.0.5'
+__version__ = '2.1.0'
 
 from isocor.mscorrectors import MetaboliteCorrectorFactory
 from isocor.mscorrectors import LowResMetaboliteCorrector, HighResMetaboliteCorrector

isocor/base.py

@@ -64,7 +64,7 @@ class LabelledChemical(object):
                               "mass": [D('27.976926535'), D('28.976494665'), D('29.9737701')]}}
 
     def __init__(self, formula, tracer, derivative_formula, tracer_purity,
-                 correct_NA_tracer, data_isotopes, label=None):
+                 correct_NA_tracer, data_isotopes, charge=None, label=None):
         """Initialize a new LabelledChemical with its associated data."""
         # Load data_isotope first as it is critical for the other attributes
         self._data_isotopes = self.DEFAULT_ISODATA if data_isotopes is None else data_isotopes
@@ -80,6 +80,13 @@ def __init__(self, formula, tracer, derivative_formula, tracer_purity,
         self._str_formula = formula
         self._str_derivative_formula = derivative_formula if derivative_formula is not None else ""
         self._str_tracer_code = tracer
+        try:
+            self._charge = None if charge is None else abs(int(charge))
+            if self._charge == 0:
+                raise ValueError(
+                    "'charge' parameter should not be 0 ({})".format(charge))
+        except:
+            raise ValueError("'charge' parameter should be a non-null integer ({})".format(charge))
         # Protected attributes (user should not see them, but must stay available in sub-class)
         self._tracer_el, self._idx_tracer = self._parse_strtracer(
             self._str_tracer_code)
@@ -121,6 +128,11 @@ def derivative_formula(self):
                 self._str_derivative_formula)
         return self._derivative_formula
 
+    @property
+    def charge(self):
+        """int: absolute value of the charge of the metabolite."""
+        return self._charge
+
     @property
     def tracer_purity(self):
         """list: proportion of each isotope for the tracer element of the metabolite"""