Merge pull request #59 from MetaSys-LISBP/dev

Update to 3.4.0

.github/workflows/tests.yml

@@ -9,11 +9,11 @@ jobs:
     runs-on: ${{ matrix.os}}
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: [ '3.8', '3.9', '3.10', '3.11']
+        os: [ubuntu-latest, windows-latest]
+        python-version: [ '3.9', '3.10', '3.11']
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{matrix.python-version}}
         uses: actions/setup-python@v4
         with:

.gitignore

@@ -1,13 +1,8 @@
 /venv/
-physiofit/__pycache__/__init__.cpython-310.pyc
-physiofit/__pycache__/__main__.cpython-310.pyc
-physiofit/__pycache__/logger.cpython-310.pyc
-physiofit/base/__pycache__/__init__.cpython-310.pyc
-physiofit/base/__pycache__/fitter.cpython-310.pyc
-physiofit/base/__pycache__/io.cpython-310.pyc
+physiofit/__pycache__/
+physiofit/base/__pycahe__/
 physiofit/last_version.txt
-physiofit/ui/__pycache__/__init__.cpython-310.pyc
-physiofit/ui/__pycache__/cli.cpython-310.pyc
+physiofit/ui/__pycache__/
 physiofit.egg-info/dependency_links.txt
 physiofit.egg-info/entry_points.txt
 physiofit.egg-info/PKG-INFO
@@ -16,3 +11,4 @@ physiofit.egg-info/SOURCES.txt
 physiofit.egg-info/top_level.txt
 /versions publi/
 /physiofit/data/
+/docs/_build/ 

README.md

@@ -25,14 +25,16 @@ Detailed documentation can be found online at Read the Docs
 ## Key features
 
    * **calculation of growth rate and extracellular (uptake and production) fluxes**,
-   * **a set of steady-state and dynamic models** are shipped with PhysioFit,
+   * a set of **steady-state and dynamic models**,
    * **tailor-made models** can be constructed by users,
-   * Monte-Carlo sensitivity analysis to **estimate the precision on the calculated fluxes**,
+   * Monte-Carlo sensitivity analysis to **estimate the precision of the calculated fluxes**,
    * **evaluation of the goodness of fit and visual inspection of the fitted curves**,
+   * calculation of the Akaike information criterion to **guide users to identify the most appropriate model**,
    * shipped as a **library** with both a **graphical** and a **command line** interface,
    * **open-source, free and easy to install** everywhere where Python 3 and pip run,
    * **biologist-friendly**.
 
+
 ## Quick-start
 PhysioFit requires Python 3.9 or higher and run on all platforms.
 Please check [the documentation](https://physiofit.readthedocs.io/en/latest/quickstart.html) for complete

docs/conf.py

@@ -24,7 +24,6 @@
 # The full version, including alpha/beta/rc tags
 release = __version__
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -52,7 +51,6 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -74,11 +72,11 @@
 
     # remove blank pages (between the title page and the TOC, etc.)
     'classoptions': ',openany,oneside',
-    'babel' : '\\usepackage[english]{babel}',
+    'babel': '\\usepackage[english]{babel}',
 
     # Additional stuff for the LaTeX preamble.
     'preamble': r'''
       \usepackage{hyperref}
       \usepackage{upquote}
       '''
-      }
+}

docs/faq.rst

@@ -4,36 +4,45 @@ Frequently asked questions (FAQ)
 How are fluxes calculated?
 ------------------------------------------------------------------
 
-We provide details on the flux calculation approach implemented in PhysioFit in the :doc:`method` section.
+We provide details on the flux calculation approach implemented in PhysioFit
+in the :doc:`method` section.
 
 How many measurements should I use to calculate fluxes?
 ------------------------------------------------------------------
 
-As in any model-based fitting procedure, more data usually means more accurate and precise flux estimates. The minimal number of 
-measurements depend on the model used for flux calculation. For instance, for steady-state built-in models provided with PhysioFit, we recommend using
-at least 6 to 8 time points, which should provide reliable and meaningful estimates in most situations.
+As in any model-based fitting procedure, more data usually means more
+accurate and precise flux estimates. The minimal number of measurements
+depend on the model used for flux calculation. For instance, for
+steady-state built-in models provided with PhysioFit, we recommend using at
+least 6 to 8 time points, which should provide reliable and meaningful
+estimates in most situations.
 
