README.md 9.22 KB
Newer Older
1
<br>
Sylvain Arreckx's avatar
Sylvain Arreckx committed
2
3
4
5
<div align="center">
    <img src="docs/src/assets/header.svg?maxAge=0" width="80%">
</div>

St. Elmo's avatar
St. Elmo committed
6
# COnstraint-Based Reconstruction and EXascale Analysis
Laurent Heirendt's avatar
Laurent Heirendt committed
7

8
9
10
11
12
[docs-img-stable]: https://img.shields.io/badge/docs-stable-blue.svg
[docs-url-stable]: https://lcsb-biocore.github.io/COBREXA.jl

[docs-img-dev]: https://img.shields.io/badge/docs-latest-0af.svg
[docs-url-dev]: https://lcsb-biocore.github.io/COBREXA.jl/dev/
13

14
[ci-img]: https://github.com/LCSB-BioCore/COBREXA.jl/actions/workflows/ci.yml/badge.svg?branch=master
Laurent Heirendt's avatar
Laurent Heirendt committed
15
[ci-url]: https://github.com/LCSB-BioCore/COBREXA.jl/actions/workflows/ci.yml
St. Elmo's avatar
St. Elmo committed
16

Laurent Heirendt's avatar
Laurent Heirendt committed
17
[cov-img]: https://codecov.io/gh/LCSB-BioCore/COBREXA.jl/branch/master/graph/badge.svg?token=H3WSWOBD7L
Laurent Heirendt's avatar
Laurent Heirendt committed
18
[cov-url]: https://codecov.io/gh/LCSB-BioCore/COBREXA.jl
St. Elmo's avatar
St. Elmo committed
19

Laurent Heirendt's avatar
Laurent Heirendt committed
20
21
[contrib-img]: https://img.shields.io/badge/contributions-start%20here-green
[contrib-url]: https://github.com/LCSB-BioCore/COBREXA.jl/blob/master/.github/CONTRIBUTING.md
St. Elmo's avatar
St. Elmo committed
22

St. Elmo's avatar
St. Elmo committed
23
24
25
26
27
28
[repostatus-url]: https://www.repostatus.org/#active
[repostatus-img]: https://www.repostatus.org/badges/latest/active.svg

| **Documentation** | **Tests** | **Coverage** | **How to contribute?** | **Project status** |
|:--------------:|:-------:|:---------:|:---------:|:---------:|
| [![docs-img-stable]][docs-url-stable] [![docs-img-dev]][docs-url-dev] | [![CI][ci-img]][ci-url] | [![codecov][cov-img]][cov-url] | [![contrib][contrib-img]][contrib-url] | [![repostatus-img]][repostatus-url] |
St. Elmo's avatar
St. Elmo committed
29

30
31
This is package provides constraint-based reconstruction and analysis tools for
exa-scale metabolic models in Julia.
St. Elmo's avatar
St. Elmo committed
32

33
## How to get started
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
34

35
### Prerequisites and requirements
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
36

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
- **Operating system**: Use Linux (Debian, Ubuntu or centOS), MacOS, or Windows
  10 as your operating system. `COBREXA` has been tested on these systems.
