INCA¶

Prerequisites¶

The BFAIR MFA tools use the software INCA in MATLAB and subsequently re-import its output before processing the data. To make full use of these tools you will have to have both INCA and MATLAB installed on your system.

INCA¶

“INCA (Isotopomer Network Compartmental Analysis) is a MATLAB-based software package for isotopomer network modeling and metabolic flux analysis.” You can read more about it in Young, 2014 You have to get a free academic licence for INCA from the Vanderbilt University website (the second option is the relevant one) and install it. Note the path to the base directory of your INCA installation, you will need it later.

MATLAB¶

Get a free academic licence and install MATLAB from the mathworks website. Then, install the engine API following the guide provided under this link. In short, you will have to go to your MATLAB root folder (find your installation and open that folder) and, in the command line, go to

>>> cd /extern/engines/python

and run

>>> python setup.py install

That should do the trick.

Modules¶

BFAIR.mfa.INCA.INCA_script_generator.script_generator_descr¶

A class to write and execute an INCA script in MATLAB.

Examples

>>> from BFAIR.INCA import INCA_script
After pre-processing the input, the script can either be generated all at once
>>> INCA_script = INCA_script()
>>> script = INCA_script.script_generator(
        modelReaction_data_I,
        atomMappingReactions_data_I,
        atomMappingMetabolite_data_I,
        measuredFluxes_data_I,
        experimentalMS_data_I,
        tracer_I
    )
Or sequentially (not shown)
After generation, the script can be saved
>>> INCA_script.save_INCA_script(script, "testscript")
Same goesfor the runner script
>>> runner = INCA_script.runner_script_generator('TestFile', 10)
>>> INCA_script.save_runner_script(runner=runner, scriptname="testscript")
With working INCA and MATLAB installations and an active MATLAB engine, the script can be executed in python  # noqa E501
>>> INCA_base_directory = "/Users/Username/Documents/INCAv1.9"
>>> script_folder = %pwd
>>> matlab_script = "testscript"
>>> runner_script = matlab_script + "_runner"
>>> INCA_script.run_INCA_in_MATLAB(
>>>     INCA_base_directory,
>>>     script_folder,
>>>     matlab_script,
>>>     runner_script
>>> )
For more information on how to use this module or visualize the data, please check the example notebook in the BFAIR repository.

BFAIR.mfa.INCA.INCA_reimport.reimport_descr¶

A class to re-import the INCA output data. It is parsed from MATLAB to python DataFrames.

Examples

>>> from BFAIR.INCA import INCA_reimport

After initialization, the data can either be re-imported all at once

>>> reimport_data = INCA_reimport()
>>> reimport_data.reimport(filename, simulation_info, simulation_id)

Or sequentially (not shown)

For more information on how to use this module or visualize the data, please check the example notebook in the BFAIR repository.

INCA script generation¶

The MATLAB scripts for INCA can be automatically generated with the right input. To do that, we need to limit the input to only the information that will actually be used for the analysis.

Data pre-processing¶

If you have large dataframes that include multiple experiments that should be used in separate analyses or information about multiple models, you reduce them using these functions.

`INCA_script.limit_to_one_model`(data_input, …)	Limits the data to values that are assigned to one metabolic model
`INCA_script.limit_to_one_experiment`(…)	Limits the data to values that were acquired in one experiment

Step-wise generation¶

Once the input is ready, INCA script can be generated. This can be done either step-wise or all at once. Here are the functions for the sequential construction. See below for the short-cut.

`INCA_script.initiate_MATLAB_script`()	Starts writing the MATLAB script
`INCA_script.add_reactions_to_script`(…)	Translates the model and adds mapping using reaction_mapping()
`INCA_script.initialize_model`()	Previously described reactions are assigned to a model object
`INCA_script.symmetrical_metabolites`(…)	Takes care of symmetrical metabolites if not done so in the reaction equations
`INCA_script.unbalanced_reactions`(…[, …])	Adds in the metabolite state (balanced or unbalanced)
`INCA_script.add_reaction_parameters`(…[, …])	Flux parameters are added.
`INCA_script.verify_and_estimate`()	Adds a QC step and defines the restarts for later processing
`INCA_script.add_experimental_parameters`(…)	Defines the measured fragments and adds tracer information
`INCA_script.mapping`(experimentalMS_data_I, …)	Adds MS data to measured fragments

Summary function¶

Both the INCA_script and the INCA_reimport module have summarizing functions that run large parts of the workflows if the correct input is provided. The input script can be generated using the INCA_script.script_generator summary function.

INCA_script.script_generator(…)

Combines the functions that construct the model

Runner script generation¶

The analysis functions are kept saparate from the metabolic model and the experimental data used in INCA. The runner script, containing these analysis functions, is created using the following functions.

INCA_script.runner_script_generator(…[, …])

Adds the functions needed to run the script and export the .mat file

Save the scripts¶

Until now, our scripts are just large strings. These functions save them as .m MATLAB scripts.

`INCA_script.save_INCA_script`(script, scriptname)	Writes the output file
`INCA_script.save_runner_script`(runner, …)	Writes the runner output file

INCA execution¶

If the MATLAB engine is activated (see top), then the INCA script can be run in MATLAB from python, i.e. directly from e.g. a Jupyter Notebook.

MATLAB engine execution function¶

INCA_script.run_INCA_in_MATLAB(…)

Executes the script in MATLAB using INCA Prints time and produces .mat file

INCA output re-import¶

After INCA was successfully run, the results will be saved in a .mat file. The results will have to be parsed in order to use them in python again. This is done with the INCA_reimport module.

Step-wise re-import¶

You can execute everything all at once (check the summary function below) or one by one, as described here.

`INCA_reimport.INCA_reimport.extract_file_info`(…)	Extracts information about the file
`INCA_reimport.INCA_reimport.det_simulation_type`(…)	Determine if the simulation is a parallel labeling experiment, non-stationary, or both
`INCA_reimport.INCA_reimport.data_extraction`(…)	Extract simulation data
`INCA_reimport.INCA_reimport.extract_model_info`(m)	Extract model information
`INCA_reimport.INCA_reimport.extract_sim_params`(…)	Extract simulation parameters
`INCA_reimport.INCA_reimport.extract_base_stats`(f, …)	Extract fit information
`INCA_reimport.INCA_reimport.get_fit_info`(f)	Extract information and sum of the squared residuals of
`INCA_reimport.INCA_reimport.sort_fit_info`(…)	Seperate the information from the original input, the “get_fit_info(f)” function, the “extract_file_info(filename)” function and the “extract_base_stats(f, simulation_id, info)” function into appropriate rows
`INCA_reimport.INCA_reimport.get_residuals_info`(f, …)	Extract the residuals of the fitted measurements
`INCA_reimport.INCA_reimport.sort_residual_info`(…)	Seperate the information from the original input, the “get_residuals_info(f)” function, the “extract_file_info(filename)” function and the “extract_base_stats(f, simulation_id, info)” function into appropriate rows
`INCA_reimport.INCA_reimport.get_fitted_parameters`(f, …)	Extract the fitted parameters
`INCA_reimport.INCA_reimport.sort_parameter_info`(…)	Seperate the information from the original input, the “get_fitted_parameters(f, simulation_info)” function, the “extract_file_info(filename)” function and the “extract_base_stats(f, simulation_id, info)” function into appropriate rows

Summary function¶

The output can also be re-imported using the INCA_reimport.reimport summary function.

INCA_reimport.INCA_reimport.reimport(…)

Summary function that includes all of the previously set up functions and produces all of the outputs