Dev

docs/cite.rst

@@ -7,4 +7,4 @@ Thank you for using PhysioFit and citing us in your work! It means a lot to us a
 
   Le Grégam L., Guitton Y., Bellvert F., Jourdan F., Portais J.C., Millard P.
 
-  In preparation for publication
+  **doi**: https://doi.org/10.1101/2023.10.12.561695

docs/faq.rst

@@ -4,16 +4,17 @@ Frequently asked questions (FAQ)
 How are fluxes calculated?
 ------------------------------------------------------------------
 
-We provide details on the flux calculation approach implemented in PhysioFit in the :doc:`models` 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 means more accurate and precise flux estimates. We recommend using
-at least 6 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, and on
+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.
 
@@ -30,7 +31,7 @@ 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 3e3 µM). Importantly, units of the estimated fluxes depend on units of time and metabolites and biomass
+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.
 
@@ -42,8 +43,8 @@ What are the flux units?
 ------------------------
 
 Flux units depend on the units of time and concentrations (of biomass and metabolites) provided in the input 
-data file. For instance, if biomass units are in grams of cell dry weight by liter (gDW/L), metabolite concentrations are in millimolar (mM) and time is 
-in hours (h), the estimated fluxes will be in mmol/gDW/h. Units should thus be carefully selected, and calculated fluxes must be interpreted consistently with the concentration units.
+data file. For instance, if biomass units are in grams of cell dry weight by liter (g\ :sub:`CDW`/L), metabolite concentrations are in millimolar (mM) and time is 
+in hours (h), the estimated fluxes will be in mmol/g\ :sub:`CDW`/h. Units should thus be carefully selected, and calculated fluxes must be interpreted consistently with the concentration units.
 
 .. seealso:: :ref:`conc units` 
 
@@ -65,7 +66,7 @@ How can I check if my data have 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.
+    * 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).
 
 .. seealso:: :ref:`chi2 test` and :ref:`bad fit` 
@@ -88,10 +89,17 @@ 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. Typically, 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.
+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. 1e-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,
+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,
 please refer to section :ref:`physiofit parameters`.
 
 If you believe the problem is in PhysioFit, we would greatly appreciate 
@@ -119,6 +127,12 @@ Please follow this simple procedure:
      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>`_.
 
+I have develop a new model, can you include it in PhysioFit distribution?
+--------------------------------------------------------------------------
+
+If you have developed a new flux model, we would be happy to include it in PhysioFit! Open a new issue on our `issue tracker  <https://github.com/MetaSys-LISBP/PhysioFit/issues>`_, 
+and let's discuss about your model and how we could include it! :)
+
 I would like a new feature.
 ------------------------------------------------------------------
 

docs/index.rst

@@ -12,20 +12,19 @@ Welcome to PhysioFit documentation!
 
 **PhysioFit is a scientific tool designed to quantify cell growth parameters and uptake & production fluxes**
 
-Fluxes are estimated using various mathematical models by fitting time-course measurements of the concentration of
-cells and extracellular substrates and products. PhysioFit v3 includes by default the most common growth models, and
-additional models can be implemented by users.
+Fluxes are estimated using mathematical models by fitting time-course measurements of the concentration of
+cells and extracellular substrates and products. PhysioFit is shipped with some common growth models, and
+additional tailor-made models can be implemented by users.
 
 **PhysioFit includes the following features:**
 
    * **calculation of growth rate and extracellular (uptake and production) fluxes**,
-   * default models for quantifying parameters in steady-state conditions (with and without lag & metabolite degradation
-     over time),
-   * **user-defined growth models**,
+   * **a set of steady-state and dynamic models** are shipped with PhysioFit,
+   * **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**,
-   * shipped as a **library** with both a **graphical** and **command line** interface,
-   * open-source, free and easy to install everywhere where Python 3 and pip run,
+   * 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**.
 
 It is one of the routine tools that we use at the

docs/installation.rst

@@ -4,15 +4,22 @@ Installation
 Installation
 -----------------
 
-PhysioFit requires Python 3.9 or higher and can run on most systems supporting Python3 (Windows, MacOS and Linux). If you do not have a Python environment
-configured on your computer, we recommend that you follow the instructions from `Anaconda <https://www.anaconda.com/download/>`_.
+PhysioFit requires Python 3.9 or higher and run on all platforms supporting Python3 (Windows, MacOS and Linux).
+If you do not have a Python environment configured on your computer, we recommend that you follow the instructions
+from `Anaconda <https://www.anaconda.com/download/>`_.
 
 To install PhysioFit using Python's built-in installer, you can just run the following command in a terminal:
 
 .. code-block:: bash
 
     pip install physiofit
 