- **Julia language**: In order to use `COBREXA`, you need to install Julia 1.0
  or higher. Download and follow the installation instructions for Julia
  [here](https://julialang.org/downloads/).
- **Hardware requirements**: `COBREXA` runs on any hardware that can run Julia,
  and can easily use resources from multiple computers interconnected on a
  network. For processing large datasets, you are required to ensure that the
  total amount of available RAM on all involved computers is larger than the
  data size.
- **Optimization solvers**: `COBREXA` uses
  [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) to formulate optimization
  problems and is compatible with all [`JuMP` supported
  solvers](https://jump.dev/JuMP.jl/stable/installation/#Supported-solvers).
  However, to perform analysis at least one of these solvers needs to be
  installed on your machine. For a pure Julia implementation, you may use e.g.
  [`Tulip.jl`](https://github.com/ds4dm/Tulip.jl), but other solvers (GLPK,
  Gurobi, ...) work just as well.
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
55

St. Elmo's avatar
St. Elmo committed
56
:bulb: If you are new to Julia, it is advisable to [familiarize yourself with
57
the environment
58
59
first](https://docs.julialang.org/en/v1/manual/getting-started/).  Use the
Julia [documentation](https://docs.julialang.org) to solve various
60
61
language-related issues, and the [Julia package manager
docs](https://julialang.github.io/Pkg.jl/v1/getting-started/) to solve
62
63
installation-related difficulties. Of course, [the Julia
channel](https://discourse.julialang.org/) is another fast and easy way to find
St. Elmo's avatar
St. Elmo committed
64
answers to Julia specific questions.
65

66
### Quick start guide
67

68
<!--quickstart_begin-->
69
70
You can install COBREXA from Julia repositories. Start `julia`, **press `]`** to
switch to the Packaging environment, and type:
71
```
72
add COBREXA
73
74
```

75
76
77
You also need to install your favorite solver supported by `JuMP.jl`, typing
e.g.:
```
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
78
add Tulip
79
```
80

81
82
83
84
85
When the packages are installed, switch back to the "normal" julia shell by
pressing Backspace (the prompt should change color back to green). After that,
you can download [a SBML model from the
internet](http://bigg.ucsd.edu/models/e_coli_core) and perform a
flux balance analysis as follows:
86
87

```julia
88
using COBREXA   # loads the package
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
89
using Tulip     # loads the optimization solver
90

91
92
# download the model
download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
St. Elmo's avatar
St. Elmo committed
93

94
95
# open the SBML file and load the contents
model = load_model("e_coli_core.xml")
St. Elmo's avatar
St. Elmo committed
96

97
# run a FBA
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
98
fluxes = flux_balance_analysis_dict(model, Tulip.Optimizer)
99
```
St. Elmo's avatar
St. Elmo committed
100

101
102
The variable `fluxes` will now contain a dictionary of the computed optimal
flux of each reaction in the model:
103
```
104
105
106
107
108
109
110
111
112
Dict{String,Float64} with 95 entries:
  "R_EX_fum_e"    => 0.0
  "R_ACONTb"      => 6.00725
  "R_TPI"         => 7.47738
  "R_SUCOAS"      => -5.06438
  "R_GLNS"        => 0.223462
  "R_EX_pi_e"     => -3.2149
  "R_PPC"         => 2.50431
  "R_O2t"         => 21.7995
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
113
  "R_G6PDH2r"     => 4.95999
114
115
116
  "R_TALA"        => 1.49698
  ⋮               => ⋮
```
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204

#### Model variant processing

The main feature of COBREXA.jl is the ability to easily specify and process
many analyses at once, in parallel. Let's see how the organism would perform if
some reactions were disabled:

```julia
# convert to a model type that is easy to modify
m = convert(StandardModel, m)

# find the model objective value if oxygen and carbon dioxide transports are disabled
screen(m,
    variants=[
        [], # no modifications
        [with_changed_bound("O2t", lower=0.0, upper=0.0)], # disable oxygen
        [with_changed_bound("CO2t", lower=0.0, upper=0.0)], # disable CO2
        [with_changed_bound("O2t", lower=0.0, upper=0.0),
	 with_changed_bound("CO2t", lower=0.0, upper=0.0)], # disable both
    ],
    analysis = x -> flux_balance_analysis_dict(x, Tulip.Optimizer)["BIOMASS_Ecoli_core_w_GAM"],
)
```
You should receive a result showing that missing oxygen transport makes the
biomass production much harder:
```julia
4-element Vector{Float64}:
 0.8739215022674809
 0.21166294973372796
 0.46166961413944896
 0.21114065173865457
```

Most importantly, such analyses can be easily specified by automatically
generating long lists of the modifications to apply to the model, and
parallelized:

```julia
# load the task distribution package, add several worker nodes, and load
# COBREXA and the solver on the nodes
using Distributed
addprocs(4)
@everywhere using COBREXA, Tulip

# get a list of the workers
worker_list = workers()

# run the processing in parallel for many model variants
res = screen(m,
    variants=[
	# specify one variant for each reaction in the model, with that reaction knocked out
        [with_changed_bound(reaction_id, lower=0.0, upper=0.0)]
	for reaction_id in reactions(m)
    ],
    analysis = model -> begin
	# we need to check if the model even found a feasible solution, which
	# may not be the case if we knock out important reactions
    	sol = flux_balance_analysis_dict(model, Tulip.Optimizer)
	isnothing(sol) ? nothing : sol["BIOMASS_Ecoli_core_w_GAM"]
    end,
    # run the screening in parallel on all workers from the list
    workers = worker_list,
)
```

In result, you should get a long list of the biomass production for each
reaction knockout. Let's decorate it with reaction names:
```julia
Dict(reactions(m) .=> res)
```
...which should output an easily accessible dictionary with all the objective
values named, giving a quick overview of which reactions are critical for the
model organism to create biomass:
```julia
Dict{String, Union{Nothing, Float64}} with 95 entries:
  "ACALD"       => 0.873922
  "PTAr"        => 0.873922
  "ALCD2x"      => 0.873922
  "PDH"         => 0.796696
  "PYK"         => 0.864926
  "CO2t"        => 0.46167
  "EX_nh4_e"    => 1.44677e-15
  "MALt2_2"     => 0.873922
  "CS"          => 2.44779e-14
  "PGM"         => 1.04221e-15
  "TKT1"        => 0.864759
               => 
```
205
<!--quickstart_end-->
206

207
### Testing the installation
St. Elmo's avatar
St. Elmo committed
208

209
210
211
If you run a non-standard platform (e.g. a customized operating system), or if
you added any modifications to the `COBREXA` source code, you may want to run
the test suite to ensure that everything works as expected:
St. Elmo's avatar
St. Elmo committed
212

213
214
```julia
] test COBREXA
St. Elmo's avatar
St. Elmo committed
215
216
```

Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
217
<!--acknowledgements_begin-->
218
219
220
## Acknowledgements

`COBREXA.jl` is developed at the Luxembourg Centre for Systems Biomedicine of
221
the University of Luxembourg ([uni.lu/lcsb](https://wwwen.uni.lu/lcsb)),
St. Elmo's avatar
St. Elmo committed
222
223
cooperating with the Institute for Quantitative and Theoretical Biology at the Heinrich
Heine University in Düsseldorf ([qtb.hhu.de](https://www.qtb.hhu.de/)).
224
225

The development was supported by European Union's Horizon 2020 Programme under
226
PerMedCoE project ([permedcoe.eu](https://permedcoe.eu/)) agreement no. 951773.
Miroslav Kratochvil's avatar
Miroslav Kratochvil committed
227
228
229
230
231
<!--acknowledgements_end-->

<!--ack_logos_begin-->
<img src="https://lcsb-biocore.github.io/COBREXA.jl/stable/assets/cobrexa.svg" alt="COBREXA logo" height="64px" style="height:64px; width:auto">   <img src="https://lcsb-biocore.github.io/COBREXA.jl/stable/assets/unilu.svg" alt="Uni.lu logo" height="64px" style="height:64px; width:auto">   <img src="https://lcsb-biocore.github.io/COBREXA.jl/stable/assets/lcsb.svg" alt="LCSB logo" height="64px" style="height:64px; width:auto">   <img src="https://lcsb-biocore.github.io/COBREXA.jl/stable/assets/hhu.svg" alt="HHU logo" height="64px" style="height:64px; width:auto">   <img src="https://lcsb-biocore.github.io/COBREXA.jl/stable/assets/qtb.svg" alt="QTB logo" height="64px" style="height:64px; width:auto">   <img src="https://lcsb-biocore.github.io/COBREXA.jl/stable/assets/permedcoe.svg" alt="PerMedCoE logo" height="64px" style="height:64px; width:auto">
<!--ack_logos_end-->