User’s manual

MTF format

Let start by describing file formats used by influx_si. MTF (Multiple TSV files) format was introduced in v6.0 of influx_si and was developed in collaboration and on demand from MetaToul-FluxoMet platform and MetaSys team of Toulouse Biotechnology Institute. Since v7.0, MTF is also used for output files.

Originally, MTF introduction came in replacement to FTBL format and served several purposes:

• to simplify network and other information formatting;

• to allow multiplexing of constant and variable information for large experience series. E.g., a same network can be tested under several biological conditions or vice versa a given data set can be confronted to different network models to see which one can better fit it;

• to facilitate automatic assembling of network/data/options coming from tiers workflows such as MS or NMR data treatment.

Even if FTBL format was replaced as front-end format in influx_si, it is still a valid format for calculation and continues to be used behind the scene in accompanying utilities.

MTF format is composed of a series of plain text (tab separated when necessary) files, each having a particular role and designated by their suffixes:

.netw

describes biochemical reactions and label transitions.

.linp

describes label inputs forms and fractions

.miso

describes stationary and instationary label measurements, their type, value, and standard deviation

.mflux

describes stationary net flux measurements (e.g., substrate consumption or product secretion)

.mmet

describes stationary concentration measurements

.cnstr

describes constraints, equality or inequality type, on fluxes and concentrations

.tvar

describes variable type such as Free, Constrained or Dependent with possible starting values for Free variables

.opt

describes options such as optimization parameters, post-treatment R scripts to execute and others

These suffixes will be used throughout this manual, as they facilitate influx_si usage. But they are not mandatory. For example, a classical .tsv or .txt suffixes can be used instead. In this case, a file meaning can be indicated in --mtf option of influx_si of txt2ftbl, e.g. --mtf netw=ecoli.txt,miso=gcms.tsv,linp=glucoseU.8.tsv

Only the first 3 are mandatory as input files, the rest of MTF set is optional.

Now, we pass in more detailed review each of the file content.

.netw

This is a central file to the rest of the work – network file .netw It represents a list of biochemical reactions with label transitions. Here is an example of such reaction:

edd: Gnt6P (ABCDEF) -> Pyr (ABC) + GA3P (DEF)

Let detail its elements (all reaction elements are case-sensitive):

edd

the unique reaction name

:

name-reaction separator

Gnt6P, Pyr, GA3P