+Use :samp:`conda` to install from conda:
+
+.. code-block:: bash
+
+    conda install physiofit -c bioconda
+
 .. tip::  We recommend the creation of isolated environments for each python tool you install in your system using the python built-in `venv <https://docs.python.org/3/library/venv.html>`_ package or `Anaconda <https://www.anaconda.com/products/individual>`_.
 
 If this method does not work, you should ask your local system administrator or
@@ -38,4 +45,5 @@ Once the package is installed, you can update it using the following command:
 
     pip install -U physiofit
 
-Alternatively, you can also download all sources in a tarball from `GitHub <https://github.com/MetaSys-LISBP/PhysioFit>`_, but it will be more difficult to update PhysioFit later on.
+Alternatively, you can also download all sources in a tarball from `GitHub <https://github.com/MetaSys-LISBP/PhysioFit>`_,
+but it will be more difficult to update PhysioFit later on.

docs/method.rst

@@ -1,12 +1,59 @@
 Method
-=======
+===============
+
+Overview
+*********
+
+Fluxes (exchange fluxes of a metabolite M\ :sub:`i`, qM\ :sub:`i` ; growth rate, µ), initial concentrations of species (biomass, X ; 
+metabolites, M\ :sub:`i`) and possibly other growth parameters (e.g. lag time) are estimated by fitting time-course measurements of
+metabolite and biomass concentrations, as detailed below.
+
+Flux values provided by PhysioFit correspond the best fit. A global sensitivity analysis (Monte-Carlo approach) is
+available to evaluate the precision of the estimated fluxes (mean, median, standard deviation, 95% confidence
+intervals), plots are generated for visual inspection of the fitting quality, and a χ² test is performed to assess the
+statistical goodness of fit.
+
+.. _method_models:
+
+Models
+******
+
+Models are at the heart of the flux calculation approach implemented in PhysioFit. A flux model contains i) equations that describe the dynamics of biomass and 
+metabolite concentrations as function of different parameters (used to simulate time-course metabolite concentrations) and ii) the list of all parameters (including fluxes) with their 
+(default) initial values and bounds (used for flux calculation). 
+
+Different models are shipped with PhysioFit, and tailor-made models can be provided by users, as detailed in the :doc:`models` section.
+
+.. _optimization_process:
 
 Flux calculation
-*****************
+************************
+
+First, PhysioFit construct a model that used to simulate the dynamics of the concentration of biomass and metabolites (substrates and products) provided in the input data. 
+Model parameters (such as fluxes, growth rate, and initial concentrations of biomass and metabolites) are then estimated by fitting experimental metabolite and biomass dynamics. PhysioFit 
+minimizes the following cost function:
+
+.. math:: residuum = \sum_{i} (\dfrac{sim_{i}-meas_{i}}{sd_{i}})^2
+
+where :math:`sim` is the simulated data, :math:`meas` denotes measurements, and :math:`sd` is the 
+standard deviation on measurements.
 
-To write...
+For this optimization step, PhysioFit uses the Scipy's Differential evolution method to approximate the solution, 
+and the best solution is polished using the L-BFGS-B method (see
+`scipy.optimize <https://docs.scipy.org/doc/scipy/reference/optimize.html>`_ for more information on the optimization
+process).
 
-Sensitivity Analysis
+Goodness-of-fit evaluation
+**************************
+
+PhysioFit performs a χ² test to assess the goodness of fit. Have a look at the :doc:`faq` section for 
+more details on the interpretation of the khi2 test results.
+
+Sensitivity analysis
 *********************
 
-To write...
+To determine the precision on the fit and on the estimated parameters (including fluxes), PhysioFit performs a Monte Carlo analysis. Briefly, several 
+noisy datasets are generated from the simulated dynamics of the best fit (i.e defined in parameter :samp:`number of iterations` of the GUI) and calculate fluxes and other growth 
+parameters for each of these synthetic datasets. This enables PhysioFit to compute statistics (mean, median, standard deviation and 95% confidence interval) for 
+each parameter. We recommend always running a sensitivity analysis when using PhysioFit.
+