Merge branch 'main' into develop

docs/Low_level_api.ipynb

@@ -45,7 +45,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To illustrate how to use the incawrapper, we will use a small toy model with 5 reactions original used as a test model in [1,2]. As described in the Input data notebook, the incawrapper takes inputs in the form of pandas dataframes, which has to obey specific structure schema's. Let's have a look at the reactions data of our simple model."
+    "To illustrate how to use the INCAWrapper, we will use a small toy model with 5 reactions original used as a test model in [1,2]. As described in the Input data notebook, the INCAWrapper takes inputs in the form of pandas dataframes, which has to obey specific structure schema's. Let's have a look at the reactions data of our simple model."
    ]
   },
   {
@@ -426,7 +426,7 @@
    "metadata": {},
    "source": [
     "## Generate the MATLAB script\n",
-    "To prepare a model and data for 13C-MFA in INCA, we need to write a matlab script, which specifies to the model, the tracers and the measured data. The script is constructed incrementally, line by line, within an INCAScript object. When the incawrapper executes INCA, it essentially runs this script within the MATLAB environment. \n",
+    "To prepare a model and data for 13C-MFA in INCA, we need to write a matlab script, which specifies to the model, the tracers and the measured data. The script is constructed incrementally, line by line, within an INCAScript object. When the INCAWrapper executes INCA, it essentially runs this script within the MATLAB environment. \n",
     "\n",
     "To ensure the orderly execution of the MATLAB code, the structure of the INCAScript object is organized into discrete code blocks. Throughout this workflow, users progressively populate these code blocks one at a time until the script is fully formed. The central mechanism for this procedure involves employing the .add_to_block() method of the INCAScript object, in combination with a function that generates the corresponding MATLAB code string.\n",
     "\n",

docs/examples/Published_data_examples_C_necator.ipynb

@@ -17,7 +17,10 @@
     "work. If not, see <http://creativecommons.org/licenses/by/4.0/>.\n",
     "\n",
     "## Description of data\n",
-    "Alagesan and their colleagues aims to investigate the difference between heterotrophic and mixotrophic metabolism in Cupriavidus necator H16. They setup of three experimental condition differing in the available carbon sources. Two heterotrophic growth conditions using either [1-13C]fructose, or [1,2-13C]Glycerol as the sole carbon source and one mixotrophic condition using a mix of [1,2-13C]Glycerol and unlabelled CO2 as carbon source. All cultures are growth as batch cultures and samples were drawn during exponential growth phase."
+    "Alagesan and their colleagues aimed to investigate the difference between heterotrophic and mixotrophic metabolism in Cupriavidus necator H16. They set up of three experimental condition differing in the available carbon sources. Two heterotrophic growth conditions using either [1-13C]fructose, or [1,2-13C]Glycerol as the sole carbon source and one mixotrophic condition using a mix of [1,2-13C]Glycerol and unlabelled CO2 as carbon source. All cultures are growth as batch cultures and samples were drawn during exponential growth phase.\n",
+    "\n",
+    "## Description of the published analysis\n",
+    "Originally, OPENFLUX was used to analyze the data. Since this is a different software, we will not be able to reproduce the results exactly. However, we can use the same data and model to demonstrate how to perform an isotopically steady state 13C MFA analysis using the INCAWrapper."
    ]
   },
   {
@@ -181,7 +184,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We see that the model contains 74 reaction. The incawrapper uses the package Pandera to validate the input data. We can check if the reaction data correctly formatted according to the `ReactionsSchema`. We will wrap it in a try-except clause to create an output that is easier to interpret."
+    "We see that the model contains 74 reaction. The INCAWrapper uses the package Pandera to validate the input data. We can check if the reaction data correctly formatted according to the `ReactionsSchema`. We will wrap it in a try-except clause to create an output that is easier to interpret."
    ]
   },
   {
@@ -1646,7 +1649,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Finally, the MS measurement data frame is lacking a time and a measurement replicate column. The time is only used for Isotopically non-stationary MFA, but due to the way the incawrapper works it is a required input also for isotopically stationary MFA. In that case fill the time column with zeros. Regarding `measurement_replicate` this dataset contains a single replicate for per measurement, therefore we will simply fill the column with `1`."
+    "Finally, the MS measurement data frame is lacking a time and a measurement replicate column. The time is only used for Isotopically non-stationary MFA, but due to the way the INCAWrapper works it is a required input also for isotopically stationary MFA. In that case fill the time column with zeros. Regarding `measurement_replicate` this dataset contains a single replicate for per measurement, therefore we will simply fill the column with `1`."
    ]
   },
   {
@@ -1927,7 +1930,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The incawrapper has now created most of the INCA script. Currently, all options are at their default setting (see the INCA documentation see \\<your-inca-installation-folder\\>/doc/inca/class/@option/option.html). We discussed earlier that the MS data was all ready corrected for natural abundance, we will assume that this also included correction for unlabelled atoms. Therefore, we will specify two INCA settings: sim_na and sim_more. First, determines whether to simulate of the natural abundance of the labelled atoms, and the second of the unlabelled atoms. Additionally we will specify that the algorithm should do 100 restarts during the estimation algorithm."
+    "The INCAWrapper has now created most of the INCA script. Currently, all options are at their default setting (see the INCA documentation see \\<your-inca-installation-folder\\>/doc/inca/class/@option/option.html). We discussed earlier that the MS data was all ready corrected for natural abundance, we will assume that this also included correction for unlabelled atoms. Therefore, we will specify two INCA settings: sim_na and sim_more. First, determines whether to simulate of the natural abundance of the labelled atoms, and the second of the unlabelled atoms. Additionally we will specify that the algorithm should do 100 restarts during the estimation algorithm."
    ]
   },
   {
@@ -15732,7 +15735,7 @@
    "metadata": {},
    "source": [
     "## Analysis of the INCA results\n",
-    "Now that INCA has estimated the fluxes, we are ready to analyze the results. The incawrapper contains a INCAResults class, which is used to read and parse the matlab file produced by INCA. Simply provide the name of the .mat file as the first argument."
+    "Now that INCA has estimated the fluxes, we are ready to analyze the results. The INCAWrapper contains a INCAResults class, which is used to read and parse the matlab file produced by INCA. Simply provide the name of the .mat file as the first argument."
    ]
   },
   {
@@ -16129,7 +16132,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "It is clear that some of these estimates e.g. Histidine338 M3, fits the data quite poor. There are different ways of handling poor fitting measurements. It this case it it likely that the poor fit arise from mistake that we made when formulating the model or the data. Because this data comes from another research group, we may have missed some important details when reproducing the analysis. \n",
+    "It is clear that some of these estimates e.g. Histidine338 M3, fits the data quite poor. There are different ways of handling poor fitting measurements. It this case it it likely that the poor fit arise from mistake that we made when formulating the model or the data. Because this data comes from another research group, we may have missed some important details when reproducing the analysis. Also, a different software was used to analyze the data in the original article, which may have different assumptions and limitations.\n",
     "\n",
     "At the end we will shortly compare the our results the to results in figure 2 in the article. We will consider only the reactions around F6P as this is were the carbon which enters the cells is split between different metabolic pathways."
    ]