-Still, the exact answer to this question strongly depends on the uptake/production/growth rates of your (micro)organism
-in the conditions you are investigating, on the sampling time interval, on the questions you are addressing, on the model used for flux calculation, and on
-many other parameters! You can make some tests by calculating fluxes from (published or theoretical) datasets similar
-to those you have in mind.
+Still, the exact answer to this question strongly depends on the
+uptake/production/growth rates of your (micro)organism in the conditions you
+are investigating, on the sampling time interval, on the questions you are
+addressing, on the model used for flux calculation, and on many other
+parameters! You can make some tests by calculating fluxes from (published or
+theoretical) datasets similar to those you have in mind.
 
 Can I calculate fluxes in case of missing values?
 ------------------------------------------------------------------
 
-Yes, fluxes can still be calculated if some measurement(s) are missing. In this case, let empty the corresponding field
-of the input data file.
+Yes, fluxes can still be calculated if some measurement(s) are missing. In
+this case, leave empty the corresponding field of the input data file.
 
 ..  _`conc units`:
 
 What units should be used for input data?
 -----------------------------------------
 
-Input data (biomass concentration, metabolites concentrations, and time) can be provided to PhysioFit using any unit.
-Still, we recommand to use units for which values are as close to unity as possible to ensure numerical stability (e.g.
-3 mM instead of 3.10\ :sup:`-3` M). Importantly, units of the estimated fluxes depend on units of time and metabolites and biomass
-concentrations. The concentration of different metabolites can be provided using different units, but a single unit
-must be used for all measurements of a given metabolite.
+Input data (biomass concentration, metabolites concentrations, and time) can
+be provided to PhysioFit using any unit. Still, we recommend using units
+for which values are as close to unity as possible to ensure numerical
+stability (e.g. 3 mM instead of 3.10\ :sup:`-3` M). Importantly, units of
+the estimated fluxes depend on units of time and metabolites and biomass
+concentrations. The concentration of different metabolites can be provided
+using different units, but a single unit must be used for all measurements
+of a given metabolite.
 
 .. seealso:: :ref:`flux units` 
 
@@ -61,49 +70,75 @@ What parameters values should I use?
 
 Details on PhysioFit parameters can be found in the :doc:`usage` section.
 
-How can I check if my data have been fitted correctly?
+Which model should I use?
 ------------------------------------------------------------------
 
-The quality of the fit can be evaluated based on:
+The choice of the model depends on the biological question you are addressing,
+the data you have, and the assumptions you are willing to make. We provide a
+set of models in PhysioFit, each with its own assumptions and requirements.
 
-    * the plots of experimental vs simulated data for the best fit, which should be as close as possible,
-    * the χ² statistical test results given in the log file (see below for help on interpreting the results).
+As a starting point, we recommend using the most relevant model based on
+the type of experiment you have conducted. Begin with the simplest model that
+fits your data and evaluate the quality of the fit based on the χ² test
+results and the plots of experimental vs. simulated data. If the fit is
+not satisfactory, you may try more complex models. However, keep in mind
+that more complex models often require more data, include more assumptions,
+and may lead to overfitting.
 
-.. seealso:: :ref:`chi2 test` and :ref:`bad fit` 
+If different models fit your data, a good practice for comparing them
+is to use the AIC (Akaike Information Criterion). For more information, please
+refer to the section "Model comparison" from the :doc:`method` page.
 
-..  _`chi2 test`:
 
-What is a χ² test?
+How can I check if my data has been fitted correctly?
 ------------------------------------------------------------------
 
-A χ² test describes how well a model fits a set of observations. Measures of goodness of fit typically summarize the discrepancy between observed values and the values expected under the model used in PhysioFit (see the :doc:`method` section). It is calculated as the sum of differences between measured and simulated values, each squared and divided by the simulated value.
-A good fit corresponds to small differences between measured and simulated values, thereby the χ² value is low. In contrast, a bad fit corresponds to large differences between simulations and measurements, and the χ² value is high. 
+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,
+    * the χ² statistical test results given in the stat ouput file (see below
+      for help on interpreting the results).
+
+.. seealso:: :ref:`chi2 test` and :ref:`bad fit`
 
-The resulting χ² value can then be compared with a χ² distribution to determine the goodness of fit. The p-value of one-tail χ² test is calculated by PhysioFit from the best fit and is given in the log file (have a look to the :doc:`usage` section). A p-value close to 0 means poor fitting, and a p-value close to 1 means good fitting (keeping in mind that a p-value very close to 1 can be an evidence that standard deviations might be overestimated). A 
-p-value between 0.95 and 1 means the model fits the data good enough with respect to the standard deviations provided (at a 95% confidence level). PhysioFit provides an explicit meassage stating wether the flux data are satisfactorily fitted or not (at a 95% confidence interval).
 
 ..  _`bad fit`:
 
 My data hasn't been correctly fitted. Why?
 ------------------------------------------------------------------
 