reactant names. They must not contain +, (, ). Other common separators such as :, ; and special characters such as {, |, … are to avoid. However, other than Latin alphabet letters are welcome in UTF-8 encoding, e.g. α, β etc.

(ABCDEF), (ABC), (DEF)

are labels of reactants. Here, their meaning is that first 3 carbons of Gnt6P goes to Pyr in the same order and the rest goes to GA3P also in the same order. Label atom numbering is left free for user’s choice but once chosen, it must remain consistent between reactions. It is advised to follow some common conventions. E.g., the most oxidized carbon atom (if it is a carbon which is used for labeling) should have number 1 (here letter A in Gnt6P and Pyr, and letter D in GA3P). Its neighbor has number 2 etc. influx_si does not impose to use ¹³C as labeling atom. User is free to use any other atom or even a combination of them, e.g., ¹³C and ¹⁵N. A reactant can be without label atoms. In this case, it will participate in mass balance but not in label balance. Such situation can be useful e.g., for co-factors, e.g., ATP/ADP, NADP/NADPH etc. if they are not synthesized in the modeled network. The left opening parenthesis of the label pattern must be separated by a space from a precedent reactant name. The label identifiers can be composed of Latin or foreign letters as well as digits, each symbol representing one label atom. If a label symbol is present on one reaction side, it must be present as well on the other side. Each symbol must be present only once, except for so called “scrambling” label molecules. For example, Formate is a symmetric molecule from carbon point of view. So, its labeling can be given as (ABCD+DCBA). Thus, for example, a letter A appearing on the other side of reaction can come from both ends of Formate.

->

reaction left and right side separator. Here, the reaction is indicated as non-reversible, i.e., exchange flux is imposed to be 0. However, the net flux can be either positive or negative. For a positive net flux, the reactants on the left are consumed and those on the right are produced. If user wishes to impose the sens of reaction, a sign ->> can be used. In this case, the net flux is imposed to be non-negative (i.e. ≥ 0). For reversible reactions, a sign <-> can be used. A sign <->> is meaningful. It indicates that a reaction is reversible, but the net flux must be non-negative. A non-zero exchange flux for a positive net flux can be responsible for a backward label propagation.

Input/output reactions must have exchange flux set to 0. So they can be edited either with -> or ->>. This is necessary to distinguish them from reactions having so-called “dead-end” reactants. They occur only on one side of reaction(s) (either left or right, like input/output reactants do) but have an exchange flux different from 0. The dead-ends are rarely desirable and most often result from network topology errors or simply leaving <-> where -> is meant. However, there are some special situations when they can be used on purpose in influx_i, for example, for modeling label dilution from stock species.

+

reactant separator. The surrounding spaces are mandatory.

In the above reaction example, all stoichiometric coefficients are 1. If it is not the case in some reaction, they can be given as plain number (integer or with decimal point) preceding a reactant name and separated by an optional * sign (it can be replaced by a space), e.g.:

v47:  Ser (abc) + AcCoA (de) + 3.0*ATP () + 4.0*NADPH () + SO4 () -> Cys (abc) + Ac (de)

Note that coefficients different from 1 can only be used with non labeled reactants.

A comment can be introduced by #. The line content starting from this character to the end of the line is simply ignored with one exception: a triple hash sign ### at the line beginning is used to introduce a pathway name. Pathway name can be useful for ftbl2metxml.py script which prepare xml and txt files for visualization on a partner site MetExplore.

.linp

Label input can be indicated in .linp file. Starting from this file type, the rest of the files are in TSV (tab separated values) format. I.e. they are plain text files where data are organized in tables, one table row per file line and where columns are separated with the tabulation character. The first non commented row contains column names. The comments start with # sign, they are simply ignored till the end of the row where they occur. The left- and right-trailing white spaces are stripped.

The .linp file can contain the following column names:

Id

Not used by influx_si but can be useful for user’s information tracking system.

Comment

Not used by influx_si but left for user’s convenience.

Specie

Chemical specie name such as used in reactions in .netw file, e.g. Glucose

Isotopomer

Particular isotopomer form used as label entry and composed only of “0”s and “1”s, e.g. 111111 for uniformly labeled Glucose, 100000 for Glucose labeled in first carbon.

Value

For step-wise labeling experiments, a number between 0 and 1 indicating a fraction of the given labeled form in the mix. For experiments with labeling varying in time, a R expression describing time dependent function for the given label form.

Normally, all labeling form for a given specie must sum up to 1. If they don’t, the following conventions apply:

• “the rest is unlabeled”: if many labeling forms are lacking in the file (including fully unlabeled specie) then the fully unlabeled form (e.g. 000000 for Glucose) is considered as completing the set to 1;

• “guess the lacking one”: if only one form is lacking in the file (no matter which one), then its fractions is considered as completing the present set to 1.

Here is a complete example:

Id      Comment Specie  Isotopomer      Value
                Gluc_U  111111          1
                Gluc_U  000000          0.
                Gluc_1  100000          1.
                Gluc_1  000000          0.

which can be shortened, due to above conventions, to:

Id      Comment Specie  Isotopomer      Value
                Gluc_U  111111          1
                Gluc_1  100000          1.

.miso

The .miso contains and describes labeled measurements. This file contains the following column names:

Id

Not used by influx_si but can be useful for user’s information tracking system.

Comment

Not used by influx_si but left for user’s convenience.

Specie

Specie names such as used in reactions in .netw file, e.g. Glucose

Fragment

Integer sequences or intervals describing label fragment used in a given measurement, e.g. 1-3 or 1,2,3 or 2-5,7,9-11. Empty field means that the entire molecule is measured.

Dataset

Any character sequence identifying measurement method. It can be useful for distinguishing measurements on the same combination specie/fragment. Examples: MS-1, HSQC. A given dataset can have its own scaling factor if they are in use.

Isospecies

For MS measurements, a M0, M1 etc. isotopologue identification. For NMR label measurements, a combination of binary cumomers involved in measurements. They are separated by “+” sign. Each binary cumomer can be composed of “0”, “1” and “x” symbols, e.g. 01x+10x. This notation is universal enough to describe any NMR (or even MS) method. However, for methods focused on a particular specie fragment, it can be more practical to use notation “label transferring” like 2->, 2->1, 2->3 and 2->1,3. Here, the second atom is labeled and in a given measurement method it interacts:

2->

with no other atom (given a singlet peak);

2->1

with labeled atom 1 (giving a peak doublet 1);

2->3

then labeled atom 3 (giving peak doublet 2);

2->1,3

and finally with both labeled atoms 1 and 3 (doublet of doublets).

Value

Measured value in floating point notation. Can be empty or NA, meaning “non-available”. There is a difference between a measurement absent in file and a measurement with NA value. The former is simply ignored, while the latter is simulated and reported is simulated measurements.

SD

Standard deviation value in floating point notation. Cannot be empty, neither NA. We recall that SD is characterizing a given measurement technique, not its particular realization. So it is perfectly possible to have only one measurements if SD of the given technique was already estimated from previous experiments. If the Value contains an average of \(n\) measurements, than a standard SD should be reduced by a factor \(\sqrt{n}\)

Time

For instationary labeling, the time point to which a given measurement corresponds. For stationary labeling, must be empty.

A multi-line example is the following:

Id      Comment Specie  Fragment        Dataset Isospecies      Value           SD      Time
                GA3P                    LAB-10  1xx             0.03304418      0.002
                GA3P                    LAB-11  x1x             0.01260362      0.002
                GA3P                    LAB-12  xx1             0.1207158       0.002
                PEP     1,2             PEAK-1  1->             0.66            0.005
                PEP     1,2             PEAK-1  1->2            0.01            0.005
                PEP     1,2,3           PEAK-2  2->             1.26            0.005
                PEP     1,2,3           PEAK-2  2->1            0.03960991      0.005
                PEP     1,2,3           PEAK-2  2->3            0.01183004      0.005
                PEP     1,2,3           PEAK-2  2->1,3          0.0007686513    0.005
                PEP     1,2,3           MS-1    M0              12601           68.005
                PEP     1,2,3           MS-1    M1              2301            16.505
                PEP     1,2,3           MS-1    M2              96              5.48
                PEP     1,2,3           MS-1    M3              1               5.005

Here, column Time is left empty intentionally, thus signaling a stationary labeling.

.mflux

Starting from this file format, we consider that column names are either similar to already described or are self-explanatory, and we will just give multi-line examples with few possible comments. So, for net flux stationary measurements, we could have:

Id      Comment Flux    Value   SD
                upt     1.02    0.05

.mmet

For stationary specie concentration, we could have:

Id   Comment Specie  Value                   SD
             Fru6P   0.4263681348074568      0.01
             GA3P    0.469998855791378       0.01

.cnstr

Constraints on fluxes and specie concentrations can look like:

Id      Comment Kind    Formula                 Operator        Value
                NET     Glucupt_1+Glucupt_U     ==              1
                NET     edd                     >=              0.0001

Column Kind indicates if a constraint is on net fluxes: NET; on exchange fluxes: XCH or on specie concentrations: MET. The Formula content must be a linear function of involved entities. If numeric factors are involved in the formula, they must preceed the variable name, e.g. 0.632*BM and not BM*0.632. Column Value can have either a float number or a simple Python arithmetic expression which evaluates to a float number, e.g. math.sqrt(2)/2 or np.sqrt(2)/2 (here np stands for numpy).

.tvar

Types of variables can resemble to

Id      Comment Name    Kind    Type    Value
                upt     NET     F       1.02369
                emp1    NET     F       0.511098
                emp2    NET     D
                ppp2    XCH     F       0.778786
                ppp3    XCH     C       0.83932

The Type can be either

F

for “free”, requires a float number in Value

D

for “dependent” or

C

for “constrained”, requires a float number in Value.

The Kind can be either

NET

for net fluxes

XCH

for exchange fluxes

METAB

for specie concentration

.opt

Options passed to influx_si can be similar to:

Id      Comment Name                    Value
                dt                      1
                nsubdiv_dt              4
                file_labcin             e_coli_msen.txt
                commandArgs             --noscale --TIMEIT --time_order=2 --zc=0 --clowp 1.e-9
                optctrl:nlsic:errx      1.e-3
                optctrl:nlsic:maxit     50
                optctrl:nlsic:btmaxit   16
                optctrl:nlsic:btstart   1
                optctrl:nlsic:btfrac    0.5
                optctrl:nlsic:adaptbt   1
                optctrl:nlsic:monotone  1
                posttreat_R             plot_ilab.R

The meaning of each possible option is described in different sections of this manual.

.vmtf

Variable part of MTF approach can be used to combine constant and variable parts of experiments to launch a calculation of flux maps in a batch. E.g. in a set of experiments on the same organism in different biological conditions, .miso, .mflux can vary from one experiment to another while .netw and other files can remain the same in the whole experiment set. In this case, files containing variable sections (here .miso and .mflux) can be given in a special file having an extension ‘.vmtf’ while constant parts will be given in --mtf or --prefix options.

.vmtf file is a TSV file with columns using the same name as extensions described above: netw, linp, etc. Each row contains file names that will be used to produce a particular FTBL file used in calculation. Thus, each row must have ftbl column with unique and non empty name. If a file type is present both in column names of ‘vmtf’ and in --mtf/--prefix option then the content of ‘vmtf’ file will take precedence. Empty values in vmtf file are ignored. All file paths in vmtf file are considered relative to the location of vmtf file itself. If in .vmtf, a file name is given without extension, it is deduced from column name. Example of .vmtf file:

Id      Comment miso            mflux           tvar            ftbl
                model_WT_BW_1   model_WT_BW_1   model_WT_BW_1   vmtf_WT_BW_1
                model_WT_BW_2   model_WT_BW_2   model_WT_BW_2   vmtf_WT_BW_2
                model_zwf_1     model_zwf_1     model_zwf_1     vmtf_zwf_1

Example of command line using .vmtf:

--prefix ecoli --mtf variable.vmtf

Output format

Since v7.0, MTF is also used as output format for most result files. However, compared to input files, some additional columns were added. We will describe them in appropriate subsections.

The whole set of output files go to mynetwork_res directory if this name is not overwritten with --out option. Here mynetwork is just a name example to be adapted to your situation. Let review output files. By default, the result subdirectory is located in the same directory as input MTF files.

Note

All result files are silently overwritten if already exist. So take care to copy your results elsewhere if you want to protect them from overwriting.

mynetwork.log

contains the run-time log messages, in particular, it contains a report on convergence history during the fitting process. It can be helpful for identifying potential problems. Some warnings can be written in this file, so user should scrutinize this file for lines starting with ***Warning: to be informed about potential issues.

For example, a warning about structurally non identifiable fluxes can look like:

***Warning: inverse of covariance matrix is numerically singular.
Statistically undefined parameter(s) seems to be:
f.x.pyk
For a more complete list, see SD column in '.tvar.sim' result file.

mynetwork.err

This file contains critical error messages preventing from normal program execution. Normally, it should be empty (0 byte size). If it is not, there is something definitely wrong either in the input files or with the program itself that should be fixed before going on.

Problems can appear in all stages of a software run:

• parsing MTF/FTBL files

• R code writing

• R code execution

  • vector-matrix initialization

  • optimization

  • post-optimization treatment

Most of the error messages are automatically generated by underlying languages Python and R. These messages can appear somewhat cryptic for a user unfamiliar with these languages. But the most critical error messages are edited to be as explicit as possible. For example, a message about badly structurally defined network could be similar to

Error : Provided measurements (isotopomers and fluxes) are not
        sufficient to resolve all free fluxes.
Unsolvable fluxes may be:
        f.x.tk2, f.n.Xylupt_1, f.x.maldh, f.x.pfk, f.x.ta, f.x.tk1
Jacobian dr_dff is dumped in dbg_dr_dff_singular.txt

a message about singular cumomer balance matrix could resemble to

lab_sim: Cumomer matrix is singular. Try '--clownr N' or/and '--zc N' options with small N, say 1.e-3 or constrain some of the fluxes listed below to be non zero Zero rows in cumomer matrix A at weight 1:
cit_c:16
ac_c:2
...
Zero fluxes are:
fwd.ACITL
...

Note

In this error message, we report cumomers whose balance gave a zero row in the cumomer matrix (here cit_c:<N> cumomers, where <N> is an integer, its binary mask indicates the “1”s in the cumomer definition) as well as a list of fluxes having 0 value. This information could help a user to get insight about a flux whose zero value led to a singular matrix. A workaround for such situation could be setting in the .cnstr file an inequality constraining a faulty flux to keep a small non zero value. A more radical workaround could be restricting some flux classes (input-output fluxes with the option --cinout=CINOUT or even all non-reversible ones with the option --clownr=CLOWNR) to stay out of 0, e.g.:

$ influx_s.py --clownr 0.0001 --prefix mynetwork

Adding such inequalities does not guaranty that cumomer matrix will become invertible, but often it does help. It’s up to the user to check that an addition of such inequalities does not contradict biological sens of his network.

and so on.

A user should examine carefully any warning/error message and start to fix the problems by the first one in the list (if there are many) and not by the easiest or the most obvious to resolve. After fixing the first problem, rerun influx_si to see if other problems are still here. Sometimes, an issue can induce several others. So, fixing the first issue could eliminate some others. Repeat this process, till all the troubles are eliminated.

mynetwork.miso.sim, mynetwork.mflux.sim, mynetwork.mmet.sim

These files contain simulated values and are formatted as input files for isotopic, flux and concentration measurements. Additional columns are:

Residual

containing reduced residual values calculated as “(simulated - measured)/SD”;

Pvalue

result of Z-test on residual value. Lower p-value corresponds to higher (in absolute value) residual.

If multiple starting points were used (e.g. with --fseries and/or --iseries options) then result corresponding to each starting point will be numbered with prefix .V, e.g. mynetwork.V10.miso.sim for tenth staring point.

mynetwork.tvar.sim

Estimated fluxes and specie concentrations (if any) are all gathered in this file, in column Value. Additional columns are:

SD

Estimated Standard Deviation

Struct_identif

Contains “yes” if the value on the current row is considered as structurally identifiable (“no” otherwise). We arbitrary set a threshold for “yes” decision at SD <= 10000. Note that a value can be structurally identifiable but still statistically poorly defined.

Low_mc, Up_mc

If Monte-Carlo method for sensitivity estimation is used (cf. option --sens mc=MC) then these columns contain lower and upper 95% confidence interval limits. They are estimated at quantile levels 2.5% and 97.5% respectively.

In case of multiple starting points, this file is numbered.

mynetwork.stat

This file contains results of chi2 statistical test. Its content can look like:

chi2_value              61.5141593189625
chi2/df                 1.86406543390795
number_of_measurements  54
number_of_parameters    21
degrees_of_freedom      33
p-value                 0.998130284339227
conclusion              At level of 95% confidence, the model does not fit the data good enough with respect to the provided measurement SD

The field names are self explanatory. In case of multiple starting points, this file is numbered.

Custom files

These files (e.g. mynetwork.pdf) can be produced by user supplied scripts that are executed at the end of influx_si simulations. For example, we provide a script plot_ilab.R which can be used to plot label kinetics simulated by influx_i or plot_smeas.R for influx_s. One or many of such custom scripts can be given in .opt file, field posttreat_R (cf. e_coli_i.opt for example)

Old result files

For users willing to continue usage of old result files, namely mynetwork_res.kvh, we kept them in tmp subdirectory.

Thus typically, a tmp subdir contains:

• mynetwork.ftbl

• mynetwork.pres.csv

• mynetwork.R

• mynetwork_res.kvh

• edge.netflux.mynetwork.attrs

• edge.xchflux.mynetwork.attrs

Basic influx_si usage

influx_si can be run as

$ influx_s.py --prefix mynetwork

or

$ influx_i.py --prefix mynetwork

Letters s and i stand for “stationary” and “instationary”. We suppose here that a valid MTF file set was created. Moreover, we supposed influx_s.py and influx_i.py are in the PATH variable.

In the rest of this manual, we’ll use just influx_s.py as an example if the example is valid for both stationary and instationary contexts. If some usage is valid exclusively for influx_i.py, it will be duly signaled.

In a high throughput context, it can be useful to proceed many MTF set files in parallel. This can be done by giving all variable parts of experiment set in a .vmtf file, e.g.

$ influx_s.py --prefix mynetwork --mtf variable.vmtf

All files are then proceeded in separate independent processes launched almost simultaneously by a bunch of size equal to the number of available or requested cores (if an option --np=NP is used). It is an operating system who is in charge to make a distribution of all these processes among all available CPUs and cores.

Sometimes, particular cases need usage of special options of influx_si. The list of available options can be seen by running:

$ influx_s.py --help

If used with options, influx_si can be run like

$ influx_s.py [options] --prefix mynetwork

where [options] is an option list separated by a white character.

Note

Here and throughout this manual, content placed in brackets [...] is meant to be an optional part of the command. If the user does wish to type an optional part of a command, the brackets themselves must be omitted.

Each option starts with a double dash -- and can be followed by its argument if applicable. For example, to use BFGS optimization method instead of the default NLSIC algorithm, a user can run:

$ influx_s.py --meth BFGS --prefix mynetwork

or

$ influx_s.py --meth=BFGS --prefix mynetwork

The option names can be shortened till a non-ambiguous interpretation is possible, e.g., in the previous example, the option could be shortened as --me BFGS or --me=BFGS because there is no other option name starting by me. But an option --no could not be distinguished between --noopt and --noscale. So at least --nos (for --noscale) or --noo (for --noopt) should be provided. There is only one option that does not admit a usage of an equal sign to provide an argument, it is --excl_outliers. Use only a space character to provide an argument to this option when required.

Here after, the available options with their full names are enumerated and detailed.

influx_si command line options

--version

show program’s version number and exit

-h, --help

show the help message and exit

--noopt

no optimization, just use free fluxes as is (after a projection on feasibility domain), to calculate dependent fluxes, cumomers, stats and so on

--noscale

no scaling factors to optimize => all scaling factors are assumed to be 1

This option can be useful if your measurements are already scaled to sum up to 1 which is often the case of MS data. Then, user saves some free parameters corresponding to scaling factors. This option can become mandatory if user wants to prevent scaling factors to be adjusted by optimization process.

--meth=METH

method for optimization, one of nlsic|BFGS|Nelder-Mead|pso. Default: nlsic. Multiple occurrences of this option can appear on command line. In this case, specified minimization methods are applied successively, e.g. --meth pso --meth nlsic means that pso will be used first, then nlsic will take over from the point where pso ends. In case of multiple methods, it is recommended starting with non-gradient methods like pso or Nelder-Mead and make them follow by gradient based methods like nlsic or BFGS. If pso or Nelder-Mead are indeed used as the first method, it is not recommended combining them with --zc option.

--fullsys

calculate all cumomer set (not just the reduced one necessary to simulate measurements)

This option influences only post-optimization treatment. The fitting itself is still done with the reduced cumomer set or EMU variables if requested so. See the original paper on influx_s for more information on the reduced cumomer set.

--emu

simulate labeling in EMU approach

This option should not produce a different result in parameter fitting. It is implemented and provided in a hope that on some network the results can be obtained in a shorter time

--irand

ignore initial approximation for free parameters (free fluxes and specie concentrations) from the FTBL file or from a dedicated file (cf –fseries and –iseries option) and use random values drawn uniformly from [0,1]

It is recommended to use this option in conjunction with “–zc 0” option.

--sens=SENS

sensitivity method: SENS can be ‘mc[=N]’, mc stands for Monte-Carlo. N is the number of Monte-Carlo simulations. Default for N: 10

The sensitivity information (i.e., the influence of the noise in the data on the estimated parameter variation) based on linearized statistics is always provided. So the user has to use this option only if he wants to compare this linearized information to the Monte-Carlo simulations. Note that the default value 10 for the number of simulations is far from to be sufficient to get reliable statistical estimations. This default option allows only to quickly check that this option is working as expected.

--cupx=CUPX

upper limit for reverse fluxes. Must be in interval [0, 1]. Default: 0.999

--cupn=CUPN

upper limit for net fluxes. Default: 1.e3

--cupp=CUPP

upper limit for specie pool. Default: 1.e5

--clownr=CLOWNR

lower limit for not reversible free and dependent fluxes. Zero value (default) means no lower limit

A byproduct of this option is that it can drastically reduce cumomer system sizes. As it ensures that non-reversible fluxes cannot change the sign, revers fluxes can be eliminated from pathways leading to observable cumomers.

--cinout=CINOUT

lower limit for input/output free and dependent fluxes. Must be non-negative. Default: 0

--clowp=CLOWP

lower limit for free specie pools. Must be positive. Default 1.e-8

--np=NP

When integer >= 1, it is a number of parallel threads (on Unix) or subprocesses (on Windows) used in Monte-Carlo (M-C) simulations or for multiple FTBL inputs. When NP is a float number between 0 and 1, it gives a fraction of available cores (rounded to closest integer) to be used. Without this option or for NP=0, all available cores in a given node are used for M-C simulations.

--ln

Least norm solution is used for increments during the non-linear iterations when Jacobian is rank deficient

Jacobian can become rank deficient if provided data are not sufficient to resolve all free fluxes. It can be useful to determine fluxes that can still be resolved by the available measurements. If the Jacobian does not become rank deficient, this option has no influence on the found solution, neither on the optimization process. But if the Jacobian does become rank deficient, a warning message is printed in the error file even if the optimization process could go to the end.

Note

Use this option with caution, in particular, when used in conjunction with Monte-Carlo simulations. As undetermined fluxes will be given some particular value, this value can be more or less stable from one Monte-Carlo simulation to another. This can create an illusion that a flux is well determined. See the linearized statistics in the result file to decide which fluxes are badly resolved.

A correct way to deal with badly defined metabolic network is to provide additional data that can help to resolve all the fluxes and/or to optimize input label, not just put --ln option and cross the fingers.

Warning

In this option, the notion of “least norm” is applied to increments during the optimization, not to the final solution. So undetermined fluxes could vary from one run to another if the optimization process is started from different points, while well determined fluxes should keep stable values.

--sln

Least norm of the solution of linearized problem (and not just of increments) is used when Jacobian is rank deficient

--tikhreg

Approximate least norm solution is used for increments during the non-linear iterations when Jacobian is rank deficient

To obtain an approximate solution, a Tikhonov regularization is used when solving an LSI problem. Only one of the options --ln and --tikhreg can be activated in a given run.

--lim

The same as –ln but with a function limSolve::lsei()

--zc=ZC

Apply zero crossing strategy with non-negative threshold for net fluxes

This option can accelerate convergence in situations when a net flux has to change its sign during the optimization iterations. Once such flux is identified, it is better to write the corresponding reaction in opposite sens in the FTBL file or to give a starting value with a correct sign to avoid such zero crossing situation.

--ffguess

Don’t use free/dependent flux definitions from FTBL file(s). Make an automatic guess.

The fact that free fluxes are chosen automatically does not allow specifying a starting point for optimization iterations so a random starting point is used (drawn uniformly in [0; 1] interval). An option --seed can be useful to make the results reproducible.

--fseries=FSERIES

File name with free parameter values for multiple starting points. Default: ‘’ (empty, i.e. only one starting point from the FTBL file is used)

The file must be formatted as plain text file with tab separator. There must be as many columns as starting points and at least as many rows as free parameters assigned in this file. A subset of free parameters can be used in this file. In this case, the rest of parameters take their unique starting values from the FTBL file. The first column must contain the names of free parameters used in this file. If there are extra rows whose names are not in the set of free parameter names, they are simply ignored. The first row must contain the names of starting points. These names can be just numbers from 1 to the number of starting points.

--iseries=ISERIES

Indexes of starting points to use. Format: ‘1:10’ – use only first ten starting points; ‘1,3’ – use the first and third starting points; ‘1:10,15,91:100’ – a mix of both formats is allowed. Default ‘’ (empty, i.e. all provided starting points are used)

When used with conjunction with --fseries, this option indicates the starting points to use from FSERIES file. But this option can also be used in conjunction with --irand to generate a required number of random starting points, e.g., influx_s.py --irand --iseries 1:10 mynetwork will generate and use 10 random starting points.

For both --fseries and --iseries, one result file is generated per starting point, e.g., mynetwork_res.V1.kvh, mynetwork_res.V2.kvh and so on. If starting points comes from a --fseries then the suffixes V1, V2, … are replaced by the column names from this file. In addition, a file mynetwork.pres.csv resuming all estimated parameters and final cost values is written.

--seed=SEED

Integer (preferably a prime integer) used for reproducible random number generating. It makes reproducible random starting points (–irand) but also Monte-Carlo simulations for sensitivity analysis. Default: none, i.e., current system value is used, so random drawing will be varying at each run.

--excl_outliers

This option takes an optional argument, a p-value between 0 and 1 which is used to filter out measurement outliers. The filtering is based on Z statistics calculated on reduced residual distribution. Default: 0.01.

Excluded outliers (if any) and their residual values are reported in the mytework.log file. Non-available (NA) measurements are considered as outliers for any p-value. An optional p-value used here does not give a proportion of residuals that will be excluded from the optimization process, but rather a degree of being a valuable measurement. So, closer to zero is the p-value, the fewer data are filtered out. If in contrary, you want to filter out more outliers than with the default p-value, use a value grater than the default value of 0.01, e.g.:

influx_s.py --excl_outliers 0.02 mynetwork.ftbl

Note

Don’t use an equal sign “=” to give a p-value to this option. Here, only a white space can be used as a separator (as in the example above).

--nocalc

generate an R code but not execute it.

This option can be useful for parallel execution of the generated R files via source() function in cluster environment

--addnoise

Add centered gaussian noise to simulated measurements written to _res.kvh file. SD of this noise is taken from FTBL file

This option can be helpful for generating synthetic FTBL files with realistic simulated measurements (cf. How to make FTBL file with synthetic data?).

--mtf MTF

option passed to txt2ftbl. See help there.

--prefix PREFIX

option passed to txt2ftbl. See help there.

--eprl EPRL

option passed to txt2ftbl. See help there.

--force FORCE

option passed to txt2ftbl. See help there.

-o OUT, --out OUT

output directory. Default: basename of input file without suffix + ‘_res’. If empty, no output directory is created. In this case log and error messages are directed to standard output/error channels. Non empty OUT can be used when only one input file or MTF set is given.

--copy_doc

copy documentation directory in the current directory and exit. If ./doc exists, its content is silently overwritten.

--copy_test

copy test directory in the current directory and exit. If ./test exists, its content is silently owerriten.

--install_rdep

install R dependencies and exit.

starting from v5.3, this installation is made in interactive mode. I.e. if the default installation directory (the first one from a list returned by R’s .libPaths()) is not writable by the user then influx_si will try to install the needed packages in the directory defined in R session variable R_LIBS_USER. If this last does not exist, the user is asked for a permission to create it. This behavior is the default one of R’s install.packages() which is used here.

--TIMEIT

developer option

Some portions of code are timed, and the results is printed in the log-file. A curious user can use this option without any harm.

--prof

developer option

This option provides much more detailed profiling of the execution than --TIMEIT option. Only developers can be interested in using such information.

All command line options can also be provided in a .opt file. A user can put them in the field commandArgs, e.g.

Name            Value
commandArgs     --meth BFGS --sens mc=100 --np 1

If an option is provided both on the command line and in the .opt file, it is the command line that has the priority. In such a way, a user is given an opportunity to overwrite any option at the run time. Nevertheless, there is no way to cancel a flag option (an option without argument) on a command line if it is already set in the .opt file. For example, if --fullsys flag is set in the .opt file, the full system information will be produced whatever command line options are.

Parallel experiments

Staring from v4.0, influx_si offers possibility to treat labeling data from parallel experiments. Parallel experiments for stationary labeling were described in the literature (e.g. cf. “Parallel labeling experiments and metabolic flux analysis: Past, present and future methodologies.”, Crown SB, Antoniewicz MR., Metab Eng. 2013 Mar;16:21-32. doi: 10.1016/j.ymben.2012.11.010). But for instationary labeling, at the best of our knowledge, influx_si is the first software offering parallel experiments treatment.

The main interest of parallel experiments is increased precision of flux estimations. This comes at a price of additional work for experiments and data gathering, but the result is often worth the effort. As usual, before doing a real “wet” experiment, it can be useful to run a few “dry” simulations to see if planned experiments will deliver desired precision.

To deal with parallel experiments, a user have to prepare a series of additional .miso/.linp couples, one per additional experiment. While the “main” .miso/.linp couple can be given in --prefix or --mtf options.

Each couple provides input labeling and measured labeling data corresponding to an experiment. This file architecture ensures that a network topology, flux, and specie values are common to all experiments, while entry label and measurements on labeled species are proper to each experiment.

When files are ready, you can run influx_si on them, e.g. in test/prl_exp/mtf directory run:

$ influx_s.py --pref e_coli_glc1-6n --eprl e_coli_glc2n,e_coli_glc3n,e_coli_glc4n,e_coli_glc5n,e_coli_glc6n

In this example, 6 parallel experiments were used, the “main” being described in files ecoli_glc1-6n and 5 additional ones in files going from e_coli_glc2n to e_coli_glc6n. Note that we used a compact form of --eprl options as all .miso/.linp couples used canonical suffixes. In that way, giving only a prefix like e_coli_glc2n was sufficient to find the both corresponding files.

The command can be shortened even more if prl_exp option is used in .opt file. For example if we write in the main set e_coli_glc1-6n.opt:

Name    Value
prl_exp e_coli_glc2n,e_coli_glc3n,e_coli_glc4n,e_coli_glc5n,e_coli_glc6n

then the command to run parallel experiments becomes simply:

$ influx_s.py --pref e_coli_glc1-6n

This example set of files correspond to stationary labeling experiments described in “Complete-MFA: Complementary parallel labeling experiments technique for metabolic flux analysis”, Robert W. Leighty, Maciek R. Antoniewicz, Metabolic Engineering 20 (2013) 49–55 (with only difference that we use simulated and noised data instead of measured ones).

We also provide an example of simulated instationary parallel experiments in the files e_coli_GX_prl (main files) and e_coli_GX_X (secondary files) corresponding to simultaneous consumption of glucose and xylose. The network for these simulations was borrowed from “13C metabolic flux analysis of microbial and mammalian systems is enhanced with GC-MS measurements of glycogen and RNA labeling”, Christopher P. Long, Jennifer Au, Jacqueline E. Gonzalez, Maciek R. Antoniewicz, Metabolic Engineering 38 (2016) 65–72. The experiment consisted in dynamic labeling by uniformly labeled glucose (main experiment) and by uniformly labeled xylose (secondary one). Labeling kinetics MS data are given in e_coli_GX_MS.miso and e_coli_GX_X_MS.miso files respectively. To play with this example (still in the same directory), you can run:

$ influx_i.py e_coli_GX_prl

Note that set of measured specie fragments as well as sampling time points for instationary labeling are not necessary the same for instationary experiments. They do can differ. That’s why a .opt can be necessary to add to .miso/.linp couple to form a complete parallel experiment.

It should be made a clear distinction between parallel experiments described in this section and independent experiments calculated in parallel. The main difference is that parallel experiments of this section share all the same flux map (only labeling pattern and data can differ) while independent experiments can have each its own flux map, be they calculated in parallel or sequentially.

Options in .opt file

In this section, we describe different options that can appear in .opt file

Optimization options

These options can help to tune the convergence process of the NLSIC (or any other chosen algorithm). These options are prefixed with optctrl which is followed by a particular optimization method name and ended by an option name. For example, optctrl:nlsic:errx corresponds to the stopping criterion. A corresponding .opt portion could look like

Name                    Value
optctrl:nlsic:errx      1.e-3

NLSIC parameters

All possible options and their default values for NLSIC algorithm follow:

errx=1.e-5

stopping criterion. When the L2 norm of the increment vector of free parameters is below this value, the iterations are stopped.

maxit=50

maximal number for non-linear iterations.

btstart=1.

backtracking starting coefficient

btfrac=0.25

backtracking fraction parameter. It corresponds to the alpha parameter in the paper on influx_s

btdesc=0.1

backtracking descending parameter. It corresponds to the beta parameter in the paper on influx_s

btmaxit=15

maximal number of backtracking iterations

trace=1

report (=1) or not (=0) minimal convergence information

rcond=1.e10

condition number over which a matrix is considered as rank deficient

ci=list(p=0.95, report=F)

confidence interval reporting. This option is own to nlsic() function. It has no impact on the reporting of linear stats information in the result kvh file after the post-optimization treatment. This latter is always done.

history=FALSE

return or not (default) the matrices with optimization steps and residual vectors during optimization. These matrices can then be found as part of optimization process information/history field in mynetwork_res.kvh file. Use it with caution, big size matrices can be generated requiring much of memory and disk space.

adaptbt=TRUE

use (default) or not an adaptive backtracking algorithm.

monotone=FALSE

should or not the cost decrease be monotone. If TRUE, then at first non decrease of the cost, the iterations are stopped with a warning message.

PSO parameters

Particle Swarm Optimization (PSO) is a stochastic optimization method. It can help to avoid local minimums but its convergence is very slow. That’s why its usage can be particularly useful if combined with a deterministic algorithm like NLSIC. We have implemented PSO method based on the code from CRAN package pso v1.0.3 published in 2012 by Claus Bendtsen (papyrus.bendtsen at gmail.com). The original algorithm was written for box constrained problems. While influx_si requires a usage of general linear constraints. So we modified the algorithms accordingly. Its parameters with their default values used in influx_si are following:

trace=0

an integer controlling the trace printing. A zero value means no printing

fnscale=1

scale factor for minimized function. It is useless in influx_si context.

maxit=100

maximal iteration number to not overcome

maxf=Inf

maximal number of a cost function evaluation

abstol=-Inf

stopping criterion by absolute tolerance during approximating the searched minimum. This parameter can only be useful if the searched minimal value is known in advance. It is not the case of influx_si

reltol=0

stopping criterion by relative change in the found minimal value

REPORT = 10

if tracing is enabled, this parameters gives the number of iterations passed between two successive reports

s=NA,

swarm size. If NA, it is automatically determined.

k=3, p=NA, w=1/(2*log(2)), c.p=.5+log(2), c.g=.5+log(2)

are parameters governing PSO minimization paths. For their significance see the original pso documentation

d=NA

domain diameter

v.max=NA

maximum allowed velocity

rand.order=TRUE

proceed swarm particles in random order or not

max.restart=Inf

maximal allowed restarts

maxit.stagnate=Inf

maximal successive iterations allowed without a detected decrease in optimization function.

trace.stats=FALSE

return or not detailed statistics about the convergence process (not used in influx_si)

type=”SPSO2011”,

which PSO strategy to use. Available options are “SPSO2011” and “SPSO2007”. More about this in the original documentation.

tolineq=1.e-10

tolerance for violating of linear constraints that can happen mainly due to rounding errors.

Other optimization methods

Names and default values for BFGS and Nelder-Mead algorithms can be found in the R help on optim() function.

Growth flux option

If present, this option makes influx_si take into account growth fluxes \(-\mu{}M\) in the flux balance, where \(\mu\) is a growth rate and \(M\) is a concentration of an internal specie M by a unit of biomass. Only species for which this concentration is provided in a .tvar file, contribute to flux balance with a flux \(-\mu{}M\). This flux can be varying or constant during optimization process depending on whether the specie M is part of free parameters to fit or not. Usually, taking into account of this kind of flux does not influence very much on the estimated flux values. So, this option is provided to allow a user to be sure that it is true in his own case.

The option is activated by a field include_growth_flux:

Name                    Value
include_growth_flux     1

Value 0 cancels the contribution of the growth fluxes to the general flux balance.

Another necessary option is mu giving the value of µ:

Name    Value
mu      0.12

Please note that the specie concentrations by a unit of biomass are reported in a file .tvar as:

Name    Kind    Type    Value
Fum     METAB   C       2.47158569399681
Suc     METAB   F       15.8893144279264
Mal     METAB   F       6.47828321758155
...     ...

Specie names used in this section must be identical to those used in the .netw file and others. “F” is used as an indicator of a varying specie pool. Such varying species are part of fitted parameters. Column “Value” is used as starting value in the optimization process.

One of valuable originality of influx_s, it is a possibility to couple fluxomics and metabolomics in stationary experiments. It can be done because specie pools can influence labeling in two ways:

• through specie pooling (due to compartmentalization and/or co-elution during chromatography)

• through growth fluxes.

This last influence is often of low intensity compared to specie transformation fluxes. In literature, it is typically neglected.

Another possibility that was added influx_si is to provide measured specie concentrations in .mmet file:

Specie                  Value                           SD
Suc                     15.8893144279264*1.e-3/10.7     1.e-2
Mal                     6.47828321758155*1.e-3/10.7     1.e-2
Rub5P+Rib5P+Xul5P       1.66034545348219*1.e-3/10.7     1.e-2

Like for other measurements, the user has to provide a name, a value, and a standard deviation for each entry. Species listed in this section must be defined in the .netw file and must have type “F” in the .tvar. Numerical values can be simple arithmetic expressions (as in the example above) which are evaluated during file parsing.

When a specie name is given as a sum of species (e.g. Rub5P+Rib5P+Xul5P) it is interpreted as a list of species to be pooled. It is done proportionally to their concentrations. No numerical factor can appear in this sum. At least one of the species from the list must be free (i.e. to have “F” type in the .tvar file). Otherwise, all species from the list would be considered as having a fixed concentration and providing a measurement for such species would be meaningless.

Note

Species having “F” (as “Free”) in column “Type” in a .tvar file are treated as fittable parameters. We recall that species in this file are identified as having “METAB” in column “Kind”.

An example of an MTF files having specie sections and involving growth fluxes can be found in test/mtf/e_coli_growth.*.

Post treatment option

User can specify a name of one or several R scripts that will be automatically executed after non aborted influx_si run. This option can be useful, for example, for plain saving of calculation environment in a file for later exploring in an interactive R session or for plotting results in a pdf file and so on. A very basic example of such a script is provided in the file R/save_all.R and its use can be found in the options of test/e_coli.opt file.

To activate this option, the script names must be provided in the .opt file, in the field posttreat_R and separated by '; ', e.g.:

Name            Value
posttreat_R     save_all.R; plot_smeas.R

The script name is interpreted as a relative path to the directory where the original MTF files are located. If the file is not found there, it is searched for in influx_si/R. After execution of save_all.R, a file e_coli.RData is created. This particular example can be used to restore a calculation R environment by launching R and executing:

> load("e_coli.RData")

After that, all variables defined in influx_si at the end of the calculations will be available in the current interactive session. To be able to launch custom calculations on these variables, the user has to do some preliminary actions. An example of such actions can be found in a file preamble.R which can be adapted for user’s case.

To write his own scripts for post treatments or explore the calculated values in an interactive session, a user have to know some basics about existent variables where all the calculation results and auxiliary information are stored. Here are few of them:

dirw

is a working directory (where the original FTBL file is)

dirx

is an executable directory (where influx_s.py is)

baseshort

is a short name of the input FTBL file (without the suffix .ftbl neither the directory part of the path)

param

is the vector of the estimated parameters composed of free fluxes, scaling parameters (if any) and specie concentrations (if any)

labargs

is an environment with all necessary data for label simulation (e.g. v=lab_sim(param, cjac=FALSE, labargs)) or residual calculation (e.g. rres=lab_resid(param, cjac=TRUE, labargs))

jx_f

is a environment regrouping calculated quantities. Here are some of its fields:

lf a list with different fluxes:

fallnx

a vector of all net and exchange fluxes (here, exchange fluxes are mapped on [0; 1[ interval)

fwrv

a vector of forward and reverse fluxes (reverse fluxes are “as is”, i.e. not mapped)

xsim

is an internal state label vector

simlab, simfmn and simpool

are vectors of simulated measurements for label, net flux and specie pools respectively (fitting at the best of influx_s’ capacity the provided measurements)

res

is the reduced residual vector, i.e. (simulated-measured)/SD

ures

is the unreduced residual vector, i.e. (simulated-measured)

jacobian

as its names indicates, is the Jacobian matrix (d res/d param)

udr_dp

is the Jacobian matrix for the unreduced residual vector (d ures/d param)

measurements

is a list regrouping various measurements and their SD

nb_f

is a list of various counts, like number of fluxes, parameters to fit, system sizes and so on

nm_list

is a list of names for various vectors like fluxes, species, label vectors, measurements, inequalities and so on

ui, ci

are inequality matrix and right-hand side respectively

A full list of all available variable and functions can be obtained in an R session by executing:

> ls()

This list of more than 400 items is too long to be fully described here. We hope that the few items succinctly described in this section will be sufficient for basic custom treatments.

An inspiration for your own custom treatments and/or plotting can be found in files plot_ilab.R and plot_smeas.R that plot instationary and stationary data respectively in pdf files.

Exclusive influx_i options

There is only one exclusive option that can be given on a command line:

--time_order=TIME_ORDER

Time order for ODE solving (1 (default), 2 or 1,2). Order 2 is more precise but more time-consuming. The value ‘1,2’ makes to start solving the ODE with the first order scheme then continues with the order 2.

The scheme order can be important for the precision of flux and concentration estimations. The impact is not direct, but can be very significant. Please note that it can happen that order 1 fits the data with lower cost value function, but it does not mean that the fluxes/concentrations are better estimated.

Other options can occur as fields in a .opt file.

nsubdiv_dt

integer number of sub-intervals by which every time interval is divided to increase the precision of time resolution.

It can happen that the value 1 (default) is sufficient for a satisfactory flux/concentration estimation. User can gradually increase this value (2, 3, …) in successive influx_i runs to be sure that better time resolution does not impact parameter estimation. This property is called grid convergence. A grid convergence is necessary to overcome the result dependency on the choice of a numerical discretization scheme. A grid convergence can be considered as achieved when changes in estimated parameters provoked by a grid refinement are significantly lower than estimated confidence intervals for these parameters.

dt

a real positive number, defines a time step in a regular grid in absence of values in “Time” column in .miso file. If a “Time” values are well present for label kinetics, then this parameter has no effect.

A regular time grid for label simulations can be useful on preliminary stage when user only elaborates MTF files and wants to see if label simulation are plausible. It can also help to produce simulated measurements (which can be extracted from the _res.kvh file) for further numerical experiments like studying convergence speed, parameter identifiability, noise impact and so on.

tmax

a real positive number, defines the end of a regular time grid if “Time” is empty or absent in .miso. Parameters dt and tmax must be defined in such a way that there will be at least 2 time points greater than 0 in the time grid.

If “Time” values are well present in .miso then this parameter can be used to limit the time grid on which the simulations are done. If the value in tmax is greater than the maximal time value defined in .miso file then this parameter has no effect.

Note

It is very important that the values for time, flux, and specie concentrations be expressed in concordant units. It would be meaningless to give time in minutes, fluxes in mM/h/g and concentrations in mM. This will lead to wrong results.

For example, if the time is expressed in seconds and concentrations in mM/g then fluxes must be expressed in mM/s/g.

funlabR

since v5.4, influx_i is able to simulate label propagation in a metabolically stationary network from a label input varying in time. User can supply R expressions which will calculate fractions of different input label components as functions of time t. Those expressions can be provided in the Value column of .linp file but they can need some helper functions. Few of them are defined in a file funlab.R included in influx_si but user can need more of them. Thanks to this field, he can define them in a custom R file, who’s name can be provided here. There can be given only one file. However, if user-defined functions are spread over several files, they can be included via source() function called from this one. For this purpose, a predefined variable dirw pointing to the current working directory can be useful. It is worth mentioning that the file defined in this field will be executed in a particular environment so that variables created during its execution won’t affect influx_si’s ones. The path of the file provided in this field is relative to the .netw’s one. Example:

Name            Value
funlabR         e_coli_iv_funlab.R  # the file 'e_coli_iv_funlab.R' is in the same directory that 'e_coli_iv.*' MTF set

Functions that are available in funlab.R are following:

ppulses(tp, Tint, Hint=rep_len(c(1., 0.), length(Tint)))

computes a signal in the form of periodic rectangular pulses in time points tp. Each period is composed of one or several intervals whose length in time is given in numeric vector Tint and heights of signals are given in optional numeric vector Hint. By default, Hint is a sequence of 1’s and 0’s. The very first period starts at t=0. Returns a numeric vector of the same length as tp.

linterp(tp, knots, v)

computes a signal in the form of continuous linear piece-wise functions in time points tp. The limits of linear intervals are defined in numeric vector knots and values at limits must be given in numeric vector v. All tp values must lie between min(knots) and max(knots). Returns a numeric vector of the same length as tp.

steplinpath(tp, nu)

computes labeling in a linear pathway of non-reversible reactions under step labeling with fully unlabeled initial state, i.e. starting from 0. The signal is calculated in time points tp. The pathway is defined by numeric vector nu which represents turn-over rates (i.e. a ratio Flux/Specie_Concentration). All values in nu must be pairwise different. Returns a numeric matrix of size m x n, where number of rows m=length(nu) and number of columns n=length(tp). So, for example, if a signal only of the third specie is required, the function can be called as steplinpath(tp, nu)[3,]

steplinpath2(tp, nu, init=double(length(nu)), height=1.)

The same as steplinpath() above but initial state can be different from 0. It can be defined in numeric vector init of the same length as nu. The label amplitude can be given in a scalar height.

ppulseslinpath(tp, nu, Tint, Hint=rep_len(c(1., 0.), length(Tint)), init=double(length(nu)))

computes labeling of linear non-reversible pathway under input composed of periodic rectangular pulses. Labeling for all species is calculated in time points tp. Each period is composed of one or several intervals whose length in time is given in numeric vector Tint and heights of signals are given in optional numeric vector Hint. By default, Hint is a sequence of 1’s and 0’s. Initial label levels can be defined in numeric vector init. Returns a numeric matrix of size m x n, where number of rows m=length(nu) and number of columns n=length(tp).

Value column in .linp

in this field, user can provide R expression calculating fractions of input label as function of time. While for influx_s, it can only be a constant or python expression evaluating to a scalar at compilation time. Such R expressions can refer to a scalar variable t representing the current time point and should return a scalar value representing a label level between 0 and 1. The sum of all label levels relative to a given specie must be 1 if a full set of isotopomer is provided by user. If one or many isotopomers are lacking, usual conventions apply for completion to 1 (cf. MTF format).

# .linp example
Specie  Isotopomer      Value
Gluc_U  111111          ppulses(t, c(T1,T2))  # periodic pulses composed of intervals of length T1 ("labeled") and T2 ("unlabeled")
Gluc_1  100000          ppulses(t, c(T1,T2))

# .opt example
Name    Value
funlabR e_coli_iv_funlab.R  // in this R file variables T1 and T2 are defined

Input isotopomers that are absent in such funlab fields are supposed to be 0 all the time (except for above-mentioned conventions).

If a label level cannot be calculated in one arithmetic operation, several R statements can be placed between curled braces {} separated by semicolon ;. The last operation must be the searched result. In the example above, we could exclude usage of helper file e_coli_iv_funlab.R by defining T1 and T2 directly in the expressions:

# .linp example
Specie  Isotopomer      Value
Gluc_U  111111          {T1=2; T2=2; ppulses(t, c(T1,T2))}
Gluc_1  100000          {T1=2; T2=2; ppulses(t, c(T1,T2))}

Old Result File Fields

Note

Starting from v7.0 results are written in MTF format described above. So this section is kept only for legacy reason and is not more necessary for reading.

Generally speaking, the names of the fields in the result KVH file are chosen to be self-explanatory. So there is no so much to say about them. Here, we provide only some key fields and name conventions used in the result file.

At the beginning of the mynetwork_res.kvh file, some system information is provided. Here, “system” should be taken in two sens: informatics and biological. The information is reported in the fields influx and system sizes. These fields are followed by starting point information regrouping starting free parameters, starting cost value, flux system (Afl) and flux system (bfl). Name conventions used in these and other fields are the following:

net and exchange fluxes

are prefixed by n. or x. respectively

free, dependent, constrained and variable growth fluxes

are prefixed by f., d., c. and g. respectively. So, a complete flux name could look like f.n.zwf which means free net ZWF flux. Growth fluxes which depend on constant specie concentrations can be found in constrained fluxes. Constant or variable growth fluxes are postfixed with _gr (as growth) string. For example, a flux g.n.Cit_gr corresponds to a net growth flux of Citrate specie. The growth fluxes are all set as non-reversible, so all exchange fluxes like g.x.M_gr or c.x.M_gr are set to 0.

scaling factors names

are formed according to a pattern similar to label;Ala;1 which corresponds to the first group of measurements on Alanine molecule in labeling experiments. Other possible types of experiments are peak and mass.

MID vector names

are looking like METAB+N where METAB is specie name and N goes from 0 to the number of carbon atoms in the considered molecule.

cumomer names

follow classical convention METAB#pattern_of_x_and_1, e.g. Ala#x1x

forward and reverse fluxes

are prefixed by fwd. and rev. respectively, e.g. fwd.zwf or rev.zwf

measurement names

have several fields separated by a colon :. For example, l:Asp:#xx1x:694 deciphers like:

• l stands for labeling experiment (others possibilities are p for peak, m for mass and pm for specie pool)

• Asp is a specie name

• #xx1x is a measurement identification

• 694 is a line number in the FTBL file corresponding to this measurement.

The field optimization process information is the key field presenting the results of an optimization process. The fitted parameters are in the subfield par. Other subfields provide some additional information.

The final cost value is in the field final cost.

The values of vectors derived from free fluxes like dependent fluxes, cumomers, MID and so on are in the corresponding fields whose names can be easily recognized.

Linear stats and Monte-Carlo statistics are presented in their respective fields. The latter field is present only if explicitly requested by user with --sens mc=MC option. In this kvh section, a term rsd means “relative standard deviation” (in literature, it is often encountered a synonym CV as Coefficient of Variation). It is calculated as SD/Mean and if expressed in percentage then the formula becomes 100%*SD/Mean.

The field jacobian dr_dp (without 1/sd_exp) report a Jacobian matrix which is defined as a matrix of partial derivatives \(\partial{r}/\partial{p}\) where r is residual vector (Simulated–Measured) and p is a free parameter vector including free fluxes, scaling factors (if any) and free specie pools (if any). Note that in this definition, the residual vector is not yet scaled by standard deviation of measurements. Sometimes, Jacobian is called sensitivity matrix, in which case a special care should be brought to the sens of derivation. Often, by sensitivity matrix, we intend a matrix expressing how estimated fluxes are sensitive to variations in the measurement data. Such definition corresponds to generalized inverse of Jacobian and it is reported in the field generalized inverse of jacobian dr_dp (without 1/sd_exp)

Network values for Cytoscape

Several network values formatted for cytoscape are written by influx_si to their respective files. It can facilitate their visualizing and presentation in graphical mode. All these values can be mapped on various graphical attributes like edge width, node size or color scale of them. These files are written at the end of calculations, so if an error has interrupted this process, no such file will be produced. Take care to don’t use an outdated copy of these files.

A file named edge.netflux.mynetwork.attrs can help to map net flux values on edges of a studied network. A file edge.xchflux.mynetwork.attrs do the same with exchange fluxes. And finally, node.log2pool.mynetwork.attrs provides logarithm (base 2) of pool concentrations. They can be mapped on some graphical attribute of network nodes.

See Additional tools section, ftbl2xgmml: cytoscape view paragraph to know how to produce files importable in Cytoscape from a given MTF set. User’s manual of Cytoscape has necessary information about using visual mapper for teaching how some values like net flux values can be mapped on graphical elements like edge width and so on.

Problematic cases

Obviously, everyone would like be able just run a flux estimation software and simply get results, but unfortunately it does not work in this way every time. In this section, we review some problematic cases which can be encountered in practice.

Structurally non-identifiable fluxes

It can happen that collected data are not sufficient to resolve some fluxes in your network. Due to the non-linear nature of the issue, this situation can appear for some set of free flux values and disappear for others, or be persistent for any free flux values. An error is reported to signal such situation, e.g.

lsi: Rank deficient matrix in least squares
1 unsolvable variable(s):
f.n.PPDK        7

and execution is stopped.

Various options are then available for a user facing such situation.

1. Collect more data to resolve lacking fluxes. As a rule of thumb, data must be collected on species which are the nodes of convergence of badly defined fluxes or on species situated downhill of convergence point and preserving labeling pattern. The nature of collected data can also be important. Examples can be constructed where mass data are not sufficient to determine a flux but RMN data can do the job.

Before using real data collection, you can make a “dry run” with --noopt option and with fictitious or even NA values for intended to collect Isospecie in the .miso file. Thus, we can see if, with these new data, the network becomes well resolved. How? If the error message disappear and SD values in the section linear stats are not very high then chances are that additionally collected data can help to resolve the fluxes.

2. Optimize input label. It can happen that you do collect data on a specie situated in convergence point for undefined fluxes, but incoming fluxes are bringing the same labeling pattern which prevents flux(es) to be resolved. May be changing substrate label can help in this situation. For label optimization you can use a software called IsoDesign, distributed under OpenSource licence and available here http:://metatoul.insa-toulouse.fr/metasys/software/isodes/ (may be you have received influx_si as part of IsoDesign package, in which case you have it already).

Naturally, this label optimization should be done before doing actual experiments. See IsoDesing tutorial for more details on how to prepare and make such optimization.

If you don’t want or don’t have a possibility to use a software for label optimization or you think to have an insight on what should be changed in substrate labeling to better define the fluxes, you can still make a try with influx_s.py --noopt --prefix mynetwork --mtf new_label.linp to see if a new labeling will do the job (here new_label.linp is an example name for a .linp file set that you will prepare with new entries. It is important that --mtf new_label.linp comes after --prefix mynetwork to take precedence over the old one mynetwork.linp)

3. Use --ln option. It won’t make your fluxes well-defined, it will just continue calculation trying to resolve what can be solved and assigning some particular values (issued from so-called least norm solution for rank deficient matrices) to undefined fluxes. You will still have a warning similar to:

lsi_ln: Rank deficient matrix in least squares
1 free variable(s):
f.n.PPDK        7
Least L2-norm solution is provided.

informing you that some flux(es) in the network is(are) still undefined. This option can be helpful if undefined fluxes are without particular interest for the biological question in hand and their actual values can be safely ignored.

4. You can give an arbitrary fixed value to an undefined flux by declaring it as constrained in the .tvar file (letter C in the column Type followed by some value in Value column).

Badly defined fluxes

Also known as statistically undefined fluxes, these fluxes have big or even huge SD values. The difference between these fluxes and structurally undefined fluxes is that the badly defined fluxes can become well defined if the noise is reduced or hypothetically eliminated. While the latter will still be undetermined even in the absence of the noise. Despite this difference, all options presented in the previous section are applicable here (all but --ln which would be without effect here).

An additional measure can be taken which consist in experimental noise reduction. Generally, it can be done by using better protocols, better instruments or simply by increasing the measurement repetition number.

Once again, a use of --noopt with new hoped SD values in the .miso file can help to see if these new measurements with better noise characteristics will resolve or not the problem.

Slow convergence

Slow optimization convergence can manifest by following warnings:

nlsic: Maximal non linear iteration number is achieved

or/and

nlsic: Maximal backtrack iteration number is achieved

Theoretically, user can increase the limit for those two numbers (optctrl:nlsic:maxit and optctrl:nlsic:btmaxit respectively in the .opt file) but generally it is not a good idea. It can help only in very specific situations that we cannot analyze here, as we estimate them low probable. In all cases, a slow convergence is due to high non-linearity of the solved problem. What can vary from one situation to another, it is the nature of this non-linearity. Depending on this nature, several steps can be undertaken to accelerate optimization:

1. If a non-linearity causing the slow convergence is due to the use of function absolute value \(|x|\) in the calculation of forward and revers fluxes from net and exchange fluxes, then an option --zc=ZC (zero crossing) can be very efficient. This non-linearity can become harmful when during optimization a net flux has to change its sign, in other words, it has to cross zero.

This option splits the convergence process in two parts. First, a minimum is searched for fluxes under additional constraints to keep the same sign during this step. Second, for fluxes that reached zero after the first step, a sign change is imposed, and a second optimization is made with these new constraints. If --zc option is used with an argument 0 (--zc=0 or --zc 0), it can happen that fluxes reaching zero produce a singular (non invertible) cumomer balance matrix. In this case, an execution is aborted with an error starting like

Cumomer matrix is singular. Try '--clownr N' or/and '--zc N' options with small N, say 1.e-3 or constrain some of the fluxes listed below to be non zero
...

To avoid such situation, an argument to --zc must be a small positive number, say --zc 0.001. In this case, positive net fluxes are kept over 0.001 and negative fluxes are kept under -0.001 value. In this manner, an exact zero is avoided.

Another way to avoid problem induced by using module function \(|x|\) is to add inequality(-ies) imposing sens of reaction in .cnstr file e.g.

Id      Comment Kind    Formula Operator        Value
                NET     mae     >=              0

Naturally, in this example, you have to be sure that the reaction catalyzed by malic enzyme (here mae) must go in the sens written in your .netw file.

You can find potential candidates to impose sens of reaction by examining the flux values in mynetwork_res.kvh after a slow convergence and looking fluxes whose sign (positive or negative) looks suspicious to you. In our practice, we could observe a dramatic increase in convergence speed and stability just after imposing sens of reaction to a “key” reaction. Obviously, such constraint must be in accordance with biological sens of a studied network and its biological condition.

2. A high non-linearity can appear for some particular set of fluxes, especially when they take extreme values. E.g., when exchange fluxes are close to 1 or net fluxes take very high values of order 10² or even 10³ (supposing that the main entry flux is normalized to 1). In such a case, user can low this limits (options --cupx=CUPX and --cupn=CUPN respectively) or try to exclude outliers (--excl_outliers P-VALUE) as outliers can attract the solution in weird zone of fluxes. In this latter case, the first convergence will continue to be slow and will generate corresponding warnings but the second one (after a possible automatic elimination of outliers) can converge much faster.

Convergence aborted

This situation is signaled by an error message:

nlsic: LSI returned not descending direction

This problem can occur for badly defined network, which are very sensitive to truncation errors. The effect of such errors can become comparable to the effect of the increment step during optimization. It means that we cannot decrease the norm of residual vector under the values resulting from rounding errors. If it happens for relatively small increments, then the results of convergence are still exploitable. If not, there is no so many actions that user could undertake except to make his system better defined as described in previous sections.

Note

By default, we use a very small value for increment norm as stopping criterion (\(10^{-5}\)). It can be considered as very drastic criterion and can be relaxed to \(10^{-3}\) or \(10^{-2}\) depending on required precision for a problem in hand (to do that, use an option optctrl:nlsic:errx in the .opt file).

Additional tools

Tools described in this section are not strictly necessary for running influx_si and calculating the fluxes. But in some cases, they can facilitate the task of tracking and solving potential problems in FTBL preparation and usage.

Most of the utilities produce an output written on standard output or in a file whose name is derived from the input file name. This latter situation is signaled with a phrase “The output redirection is optional” and in the usage examples the output redirection is taken in square brackets [> output.txt] which obviously should be omitted if an actual redirection is required. Such behavior is particularly useful for drag-and-drop usage.

ftbl2mtf: conversion of FTBL to MTF format

For old influx_si users having their projects in FTBL format, this utility can be an invaluable helper for making the transition to the new MTF format. Here is the help message, which can be seen with ftbl2mtf -h

usage: ftbl2mtf [-h] [-i] [-f] [-o OUT] ftbl

Parse ftbl file from first parameter or from stdin (if input file is '-')
and write a series of mtf (multiple TSV files).
The file stem ('network' in 'network.ftbl') is used as file name basis
for produced files, e.g. 'network.miso'. Parameter --out can be used to change it.
If out path includes non existing directories, they are automatically created.
Caution! If an existing output file starts with a comment
"# Created by 'ftbl2mft ..."
or is empty, it is silently overwritten.
Otherwise, the writing is aborted with a warning. Other files may continue to be created.
To force the overwriting, use '--force'.

Output files will have following extensions/meanings:

 .netw: stoichiometric equations and label transitions in the biochemical network;
 .linp: label input;
 .miso: isotopic measurements (MS, label, peak);
 .mflux: flux measurements;
 .mmet: biochemical specie concentration measurements;
 .tvar: flux/specie types partition (free, dependent, constrained) and starting values;
 .cnstr: constraints (equalities, inequalities for both fluxes and concentrations);
 .opt: options.

Copyright 2022 INRAE, INSA, CNRS
Author: Serguei Sokol (sokol [at] insa-toulouse [dot] fr)

positional arguments:
  ftbl               input file to be converted to MTF

optional arguments:
  -h, --help         show this help message and exit
  -i, --inst         activate instationary mode
  -f, --force        force overwriting of result files
  -o OUT, --out OUT  path prefix for result files

txt2ftbl: conversion of MTF format to FTBL format

This tool is implicitly used by influx_si to convert MTF to FTBL format. Users desiring to play with format conversion or to produce FTBL file to be used with Additional tools can use it explicitly. Here is its help message:

usage: txt2ftbl [-h] [--mtf MTF] [--prefix PREFIX] [--eprl EPRL] [--inst] [--force] [netw]

transform a series of TXT and TSV files into FTBL file.

Copyright 2021, INRAE, INSA, CNRS
Author: Serguei Sokol (sokol at insa-toulouse dot fr)
License: Gnu Public License (GPL) v2 http://www.gnu.org/licenses/gpl.html

positional arguments:
  netw
                   If 'netw' file is not given in any option (neither --mtf nor --prefix), it
                   can be given as the only argument NETW, e.g.
                     txt2ftbl ecoli.txt
                   or
                     txt2ftbl --mtf ms_nmr_data.miso,glucose.linp ecoli.txt
                   If 'netw' file name is given both in any option and as an argument, it
                   is the argument value that will take precedence.

optional arguments:
  -h, --help       show this help message and exit
  --mtf MTF        MTF is a coma separated list of files with following extensions/meanings:
                    netw: a text file with stoichiometric reactions and label transitions (one per line)
                       Comments starts with '#' but those starting with '###' introduce
                       pathways which are numbered as well as reactions in them. Reaction
                       name can precede the reaction itself and is separated by ":" If no
                       explicit name is given, reactions in FTBL file will be named
                       according a pattern 'rX.Y' where X is pathway number and Y is
                       reaction number in the pathway. But it is highly recommended to
                       give explicit names to reactions.
                       Symbols "+", "(", ")" and ":" are not allowed in metabolite neither reaction names
                       Example of reaction and label transition:
                          edd: Gnt6P (ABCDEF) -> Pyr (ABC) + GA3P (DEF)
                       Non reversible reactions are signaled with '->' (as in the example above).
                       A sign '<->' can be used for reversible reactions.
                       If 'netw' name is equal to '-', then its content is read from standard input, e.g.
                         '--mtf netw=-'
                    linp: label inputs (starting from this extensions, TSV files are assumed)
                    miso: isotopic measurements (NMR (label, peak) and MS)
                    mflux: flux measurements
                    mmet: metabolite concentration measurements
                    tvar: type of variables (NET or XCH , free or dependent, starting values, ...)
                    cnstr: equality and inequality constraints on fluxes and concentrations
                    opt: options
                    ftbl: name of output FTBL file. If not given, it will be equal to 'netw'
                      stem with '.ftbl' extension. If it is equal to '-', then the result
                      will be written to standard output, e.g.
                        'txt2ftbl --mtf ftbl=-,ecoli.netw'
                      Intermediate directories in ftbl path are silently created if non existent.
                    vmtf: variable part of mtf approach.
                      If a series of FTBL files has to be generated partially with
                      information common to all files (constant part) and partially with
                      sections proper to each FTBL (variable part) then files containing
                      variable sections (e.g. 'miso') can be given in a special file
                      having an extension (or prefix, cf. hereafter) 'vmtf'. In such a
                      way, each FTBL file will be produced from combination of MTF files
                      given directly in this option (constant part) and files given on a
                      corresponding row of 'vmtf' file. vmtf file is a TSV file with
                      columns using the same names: 'netw', 'linp', etc. Each row contains
                      file names that will be used to produce an FTBL file. Thus each row
                      must have 'ftbl' column with unique and non empty name. When 'vmtf'
                      is used, 'ftbl' cannot be present on the command line. If a file
                      type is present both in column names of 'vmtf' and in '--mtf' option
                      then the content of 'vmtf' file will take precedence. Empty values
                      in 'vmtf' file are ignored. All file paths in 'vmtf' file are
                      considered relative to the location of 'vmtf' file itself.
                   Only first 3 files are necessary to obtain a workable FTBL file, others
                   are optional.
                   Example: 'txt2ftbl --mtf ecoli.netw,glu08C1_02U.linp,cond1.miso,cond1.mflux'
                   NB: no space is allowed around comas. If a file path has a spaces in
                   its name, it must be enclosed into quotes or double quotes.
                   If an entry file cannot be renamed to have some of these extensions, then
                   they can be used as prefixes followed by a '=' sign, e.g.
                     'txt2ftbl --mtf netw=ecoli.txt,linp=glu08C1_02U.tsv,cond1.miso,cond1.mflux'
                   As you can see from this example, both naming schemes can be mixed.
                   If for some reason, the same type of file is indicated several times
                   (no matter with extension or prefix), the last occurrence supersedes
                   all precedent ones.
  --prefix PREFIX  If all input files have the same name pattern and are different only
                   in extensions then the pattern can be given as PREFIX, e.g.
                     '--prefix somedir/ecoli'
                   Then in 'somedir', we suppose to have 'ecoli.netw', 'ecoli.linp' and
                   other input files having names starting with 'ecoli' and ending with
                   corresponding extensions.
                   NB. If some file is given in more than one option: '--prefix' and/or
                   '--mtf' then the last occurrence overrides precedent ones.
  --eprl EPRL      Parallel experiments can be given with this option. It must
                   introduce a couple of linp/miso files and optional auxiliary ftbl name. These files
                   correspond to a given parallel experiment. This option can be repeated as
                   many times as there are additional parallel experiments, e.g.
                     'txt2ftbl --mtf ec.netw,glc6.linp,glc6.miso --eprl glc1.linp,glc1.miso --eprl glc4.linp,glc4.miso'
                   This command will produce a main FTBL file 'ec.ftbl' including all necessary
                   sections (NETWORK, etc.) but also two auxiliary FTBL files: 'glc1.ftbl' and
                   'glc4.ftbl' having only label input/measurement sections. They will correspond
                   to 2 additional parallel experiments. If ftbl file is not given in --eprl
                   option, the name of miso file will be used for it. If intermediate
                   directories in ftbl path are non existent they will be silently created.
                   Auxiliary ftbl names will be put in 'OPTIONS/prl_exp' field on the main ftbl file.
                   These names will be written there in a form relative to the main ftbl.
                   To shorten the writings, it is possible to indicate only one of two .miso/.linp files.
                   The other one will be guessed if it has canonical extension. If extension is omitted then .miso and .linp files are searched with these extensions. In this case, several parallel experiments can be given with one --eprl option. So that above example can be shorten to:
                     'txt2ftbl --mtf ec.netw,glc6.linp,glc6.miso --eprl glc1,glc4'
  --inst           Prepare FTBL for instationary case. File 'netw' is supposed to have
                   column 'Time' non empty. Isotopic kinetic data will be written to a TSV
                   file with 'ikin' extension. Its name will be the same as in FTBL file,
                   and FTBL field 'OPTIONS/file_labcin' will contain 'ikin' file name.
  --force          Overwrite an existent result file not produced by this script.
                   NB. If a result file exists and is actually produced by this script,
                   then it is silently overwritten even without this option. The script
                   detects if it was the creator of a file by searching for a string "//
                   Created by 'txt2ftbl" at the first line of the file. By removing or
                   editing this comment, user can protect a file from a silent
                   overwriting.

ftbl2xgmml: Cytoscape view

Once a valid MTF set (or FTBL file) is generated, a user can visualize a graph representing his metabolic network in Cytoscape program. To produce necessary graph files, user can run:

$ ftbl2xgmml.py --prefix mynetwork [> mynetwotk.xgmml]

or:

$ ftbl2xgmml.py mynetwork[.ftbl] [> mynetwotk.xgmml]

or drag and drop mynetwork.ftbl icon on ftbl2xgmml.py icon.

The output redirection is optional.

This will produce a file in the XGMML format mynetwork.xgmml in the directory of mynetwork.netw or mynetwork.ftbl:

Once a generated file mynetwork.xgmml is imported in cytoscape, a user can use one of automatic cytoscape layouts (e.g. ‘Prefuse Force Directed Layout’) or edit node’s disposition in the graph by hand. For those who use CySBML plugin, a saving of a particular layout in a file can be practical for later applying it to a new network.

Graphical conventions used in the generated XGMML are the following:

• specie are presented as rounded square nodes;

• simple (one to one) reaction are represented by simple edges;

• condensing and/or splitting reactions are represented by edges converging and/or diverging from an additional almost invisible node having a label with the reaction name;

• all nodes and edges have tool tips, i.e., when a pointer is put over, their name (specie or reaction) appears in a tiny pop-up window;

• non-reversible reactions are represented by a single solid line, have an arrow on the target end (i.e., produced specie) and nothing on the source end (i.e., consumed specie);

• reversible reactions are represented by a double parallel line and have a solid circle on the source end;

• color code for arrows:

  • green for free net flux;

  • blue for dependent net flux;

  • black for constrained net flux;

• color code for solid circles:

  • green for free exchange flux;

  • blue for dependent exchange flux;

  • black for constrained exchange flux.

ftbl2netan: MTF/FTBL parsing

To see how MTF/FTBL files are parsed and what the parsing module “understands” in the network, a following command can be run:

$ ftbl2netan.py --prefix mynetwork [> mynetwork.netan]

or:

$ ftbl2netan.py mynetwork[.ftbl] [> mynetwork.netan]

The output redirection is optional.

A user can examine mynetwork.netan in vkvh software or in a plain text editor (not like Word) or in spreadsheet software. It has an hierarchical structure, the fields are separated by tabulations and the field values are Python objects converted to strings.

ftbl2cumoAb: human-readable equations

Sometimes, it can be helpful to examine visually the equations used by influx_si. These equations can be produced in human-readable form by running:

$ ftbl2cumoAb.py -r --prefix mynetwork [> mynetwork.sys]

or:

$ ftbl2cumoAb.py -r mynetwork[.ftbl] [> mynetwork.sys]

or:

$ ftbl2cumoAb.py --emu mynetwork[.ftbl] [> mynetwork.sys]

The output redirection is optional.

The result file mynetwork.sys will contain systems of stoichiometric and cumomer balance equations as well as a symbolic inversion of stoichiometric matrix. I.e., dependent fluxes are represented as a linear combination of free and constrained fluxes and an optional constant value. In the examples above, the option -r stands for “reduced cumomer set” and --emu stands for “generate EMU framework equations”. In this latter case, only isotopologues of mass+0 in each EMU are reported in mynetwork.sys file. For other mass weights, the equations does not change and the right-hand side term could get longer for condensation reactions but involves the same EMUs as in mass+0 weight.

If a full cumomer set has to be examined, just omit all options. Keep in mind that on real-world networks this can produce more than a thousand equations by cumomer weight, which could hardly be qualified as human-readable form. So use it with caution.

For the sake of brevity, cumomer names are encoded in decimal integer form. For example, a cumomer Metab#xx1x will be referred as Metab:2 because a binary number 0010 corresponds to a decimal number 2. The binary mask 0010 is obtained from the cumomer mask xx1x by a plain replacement of every x by 0.

For a given cumomer weight, the equations are sorted alphabetically.

expa2ftbl: non-carbon carrying fluxes

Deprecated since v6.0. Such kind of fluxes can be directly incorporated in .netw file.

Some reactions of carbon metabolism require cofactor usage like ATP/ADP and some others. A mass balance on cofactors can produce additional useful constraints on the stoichiometric system. Since the version 2.8, such mass balance equation on non carbon carrying species can be put in EQUATION section of FTBL file. A utility expa2ftbl.R can be helpful for this purpose if a user has already a full set of reactions in expa format. To extract additional equation from an expa file, expa2ftbl.R can be used as:

$ R --vanilla --slave --args file.expa < expa2ftbl.R > file.ftbl_eq

Then an information for the generated file.ftbl_eq has to be manually copy/pasted to a corresponding FTBL file.

Note that expa2ftbl.R uses a Unix command grep and another utility described here above ftbl2netan.py.

res2ftbl_meas: simulated data

Note

Deprecated since v7.0. User can use .miso.sim, .mflux.sim and .mmet.sim as measurement files in a new calculation. E.g.

influx_s --pref mynetwork --mtf \
miso=mynetwork_res/mynetwork.miso.sim,\
mflux=mynetwork_res/mynetwork.mflux.sim \
-o tmp

here, new output directory tmp is used to avoid an overwriting of previous results.

During preparation of a study, one of the questions that biologist can ask is “Will the intended collected data be sufficient for flux resolution in a given network?” Some clue can be obtained by making “dry runs” of influx_si with --noopt (i.e. no optimization) option. User can prepare an FTBL file with a given network and supposed data to be collected. At first, the measurement values can be replaced by NAs while the SD values for measurements must be given in realistic manner. After running:

$ influx_s.py --noopt mynetwork

a utility res2ftbl_meas.py can be practical for preparing FTBL files with obtained simulated measurements:

$ res2ftbl_meas.py res2ftbl_meas.py mynetwork_res[.kvh] > mynetwork.ftbl_meas

(here .kvh suffix is optional). The information from the generated file mynetwork.ftbl_meas has to be manually copy/pasted into the corresponding FTBL file. Getting an ftbl file with real values instead of NAs in measurement sections gives an opportunity to explore optimization behavior near a simulated point like convergence speed and/or convergence stability to cite few of them.

ffres2ftbl: import free fluxes

Note

Deprecated since v7.0. User can use .tvar.sim as starting values in a new calculation. E.g.

influx_s --pref mynetwork --mtf \
tvar=mynetwork_res/mynetwork.tvar.sim \
-o tmp

here, new output directory tmp is used to avoid an overwriting of previous results.

This utility imports free flux values and specie concentrations (if any) from a result file _res.kvh and inject them into an FTBL file. Usage:

$ ffres2ftbl.sh mynetwork_res.kvh [base.ftbl] > new.ftbl

If an optional argument base.ftbl is omitted, then the free flux values are injected into an FTBL file corresponding to the _res.kvh file (here mynetwork.ftbl). This script can be used on a Unix (e.g., Linux, MacOS) or on a cygwin (Unix tools on Windows) platform. It makes use of another utility written in python ff2ftbl.py

ftbl2kvh: check MTF/FTBL parsing

This utility simply parses MTF/FTBL files and write what was “understood” to a kvh file. No network analysis occurs here unlike in ftbl2netan utility. Usage:

$ ftbl2kvh.py --prefix mynetwork [> mynetwork.kvh]

or:

$ ftbl2kvh.py mynetwork[.ftbl] [> mynetwork.kvh]

The output redirection is optional. The resulting mynetwork.kvh is tab-separated plain text file. So it can be explored in vkvh software, plain text editor or spreadsheet software.

ftbl2metxml: prepare MetExplore visualization

Convert a MTF sets (or FTBL files) to an xml files suitable for visualization on MetExplore site. If a result kvh file mynetwork_res.kvh is present, it will be parsed to extract flux values corresponding to the last influx_si run and put them in mynetwok_net.txt, mynetwork_fwd.txt and mynetwork_rev.txt. As their names indicate, they will contain net, forward and revers flux values respectively.

IsoDesign: optimizing input label

One of the means to increase a flux resolution can be an optimization of input label composition. A utility IsoDesing solving this problem was developed by Pierre Millard. It is not part of influx_si distribution and can be downloaded at http://metatoul.insa-toulouse.fr/metasys/software/isodes/. In a nutshell, it works by scanning all possible input label compositions with a defined step, running influx_si on each of them. Then, it collects the SD information on all fluxes for all label compositions and finally selects an input label composition optimal in some sens (according to a criterion chosen by a user).