@@ -16200,9 +16203,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Also, here we see that our analysis does not agree with the literature values. This is expected because our fit is worse than the fit report.\n",
+    "Also, here we see that our analysis does not fully agree with the literature values. This is expected because our fit is worse than the fit reported in the literature, which can have many reasons. For example, the data we used was manually extracted from the article, which can lead to errors. Also, the original analysis was done with a different software, which may have different assumptions and limitations, and we may have missed some important details that might not be specified in the article when reproducing the analysis.\n",
     "\n",
-    "Even though we were not capable of reproducing the literature reports, we hope that this notebook can serve as a tutorial for how to use the incawrapper analyse data from 13C labelling experiments."
+    "Even though we were not capable of reproducing the literature reports, we hope that this notebook can serve as a tutorial for how to use the INCAWrapper analyse data from 13C labelling experiments."
    ]
   }
  ],

docs/examples/c_necator_simulated_data.ipynb

@@ -11,7 +11,7 @@
     "\n",
     "The model we use is from Alagesan, S., Minton, N.P. & Malys, N. 13C-assisted metabolic flux analysis to investigate heterotrophic and mixotrophic metabolism in Cupriavidus necator H16. Metabolomics 14, 9 (2018). https://doi.org/10.1007/s11306-017-1302-z, which is also used for one of the tutorials.\n",
     "\n",
