Metabolic-EP

Expectation Propagation algorithm for metabolic networks

Documentation	Build Status	Coverage

Authors:

Alfredo Braunstein, Anna Paola Muntoni and Andrea Pagnani

Description

This is an implementation of the Expectation Propagation algorithm for studying the space of solution of constrained metabolic fluxes. The main outputs of the m-function are the means and the variances of truncated Gaussian distributions that approximate the marginal probability density of observing a flux, given a stoichiometric matrix and a measure of the intakes/uptakes. This is part of the work:

"An analytic approximation of the feasible space of metabolic networks" - A. Braunstein, A. Muntoni, A. Pagnani - Nature Communications 8, Article number: 14915 (2017) - doi:10.1038/ncomms14915

There are two implementations: one in matlab (under folder matlab), the second in Julia.

Matlab Version

Input

S: stoichiometric matrix of "Nm metabolites" x "Nr reactions"
b: vector of Nm intakes/uptakes
nuinf, nusup: lower and upper bounds for each metabolic flux
Beta: inverse variance of the noise, if any. Otherwise a "large" number (ex. 1e9)
damp: damping coefficient (from 0 to 1) applied to the update of means "a" and variances "d" of approximating Gaussians Ex. "new a" = damp "new a" + (1 - damp) "old a"
max_iter: maximum number of iterations (ex. 1e3)
minvar, maxvar: lower and upper bounds for the variances "d" of the approximation. (ex. 1e-50, 1e50)
precision: precision required to stop the algorithm (ex. 1e-9)

Input (optional) to fix an experimental profile

av_exp: mean of the experimental profile
var_exp: variance of the experimental profile
exp_i: index of the measured flux If no experimental evidence is available, set av_exp = 0, var_exp = 0 and exp_i = 0.

Output

mu: vector parametrizing the mean of the posterior distribution
s: vector parametrizing the variance of the posterior distribution
a: vector containing the means of the approximated priors
d: vector containing the variances of the approximated priors
av: averages of the truncated Gaussians of the approximation
va: variances of the truncated Gaussians of the approximation
t: running time

Julia Version

Installing the package. Enter ] and then:

   (v.1.x)> add https://github.com/anna-pa-m/Metabolic-EP/
   julia> using MetabolicEP

Otherwise, if you do not want to use the package manager:

Clone the package git clone https://github.com/anna-pa-m/Metabolic-EP
cd Metabolic-EP
julia
Enter the pkg manager using ] and type instantiate
julia> using MetabolicEP

It works with version >= 1.5.

Typical usage is

julia> res=metabolicEP(S,b,numin,numax)

The output in res is of type `EPout: there are several fields:

μ::Vector: A parameter linked to the mean of the posterior probability
σ::Vector: A parameter linked to the std of the posterior probability
av::Vector: The mean posterior probability
va::Vector: The variance of the posterior probability
sol::EPFields: The internal field status. From this value we can restart the sampling from a specific state.
status::Symbol: either :converged or :unconverged.

Input (required)

S: MxN matrix (either sparse or dense) please note that if you input a dense version, the algorithm is slighlty more efficient. Dense matrices can be create from sparse ones with full(S).
b: a vector of M intakes/uptakes
nuinf: a vector of lengh N of upper bounds.
nusup: a vector of lengh N of lower bounds.

Input (optional argument).

beta (inverse temperature::Real): default 10^7; the zero temperature algorithm is run setting beta=Inf.
verbose (true or false): default true
damp (∈ (0,1) newfield = damp oldfield + (1-damp) newfield): default 0.9
epsconv (convergence criterion): default 1e-6
maxiter (maximum number of iterations): default 2000
maxvar (threshold on maximum variance): default 1e50
minvar (threshold on minimum variance): default 1e-50
solution (start from solution. Is of type EPout): default: nothing
expval (fix to posterior probability of mean and/or variance to values): default nothing. expval can be either at Tuple{Float64,Float64,Int} or a Vector{Tuple{Float64,Float64,Int}}. Values can be fixed as expval=(0.2,0.4,4) meaning that for flux index 4 the mean is set to 0.2 and the variance to 0.4. Fixing more values expval=[(0.2, 0.3, 4), (0.4, nothing, 5)]: in this case, we fix the posterior of flux 4 to 0.2 (mean) and 0.3 (variance), while for flux 5 we fix the mean to 0.4 and we keep the variance free.

COBRA compatibility

We developed a COBRA compatibility so that now models can be loaded with the COBRA.loadModel() utility metabolicEP can be also run passing a LPproblem type as returned by loadModel.

COBRA has not yet been updated to julia v1.0. For this reason the compatibility has been temporarily removed.

Reading matlab metabolic reconstruction (.mat files)

There is a small convenience reader for metabolic reconstructions in matlab format (.mat). It can be invoked as:

julia> met=ReadMatrix("nomefile.mat")

The output met is of type MetNet whose fields are:

N::Int number of fluxes
M::Int number of metabolites
S::SparseMatrixCSC{Float64,Int} Stoichiometric matrix M x N sparse
b::Array{Float64,1} right hand side of equation S ν = b (vector of size M)
c::Array{Float64,1} reaction index of biomass (vector of size N)
lb::Array{Float64,1} fluxes lower bound N elements vector
ub::Array{Float64,1} fluxes upper bound N elements vector
genes::Array{String,1} gene names N elements vector
rxnGeneMat::SparseMatrixCSC{Float64,Int}
grRules::Array{String,1} gene-reaction rule N elements vector of strings (and / or allowed)
mets::Array{String,1} metabolites short-name M elements
rxns::Array{String,1} reactions short-name N elements
metNames::Array{String,1} metabolites long-names M elements
metFormulas::Array{String,1} metabolites formula M elements
rxnNames::Array{String,1} reactions long-names N elements
rev::Array{Bool,1} reversibility of reactions N elements
subSystems::Array{String,1} cellular component of fluxes N elements

Test model (in folder data): iJR904 model for Escherichia Coli. https://doi.org/10.1093/nar/gkv1049

anna-pa-m / Metabolic-EP

readme