-A possible reason to explain a bad fit is that standard deviations on measurements (concentration biomass and metabolites) is under-estimated, thereby making the χ² test too stringent. In this case, plots of measured and fitted data should be in agreement. Reliable estimated of standard deviation on measurements must be provided to PhysioFit (have a look to the :doc:`usage` section to see how to check and adjust this parameter).
-
-Another possible reason to explain a bad fit is that a key asumption of the flux calculation method is not respected. For instance, 
-if you use a steady-state model shipped with PhysioFit, cells might not be strictly in metabolic steady-state, i.e. with 
-constant fluxes during the whole experiment. If this key asumption does not occur (e.g. cells are continuously adapting 
-to their environment and fluxes change over time), PhysioFit will not be able to fit the data satisfactorily. In this case, 
-evaluate wether the deviation is significant or not (e.g. based on the detailed χ² statistics or on the plot of fitted vs 
-measured data), and evaluate the potential biases that would be introduced by interpreting (or not) these flux values.
-
-In rare situations, it may also be because some parameters have to be tweaked to
-help PhysioFit fitting the measurements, which results in obviously aberrant fits (e.g. with flat 
-time-course profiles for all metabolites). This might happen for instance if some measurements are 
-provided in units far from unity (e.g. 1.10\ :sup:`-5` M instead of 10 µM). If this situation happens, we suggest modifying the initial values of fluxes, or changing the units of input data, and re-run the flux calculation. For more info on the run parameters and how they may affect the fitting process,
+A possible reason to explain a bad fit is that standard deviations on
+measurements (concentration biomass and metabolites) is under-estimated,
+thereby making the χ² test too stringent. In this case, plots of measured and
+fitted data should be in agreement. Reliable estimated of standard deviation
+on measurements must be provided to PhysioFit (have a look to the :doc:`usage`
+section to see how to check and adjust this parameter).
+
+Another possible reason to explain a bad fit is that a key asumption of the
+flux calculation method is not respected. For instance, if you use a
+steady-state model shipped with PhysioFit, cells might not be strictly in
+metabolic steady-state, i.e. with constant fluxes during the whole
+experiment. If this key asumption does not occur (e.g. cells are continuously
+adapting to their environment and fluxes change over time), PhysioFit will
+not be able to fit the data satisfactorily. In this case, evaluate wether
+the deviation is significant or not (e.g. based on the detailed χ²
+statistics or on the plot of fitted vs measured data), and evaluate the
+potential biases that would be introduced by interpreting (or not) these
+flux values.
+
+In rare situations, it may also be because some parameters have to be
+tweaked to help PhysioFit fit the measurements, which results in
+obviously aberrant fits (e.g. with flat time-course profiles for all
+metabolites). This might happen for instance if some measurements are
+provided in units far from unity (e.g. 1.10\ :sup:`-5` M instead of 10 µM). If
+this situation happens, we suggest modifying the initial values of fluxes,
+or changing the units of input data, and re-run the flux calculation. For
+more info on the run parameters and how they may affect the fitting process,
 please refer to section :ref:`physiofit parameters`.
 
-If you believe the problem is in PhysioFit, we would greatly appreciate 
-if you could open a new issue on our `issue tracker  <https://github.com/MetaSys-LISBP/PhysioFit/issues>`_.
+If you think the problem is in PhysioFit, we would greatly appreciate 
+if you could open a new issue on our `issue tracker <https://github
+.com/MetaSys-LISBP/PhysioFit/issues>`_.
 
 I cannot start PhysioFit graphical user interface, can you help me?
 -------------------------------------------------------------------
@@ -121,8 +156,9 @@ Please follow this simple procedure:
    * 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 PhysioFit, a Python 3.6 software" and what you did so far (installation),
-     give them the traceback and a link toward the documentation. They should know what to do.
+     user interface of PhysioFit, a Python 3.9 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 PhysioFit 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/MetaSys-LISBP/PhysioFit/issues>`_.

docs/index.rst

@@ -19,10 +19,11 @@ additional tailor-made models can be implemented by users.
 **PhysioFit includes the following features:**
 
    * **calculation of growth rate and extracellular (uptake and production) fluxes**,
-   * **a set of steady-state and dynamic models** are shipped with PhysioFit,
+   * a set of **steady-state and dynamic models**,
    * **tailor-made models** can be constructed by users,
    * Monte-Carlo sensitivity analysis to **estimate the precision of the calculated fluxes**,
    * **evaluation of the goodness of fit and visual inspection of the fitted curves**,
+   * calculation of the Akaike information criterion to **guide users to identify the most appropriate model**,
    * shipped as a **library** with both a **graphical** and a **command line** interface,
    * **open-source, free and easy to install** everywhere where Python 3 and pip run,
    * **biologist-friendly**.