-    "The simulation mimics a two parallel experiment where C. necator is grown with different labelled fructose and labelled glycerol. We simulated MS measurements of the amino acids and a few exchanges fluxes are measured. To increase the information about the systems we simulate measurements of CO2 exchange flux. To do this we added one additional reaction to the original model, i.e. CO2 -> CO2.ext. For more details about the simulation see the [simulation script](https://github.com/biosustain/incawrapper/blob/main/docs/examples/Literature%20data/Cupriavidus%20necator%2520%20Alagesan%202017/c_necator_simulation.py)."
+    "The simulation mimics a two parallel experiment where C. necator is grown with different labelled fructose and labelled glycerol. We simulated MS measurements of the amino acids and a few exchanges fluxes are measured. To increase the information about the systems we simulate measurements of CO2 exchange flux. To do this we added one additional reaction to the original model, i.e. CO2 -> CO2.ext. For more details about the simulation see the [simulation script](https://github.com/biosustain/incawrapper/blob/main/docs/examples/Literature%20data/Cupriavidus%20necator%20%20Alagesan%202017/c_necator_simulation.py)."
    ]
   },
   {

docs/examples/index.rst

@@ -1,12 +1,12 @@
 Example analysis notebooks
 ==========================
 
-We provide example Jupyter notebooks for how to the incawrapper. These notebooks
-represent different functionalities of incawrapper and can be used as templates for your own analysis.
+We provide example Jupyter notebooks for how to the INCAWrapper. These notebooks
+represent different functionalities of INCAWrapper and can be used as templates for your own analysis.
 If you have your data ready, you just have to adjust the paths and let the pre-written code
 do the work for you. Please don't forget to give us a shout out! (I.e., please cite us)
 
-If you have any questions, please contact the students currently working on incawrapper:
+If you have any questions, please contact the students currently working on INCAWrapper:
 You can find their mail addresses on the biosustain website
 
 - Matthias Mattanovich

docs/incawrapper_and_the_incagui.rst

@@ -1,24 +1,24 @@
-Using the incawrapper and the INCA GUI
+Using the INCAWrapper and the INCA GUI
 ================================================================================
 
-Though it is possible to use the incawrapper completely independent of the INCA GUI, there can be good reasons to use the INCA GUI combined with the incawrapper. For example, to manually verify that the model is setup as intended or run and diagnose the model. It is possible to open, modify and run the models that were created using the incawrapper in the INCA GUI. It is also possible to export the results from runs done through the GUI. However, it is not possible to export a INCAScript or the input data in the correct structure for the incawrapper from the INCA GUI.
+Though it is possible to use the INCAWrapper completely independent of the INCA GUI, there can be good reasons to use the INCA GUI combined with the INCAWrapper. For example, to manually verify that the model is setup as intended or run and diagnose the model. It is possible to open, modify and run the models that were created using the INCAWrapper in the INCA GUI. It is also possible to export the results from runs done through the GUI. However, it is not possible to export a INCAScript or the input data in the correct structure for the INCAWrapper from the INCA GUI.
 
 
-Opening models created with the incawrapper in the INCA GUI
+Opening models created with the INCAWrapper in the INCA GUI
 --------------------------------------------------------------------------------
 The function ``run_inca`` produce a .mat file that can be opened in the INCA GUI. This is done by selecting the *Open Model* or *Open Flux Map* in the INCA GUI. INCA will fail to open flux maps, i.e. results of an estimation algorithm, if the .mat files does not contain a simulation. Therefore, the argument ``run_simulation=True`` (default) must be used when calling ``define_runner()`` function.
 
 
 
 **Monte Carlo Results cannot be opened in the INCA GUI**
 
-At the moment, the incawrapper does not save Monte Carlo results in a format that can be read by the INCA GUI. Thus, results of Monte Carlo simulations done through the incawrapper can only be opened through the incawrapper.
+At the moment, the INCAWrapper does not save Monte Carlo results in a format that can be read by the INCA GUI. Thus, results of Monte Carlo simulations done through the INCAWrapper can only be opened through the INCAWrapper.
 
 
 Saving models and estimation runs from the INCA GUI
 --------------------------------------------------------------------------------
-The INCA GUI has several save options. The different options saves different data along with the model. All options saves a .mat file that can be read by the incawrapper using the the ``INCAResults`` class. The options are:
+The INCA GUI has several save options. The different options saves different data along with the model. All options saves a .mat file that can be read by the INCAWrapper using the the ``INCAResults`` class. The options are:
 
 * Save Model as: Saves only the model with the current settings.
 * Save Flux Map as: Saves the model and the results of the the estimation algorithm that was most recently run.
-* Save Simulation as: [Import into incawrapper is not implemented] Saves the model and the results of the simulation that was most recently run.
+* Save Simulation as: [Import into INCAWrapper is not implemented] Saves the model and the results of the simulation that was most recently run.

docs/index.rst

@@ -1,15 +1,15 @@
-Welcome to incawrapper's documentation!
+Welcome to INCAWrapper's documentation!
 =======================================
 
-incawrapper is a Python package which wraps around the matlab application INCA. INCA is a tool for
-13C metabolic flux analysis [1,2]. The incawrapper package allows to import data,
+INCAWrapper is a Python package which wraps around the matlab application INCA. INCA is a tool for
+13C metabolic flux analysis [1,2]. The INCAWrapper package allows to import data,
 setup the model and run INCA all from within Python. The results can be exported
 back to Python for further analysis and simply saved as .csv files. Furthermore, it is possible to 
 export results from INCA runs entirely done through the GUI to Python.
 
 The INCAWrapper code is freely available under an MIT License. However, to run INCA, you need a MATLAB and INCA licenses. Additionally, methods using COBRA tools need a GUROBI license. An INCA license is free for non-commercial use at `mfa.vueinnovations.com <mfa.vueinnovations.com>`_ and GUROBI offers free academic licenses at `gurobi.com <gurobi.com>`_. For more installation, please check our pre-requisites and installation guide.
 
-What can the incawrapper do for me?
+What can the INCAWrapper do for me?
 -----------------------------------
 * Provide a Python interface to use INCA 100% independent of the INCA GUI
 * Provide a data structure that can be imported to INCA
@@ -19,7 +19,7 @@ What can the incawrapper do for me?
 * Run both Isotopically Non-Stationary (INST) and Isotopically Stationary (IS) 13C-MFA
 * Estimate fluxes and confidence intervals through the following INCA algorithms: estimate, parameter continuation, and Monte Carlo sampling
 
-What can the incawrapper NOT do for me?
+What can the INCAWrapper NOT do for me?
 ---------------------------------------
 * Integration of NMR data
 * Simulation of experiments 

docs/input_data.ipynb

@@ -28,7 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The incawrapper does not directly read any files, but takes `pandas dataframes` as input. Thus, the user can make these dataframes using there preferred methods. In the end of this guide, we have a guide to write and read .csv or excel files to import them as correctly formatted dataframes.\n",
+    "The INCAWrapper does not directly read any files, but takes `pandas dataframes` as input. Thus, the user can make these dataframes using there preferred methods. In the end of this guide, we have a guide to write and read .csv or excel files to import them as correctly formatted dataframes.\n",
     "\n",
     "The data is validated using the Pandera python package. The validation covers both columns names and data types, thus column names must be specified exactly as shown in these examples. However the dataframes are allowed to contain more columns than the once required, though these extra columns are not parsed to INCA or to the INCA results object. To view the exact validation criteria for a specific data type inspect the data schema's found in the dataschema module.\n",
     "\n",
@@ -1781,7 +1781,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we have showed the expected structure of the input data you can move on to the next section to read about the how to use the incawrapper."
+    "Now we have showed the expected structure of the input data you can move on to the next section to read about the how to use the INCAWrapper."
    ]
   },
   {