Merge pull request #14 from NMRTeamTBI/dev

MultiNMRFit 2.1.3

README.md

@@ -1,7 +1,7 @@
 # MultiNMRFit
 
 [![Documentation Status](https://readthedocs.org/projects/multinmrfit/badge/?version=latest)](http://multinmrfit.readthedocs.io/?badge=latest)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Python 3.8+](https://img.shields.io/badge/python-%3E%3D3.8-blue)](https://www.python.org/downloads/release/python-380/)
 
 ## What is MultiNMRFit?
 
@@ -42,7 +42,7 @@ $ pip install multinmrfit
 Then, start the graphical interface with:
 
 ```bash
-$ multinmrfit
+$ nmrfit
 ```
 
 MultiNMRFit is also available as a Python library.

doc/conf.py

@@ -21,7 +21,7 @@
 author = 'Pierre Millard, Cyril Charlier'
 
 # The full version, including alpha/beta/rc tags
-release = "2.0.0"
+release = "2.1.3"
 
 # -- General configuration ---------------------------------------------------
 

doc/faq.rst

@@ -0,0 +1,83 @@
+Frequently asked questions (FAQ)
+================================
+
+I cannot start MultiNMRFit graphical user interface, can you help me?
+-------------------------------------------------------------------
+
+If you  installed MultiNMRFit following our standard procedure and that you are unable
+to start MultiNMRFit by opening a terminal and typing :samp:`nmrfit`, then there is indeed
+something wrong. Do not panic, we are here to help!
+Please follow this simple procedure:
+
+1. The first step of the debugging process will be to get a *traceback*, i.e.
+   a message telling us what is actually going wrong. You should see this message in the terminal you opened.
+
+2. Read the traceback and try to understand what is going wrong:
+
+   * If it is related to your system or your Python installation, you will need to ask some
+     help from your local system administrator or your IT department so they could
+     guide you toward a clean installation. Tell them that you wanted "to use the graphical
+     user interface of MultiNMRFit, a Python 3.8+ software" and what you did so
+     far (installation), give them the traceback and a link toward the
+     documentation. They should know what to do.
+   * If you believe the problem is in MultiNMRFit or that your local system administrator
+     told you so, then you probably have found a bug! We would greatly appreciate
+     if you could open a new issue on our `issue tracker  <https://github.com/NMRTeamTBI/MultiNMRFit/issues>`_.
+
+An error has been raised. What should I do?
+-------------------------------------------
+
+The first thing to do is to read the error message which might contain information on how to resolve it. If not, check the FAQ
+section (yes, this one) to see if the error has been explained in more depth. If the error persists or if you do not
+understand the error, please post it in the "issues" section on `GitHub
+<https://github.com/NMRTeamTBI/MultiNMRFit/issues>`_. We will try to respond as quickly as possible to solve your problem.
+
+Which model should I use?
+------------------------------------------------------------------
+
+The choice of the model depends on the signal you want to process. We provide a
+set of models in MultiNMRFit. If you have a specific signal that is not 
+included in the models, you can create your own model. We would be happy to 
+include it in the distribution of MultiNMRFit. Please post it in the "issues" section on `GitHub
+<https://github.com/NMRTeamTBI/MultiNMRFit/issues>`_.
+
+How can I check if my data has been fitted correctly?
+------------------------------------------------------------------
+
+The quality of the fit can be evaluated based on the plots of experimental vs 
+simulated data for the best fit, which should be as close as possible.
+
+My spectrum hasn't been correctly fitted. Why?
+------------------------------------------------------------------
+
+A possible reason to explain a bad fit is that you did not select the 
+right model(s). For instance, if you use a
+quartet model (i.e. with intensities 1:3:3:1) to fit a doublet of 
+doublet (i.e. with intensities 1:1:1:1), the spectrum will not be fitted correctly.
+
+In some situations, it may also be because some parameters have to be
+tweaked to help MultiNMRFit fit the spectrum, which results in
+obviously aberrant fits (e.g. with flat spectrum). If
+this situation happens, we suggest modifying the initial values of some parameters to obtain 
+a simulated spectrum as close as possible to the experimental one, and re-run the fitting. For
+more info on the parameters and how they may affect the fitting process,
+please refer to section :ref:`parameters`.
+
+If you think the problem is in MultiNMRFit, we would greatly appreciate 
+if you could open a new issue on our `issue tracker <https://github
+.com/NMRTeamTBI/MultiNMRFit/issues>`_.
+
+I have develop a new signal model, can you include it in MultiNMRFit distribution?
+--------------------------------------------------------------------------
+
+If you have developed a new signal model, we would be happy to include it in MultiNMRFit! 
+Open a new issue on our `issue tracker  <https://github.com/NMRTeamTBI/MultiNMRFit/issues>`_, 
+and let's discuss about your model and how we could include it! :)
+
+Examples of how to use MultiNMRFit programmatically can be found in the section :ref:`testing_the_model`, which offers demonstrations on running simulations and flux calculations.
+
+I would like a new feature.
+------------------------------------------------------------------
+
+We would be glad to improve MultiNMRFit. Please get in touch with us `here 
+<https://github.com/MetaSys-LISBP/multiNMRFit/issues>`_ so we could discuss your problem.

doc/index.rst

@@ -42,8 +42,7 @@ We strongly encourage you to read the :ref:`Tutorials` before using MultiNMRFit.
    :caption: Miscellaneous
 
    faq.rst
-   definitions.rst
-   library_doc.rst
+   library.rst
    license.rst
 
 .. todolist::

doc/library.rst

@@ -0,0 +1,9 @@
+.. _Library documentation:
+
+Library documentation
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   reference.rst

doc/models.rst

@@ -4,12 +4,40 @@
 Models
 ################################################################################
 
-The models used in MultiNMRFit can be found in the models folder. All models follow the same 
-format defined in:
+Signal models for some typical multiplets (singlet, doublet, triplet, quadruplet and doublet of doublet) are included 
+in multiNMRFit, and users can also build their own models.
+
+.. note:: We would be happy to broaden the types of models shipped with multiNMRFit. If you have developed a new model, it might be 
+          usefull and valuable to the NMR community! Please, keep in touch with us to discuss and see if we can include your 
+          model in the built-in models shipped with MultiNMRFit! :)
+
+The models used in MultiNMRFit can be found in the models folder, which is located in the multinmrfit package. To 
+find the path to the multinmrfit package, you can use the following command in a Python console:
 
 .. code-block:: python
-  base_model.py
 
-Users can add additionnal custom models following this format. We'll provide detailed information 
+    import multinmrfit
+    print(multinmrfit.__path__)
+
+All models follow the same 
+format. Have a look to `model_singlet.py <https://github.com/NMRTeamTBI/MultiNMRFit/blob/master/multinmrfit/models/model_singlet.py/>`_ as a template.
+
+Briefly, you will need to adapt the following functions:
+
+- **__init__**: initialize the signal model object with the following attributes:
+    - **name**: the name of the model.
+    - **description**: a brief description of the model.
+    - **peak_number**: the number of peaks in the signal.
+    - **default_params**: a list of the parameters that will be estimated by the fitting algorithm, with their default values and bounds.
+
+- **pplist2signal**: the function that will be used to built the signal from the peak list. It should return a dictionary containing the name of the signal, and optionaly some parameter values to be updated based on the peak list (if different from the default values).
+
+- **simulate**: the function that will be used to simulate the signal. It should return the simulated signal given the parameters and chemical shifts.
+
+Once you have developed a new model, you can add it to the models folder. The new model will be automatically detected by MultiNMRFit.
+
+.. note:: The file name must start with "model_".
+
+Users can add additionnal custom models following this format. We'll provide additional information 
 on the construction of new models soon! In the meantime, do not hesitate to grab us a message or 
-open an issue in our GitHub repository. 
+open an issue in our GitHub repository, we will be happy to help! 

doc/quickstart.rst

@@ -84,3 +84,5 @@ scripts:
 .. code-block:: python
 
   import multinmrfit
+
+.. seealso::  Have a look at our :ref:`API <Library documentation>` if you are interested in this feature.

doc/reference.rst

@@ -0,0 +1,32 @@
+API reference
+=============
+
+This module serves as reference for the different classes and associated methods of the MultiNMRFit package.
+
+:file:`spectrum.py`
+
+.. automodule:: multinmrfit.base.io
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: multinmrfit.base.spectrum
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: multinmrfit.base.process
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: multinmrfit.models.base_model
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: multinmrfit.models.model_singlet
+    :members:
+    :undoc-members:
+    :show-inheritance:
+