fix: improved doc and fixed typos

doc/faq.rst

@@ -95,7 +95,7 @@ Should I correct the tracer purity for my experiment?
 Yes, if you know it. The purity of your tracer should be available from your
 provider of labeled compound.
 
-..seealso:: :ref:`Isotopic purity and natural abundance of the tracer`
+.. seealso:: :ref:`Isotopic purity and natural abundance of the tracer`
 
 
 What is the default value for the tracer purity?
@@ -108,13 +108,13 @@ Should I correct natural abundance of the tracer for my experiment?
 Yes, you should correct for the presence of isotopes at natural abundance in unlabeled
 positions of non-uniformally labeled nutrients.
 
-..seealso:: :ref:`Isotopic purity and natural abundance of the tracer`
+.. seealso:: :ref:`Isotopic purity and natural abundance of the tracer`
 
 
 How does IsoCor performs its corrections?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Please have a look at the examples in the Tutorials section.
-If you are looking for something more detailed, we invite you to review our source code [git depot](https://github.com/MetaSys-LISBP/IsoCor).
+If you are looking for something more detailed, we invite you to review our source code from our `git repository <https://github.com/MetaSys-LISBP/IsoCor>`_.
 Also, have a look at the logs in Verbose logs mode; all the intermediate results (correction vector used to construct the correction matrix, correction matrix, etc)
 will allow you to reproduce the results with pen and paper.
 
@@ -131,7 +131,7 @@ IsoCor calculates the mean enrichment (:math:`ME`) using the following formula:
 
 I would like a new feature.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-We would be glad to improve IsoCor. Please get in touch with us so we could discuss your problem. [issue tracker].
+We would be glad to improve IsoCor. Please `get in touch with us <https://github.com/MetaSys-LISBP/IsoCor/issues>`_ so we could discuss your problem.
 
 
 .. [IUPAC2016] Isotope-abundance variations and atomic weights of selected elements: 2016 (IUPAC Technical Report) https://doi.org/10.1515/pac-2016-0302

doc/index.rst

@@ -19,7 +19,9 @@ the mean enrichment (i.e. the mean isotopic content in the molecule) in metaboli
 It is one of the routine tools that we use at the `MetaSys team <http://www.lisbp.fr/en/research/integrated-metabolism-and-dynamics-of-metabolic-systems.html>`_ and `MetaToul platform <https://www6.toulouse.inra.fr/metatoul_eng/>`_ in isotopic studies of metabolic systems.
 
 The code is open-source, and available on `GitHub <https://github.com/MetaSys-LISBP/IsoCor/>`_ under a :ref:`GPLv3 license <license>`.
-This documentation can also be found online at Read the Docs (`https://isocor.readthedocs.io <https://isocor.readthedocs.io/>`_).
+
+This documentation is available on Read the Docs (`https://isocor.readthedocs.io <https://isocor.readthedocs.io/>`_)
+and can be downloaded as a PDF file.
 
 
 .. rubric:: Key features

doc/library_doc.rst

@@ -1,9 +1,13 @@
+.. _Library documentation:
+
 Library documentation
 ********************************************************************************
 
 IsoCor is also a Python module that you can import directly, for instance in
 Jupyter Notebooks or in your own software.
 
+.. warning:: This is an experimental feature.
+
 .. toctree::
    :maxdepth: 2
 

doc/quickstart.rst

@@ -19,11 +19,13 @@ Then, open a terminal (e.g. run *Anaconda Prompt* if you have installed Anaconda
 
 You are now ready to start IsoCor.
 
+If this method does not work, you should ask your local IT department "how to install a Python 3 package from PyPi"
+on your computer.
 
-Alternatives
+Alternatives & update
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you do not have permission to install software systemwide,
+If you know that you do not have permission to install software systemwide,
 you can install IsoCor into your user directory using the :samp:`--user` flag:
 
 .. code-block:: bash
@@ -38,7 +40,8 @@ If you already have a previous version of IsoCor installed, you can upgrade it t
   pip install --upgrade isocor
 
 
-Alternatively, you can also download all sources in a tarball from GitHub.
+Alternatively, you can also download all sources in a tarball from `GitHub <https://github.com/MetaSys-LISBP/IsoCor>`_,
+but it will be more difficult to update IsoCor later on.
 
 
 Usage
@@ -95,3 +98,16 @@ and important messages.
 
 .. seealso:: Tutorial :ref:`First time using IsoCor` has example data
             that you can use to test your installation.
+
+
+Library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IsoCor core code is also available as a library (a Python module) that you can import directly in your Python
+scripts:
+
+.. code-block:: python
+
+  import isocor
+
+.. seealso::  Have a look at our :ref:`library showcase <Library documentation>` if you are interested into this experimental feature.

doc/tutorials.rst

@@ -27,8 +27,8 @@ hence providing quantitative information on the incorporation of labeling into m
 The raw MS data and the information required to perform the correction (i.e. the natural abundance and exact mass of isotopes,
 and a list of metabolites and derivatives moieties with their elemental formulas) are provided in flat text files.
 
-At first start, IsoCor creates in the user directory a folder 'isocordb' containing example database files.
-These files can be edited and implemented according to the user's needs, as detailed below. Different database files can also be created 
+At first start, IsoCor creates in the user directory a IsoCor data folder `isocordb` containing default database files.
+These files can be edited and implemented according to the user's needs, as detailed below. Different database files can also be created
 (e.g. to have specific project-related databases), as detailed below.
 
 ..  _`Measurements file`:
@@ -50,12 +50,10 @@ The measurement file is a TSV file with one row by :ref:`isotopologue <isotopolo
 :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".
 
-.. note:: An example file is provided with IsoCor. It is created at the
-          first run of isocor in the folder '/user/isocordb'.
-
-.. only:: builder_html
+:download:`Example file <../isocor/data/Data_example.tsv>`.
 
-          :download:`Example file <../isocor/data/Data_example.tsv>`.
+.. note:: An example file is provided with IsoCor. It is created at the
+          first run of IsoCor in your user directory (`yourusername/isocordb/Data_example.tsv`).
 
 .. topic:: About derivatives
 
@@ -76,8 +74,9 @@ The exact mass and natural abundance of each isotope and the elemental formulas
 used for correction have to be defined carefully, otherwise the correction will be wrong.
 
 IsoCor rely on several flat-files to store this information.
-Pre-configured files are shipped with IsoCor. They are created in the user directory ('/user/isocordb/')
-at the first run of IsoCor and should be modified according to the user needs.
+Pre-configured files are shipped with IsoCor and created at the first run of IsoCor.
+Those database should be modified according to the user needs.
+They are **located in IsoCor data directory**, in user main directory: `yourusername/isocordb/`.
 
 .. note:: IsoCor is case sensitive; i.e. two metabolites
           or derivatives with the same name but different cases will
@@ -95,19 +94,19 @@ It is a TSV file with one row by isotope and the following columns:
 :mass: The exact mass of this isotope; e.g. "13.003354835" for 13C.
 :abundance: The relative abundance of this isotope normalized to 1; e.g. "0.0107" for 13C.
 
-.. note::
-            *'Isotopes.dat' must be in '/user/isocordb'*. An isotope database is created at the first run of isocor and can be edited according to the user needs.
+:download:`Example file <../isocor/data/Isotopes.dat>`.
 
-.. warning::
-            **All** elements should be declared, including elements with only one isotope (with its abundance set to 1).
-            This is required for accurate correction of high-resolution data.
+A pre-configured isotopes database can be found in IsoCor data directory and should be edited according to the users needs.
+It is located in user main directory at `yourusername/isocordb/Isotopes.dat`.
 
-.. warning:: For elements with gaps in the list of nominal mass of isotopes (e.g. for sulfur with isotopes 33S, 34S, 36S, but not 35S),
-          declare the missing isotope(s), with the exact mass set at the missing integer(s), and an abundance of 0 (as done in the example file for sulfur).
+.. warning:: The isotopes database is always loaded from IsoCor data directory,
+             i.e. from `yourusername/isocordb/Isotopes.dat`.
 
-.. only:: builder_html
+.. note:: **All** elements should be declared, including elements with only one isotope (with its abundance set to 1).
+          This is required for accurate correction of high-resolution data.
 
-          :download:`Example file <../isocor/data/Isotopes.dat>`.
+.. note:: For elements with gaps in the list of nominal mass of isotopes (e.g. for sulfur with isotopes 33S, 34S, 36S, but not 35S),
+          declare the missing isotope(s), with the exact mass set at the missing integer(s), and an abundance of 0 (as done in the example file for sulfur).
 
 
 *Metabolites database (Metabolites.dat)*
@@ -121,12 +120,11 @@ It is a TSV file with the following columns:
 :formula: Elemental formula of the metabolite moiety of the molecular entity that
           gives rise to the measured :ref:`isotopic cluster <isotopic cluster>`; e.g: "C3H4O3". See also :ref:`Formulas`.
 
-.. note::
-            A metabolites database is created at the first run of isocor in '/user/isocordb'.
+:download:`Example file <../isocor/data/Metabolites.dat>`.
 
-.. only:: builder_html
+A pre-configured metabolites database can be found in IsoCor data directory and should be edited according to the users needs.
+It is located in user main directory at `yourusername/isocordb/Metabolites.dat`.
 
-          :download:`Example file <../isocor/data/Metabolites.dat>`.
 
 *Derivatives database (Derivatives.dat)*
 --------------------------------------------------------------------------------
@@ -141,25 +139,27 @@ It is a TSV file with the following columns:
 :formula: Elemental formula of the derivative moiety of the molecular entity that
           gives rise to the measured :ref:`isotopic cluster <isotopic cluster>`; e.g: "Si2C8H21". See also :ref:`Formulas`.
 
-.. note::
-            A derivatives database is created at the first run of isocor in '/user/isocordb'.
-
+:download:`Example file <../isocor/data/Derivatives.dat>`.
 
-.. only:: builder_html
+A pre-configured derivatives database can be found in IsoCor data directory and should be edited according to the users needs.
+It is located in the user main directory at `yourusername/isocordb/Derivatives.dat`.
 
-          :download:`Example file <../isocor/data/Derivatives.dat>`.
 
 *Custom databases*
 --------------------------------------------------------------------------------
 
-Files *Derivatives.dat* and *Metabolites.dat* are created at the first run of isocor in '/user/isocordb'. These files can be edited according to the users needs,
+IsoCor data directory is created at the first run of IsoCor with pre-configured
+databases files in the user main directory (`yourusername/isocordb/`).
+These files should be edited according to the users needs,
 e.g. to add some metabolites and derivatives formulas.
 
-Users can also define different metabolite and derivative databases (e.g. specific to each project), in this case the
-user's defined database files ('Metabolites.dat' and 'Derivatives.dat') should be in a single folder that can be selected in IsoCor GUI.
+Alternatively, users can select at runtime a custom folder from which metabolites
+and derivatives will be loaded ('Metabolites.dat' and 'Derivatives.dat') with
+the 'Databases Path' button.
+It is especially useful to define project-based database files.
 
-.. note::
-            'Isotopes.dat' is always loaded from '/user/isocordb' and will not be loaded from the custom databases folder.
+.. warning::
+   Importantly, 'Isotopes.dat' is always loaded from IsoCor data directory ('yourusername/isocordb/Isotopes.dat') and will not be loaded from a custom databases folder.
 
 ..  _CorrectionOptions:
 

isocor/ui/isoCorCli.py

@@ -181,7 +181,7 @@ def parseArgs():
     parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS,
                                      description='correction of MS data for naturally occurring isotopes')
 
-    parser.add_argument("inputdata", help="data file to process")
+    parser.add_argument("inputdata", help="measurements file to process")
     parser.add_argument("-M", type=str, help="path to metabolites database")
     parser.add_argument("-D", type=str, help="path to derivatives database")
     parser.add_argument("-I", type=str, help="path to isotopes database")