Unverified Commit ca903af7 authored by Miroslav Kratochvil's avatar Miroslav Kratochvil Committed by St. Elmo
Browse files

[skip ci] simplify generating of the doc index

parent c532e48d
......@@ -32,3 +32,5 @@ temp.*
# add generated tutorial specifics
!docs/src/notebooks/.git-keep
docs/src/notebooks/
# add generated docs and tutorial specifics
docs/src/index.md
......@@ -20,78 +20,104 @@
|:--------------:|:-------:|:---------:|:---------:|
| [![docs-img]][docs-url] | [![CI][ci-img]][ci-url] | [![codecov][cov-img]][cov-url] | [![contrib][contrib-img]][contrib-url] |
This is package provides constraint-based reconstruction and analysis tools for exa-scale metabolic models in Julia.
This is package provides constraint-based reconstruction and analysis tools for
exa-scale metabolic models in Julia.
## How to get started
### Prerequisites and requirements
- **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, we recommend [`Tulip.jl`](https://github.com/ds4dm/Tulip.jl), but any other solver would also work.
- **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.
:bulb: If you are new to Julia, it is advisable to [familiarize yourself with
the environment
first](https://docs.julialang.org/en/v1/manual/getting-started/). Use the Julia [documentation](https://docs.julialang.org) to solve various
first](https://docs.julialang.org/en/v1/manual/getting-started/). Use the
Julia [documentation](https://docs.julialang.org) to solve various
language-related issues, and the [Julia package manager
docs](https://julialang.github.io/Pkg.jl/v1/getting-started/) to solve
installation-related difficulties. Of course, [the Julia channel](https://discourse.julialang.org/) is another fast and easy way to find
installation-related difficulties. Of course, [the Julia
channel](https://discourse.julialang.org/) is another fast and easy way to find
answers to Julia specific questions.
### Quick start guide
### Installation
Using the Julia package manager to install `COBREXA` is straightforward -- after starting Julia, type:
```julia
] add COBREXA
<!--quickstart_begin-->
You can install COBREXA from Julia repositories. Start `julia`, **press `]`** to
switch to the Packaging environment, and type:
```
add COBREXA
```
> All these commands should be run from Julia at the `julia>` prompt.
You also need to install your favorite solver supported by `JuMP.jl`, typing
e.g.:
```
add GLPK
```
Then you can load the `COBREXA` package and start using it through:
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:
```julia
using COBREXA
```
When using `COBREXA` for the first time it may take several minutes to load, due to pre-compilation of the source code and dependencies, especially on a fresh Julia installation.
using COBREXA # loads the package
using GLPK # loads the optimization solver
### Test the installation
# download the model
download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
If you run a non-standard platform (e.g. a customized operating systems), 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:
# open the SBML file and load the contents
model = load_model("e_coli_core.xml")
```julia
] test COBREXA
# run a FBA
fluxes = flux_balance_analysis_dict(model, GLPK.Optimizer)
```
## Quick start guide
<!--start-->
In addition to `COBREXA`, you also need to include a Julia package that provides an appropriate optimizer. One such optimizer for linear programs is `Tulip`, which is provided by the [Tulip.jl](https://github.com/ds4dm/Tulip.jl) package.
```julia
] add Tulip
The variable `fluxes` will now contain a dictionary of the computed optimal
flux of each reaction in the model:
```
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
"R_G6PDH2r" => 4.95998
"R_TALA" => 1.49698
⋮ => ⋮
```
<!--quickstart_end-->
With the package installed and tested, let's perform simple flux balance analysis on a constraint based model.
```julia
using COBREXA
using Tulip
if !isfile("e_coli_core.xml")
download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
end
model = load_model("e_coli_core.xml")
### Testing the installation
sol = flux_balance_analysis_dict(model, Tulip.Optimizer)
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:
sol["BIOMASS_Ecoli_core_w_GAM"] # 0.87
```julia
] test COBREXA
```
<!--stop-->
More functionality is described in the documentation, e.g. model construction and exa-scale analysis in pure Julia.
## Acknowledgements
......
......@@ -25,15 +25,18 @@ for notebook in notebooks
Literate.notebook(notebook, notebooks_outdir)
end
# generate index by cutting example from readme
include(joinpath(@__DIR__, "src", "process_readme.jl"))
Literate.markdown(
joinpath(@__DIR__, "src", "index.jl"),
joinpath(@__DIR__, "src");
preprocess = from_readme,
documenter = false,
# generate index.md from .template and the quickstart in README.md
quickstart = match(
r"<!--quickstart_begin-->\n([^\0]*)<!--quickstart_end-->",
open(f -> read(f, String), joinpath(@__DIR__, "..", "README.md")),
).captures[1]
index_md = replace(
open(f -> read(f, String), joinpath(@__DIR__, "src", "index.md.template")),
"<!--insert_quickstart-->\n" => quickstart,
)
open(f -> write(f, index_md), joinpath(@__DIR__, "src", "index.md"), "w")
# build the docs
makedocs(
modules = [COBREXA],
clean = false,
......
# ```@raw html
# <br>
# <div align="center">
# <img src="assets/header.svg?maxAge=0" width="80%">
# </div>
# <br>
# ```
# # Constraint-Based Reconstruction and EXascale Analysis
# COBREXA is a toolkit for working with large constraint-based metabolic models,
# and running very large number of analysis tasks on these models in parallel.
# Its main purpose is to make the methods of Constraint-based Reconstruction and
# Analysis (COBRA) scale to problem sizes that require the use of huge computer
# clusters and HPC environment, which allows to realistically approach the
# pre-exascale-sized models.
# In the package, you will find the usual COBRA-like functions that inteface to
# the underlying linear programming solvers. We use
# [`JuMP.jl`](https://github.com/jump-dev/JuMP.jl) as the unified interface for
# many solvers; you can plug in whatever compatible solver you want, including
# the popular `Tulip.jl`, `GLPK.jl`, `OSQP.jl`, and `Gurobi`.
# ## Quick start guide
# You can install COBREXA from Julia repositories. Start `julia`, **press `]`** to
# switch to the Packaging environment, and type:
# ```
# add COBREXA
# ```
# You may also need to install your favorite solver, typing e.g.:
# ```
# add GLPK
# ```
# 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:
# ```julia
# using COBREXA # loads the package
# using GLPK # loads your favorite solver
# download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
# model = load_model("e_coli_core.xml")
# fluxes = flux_balance_analysis_dict(model, GLPK.Optimizer)
# ```
# The variable `fluxes` will now contain a dictionary of the computed optimal
# flux of each reaction in the model:
# ```
# 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
# "R_G6PDH2r" => 4.95998
# "R_TALA" => 1.49698
# ⋮ => ⋮
# ```
INSERT_QUICK_START
# ## Tutorials
# Detailed tutorial contents is [available here](tutorials.md).
# ```@contents
# Pages = joinpath.("tutorials", filter(x -> endswith(x, ".md"), readdir("tutorials")))
# Depth = 1
# ```
# ## Example notebooks and workflows
# Detailed notebook content is [available here](notebooks.md).
# ```@contents
# Pages = joinpath.("notebooks", filter(x -> endswith(x, ".md"), readdir("notebooks")))
# Depth = 1
# ```
# ## Functions reference
# ```@contents
# Pages = ["functions.md"]
# ```
# ## Contribution guide
# If you want to contribute, please read [the contribution guidelines and hints](howToContribute.md).
......@@ -23,88 +23,7 @@ the popular `Tulip.jl`, `GLPK.jl`, `OSQP.jl`, and `Gurobi`.
## Quick start guide
You can install COBREXA from Julia repositories. Start `julia`, **press `]`** to
switch to the Packaging environment, and type:
```
add COBREXA
```
You may also need to install your favorite solver, typing e.g.:
```
add GLPK
```
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:
```julia
using COBREXA # loads the package
using GLPK # loads your favorite solver
download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
model = load_model("e_coli_core.xml")
fluxes = flux_balance_analysis_dict(model, GLPK.Optimizer)
```
The variable `fluxes` will now contain a dictionary of the computed optimal
flux of each reaction in the model:
```
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
"R_G6PDH2r" => 4.95998
"R_TALA" => 1.49698
⋮ => ⋮
```
In addition to `COBREXA`, you also need to include a Julia package that provides an appropriate optimizer. One such optimizer for linear programs is `Tulip`, which is provided by the [Tulip.jl](https://github.com/ds4dm/Tulip.jl) package.
```julia
] add Tulip
```
With the package installed and tested, let's perform simple flux balance analysis on a constraint based model.
```julia
using COBREXA
using Tulip
if !isfile("e_coli_core.xml")
download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
end
model = load_model("e_coli_core.xml")
sol = flux_balance_analysis_dict(model, Tulip.Optimizer)
sol["BIOMASS_Ecoli_core_w_GAM"] # 0.87
```
<!--stop-->
More functionality is described in the documentation, e.g. model construction and exa-scale analysis in pure Julia.
## Acknowledgements
`COBREXA.jl` is developed at the Luxembourg Centre for Systems Biomedicine of
the University of Luxembourg ([uni.lu/lcsb](https://www.uni.lu/lcsb)),
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/)).
The development was supported by European Union's Horizon 2020 Programme under
PerMedCoE project ([permedcoe.eu](https://www.permedcoe.eu/)) agreement no.
951773.
<img src="docs/src/assets/unilu.svg" alt="Uni.lu logo" height="64px">   <img src="docs/src/assets/lcsb.svg" alt="LCSB logo" height="64px">   <img src="docs/src/assets/hhu.svg" alt="HHU logo" height="64px">   <img src="docs/src/assets/qtb.svg" alt="QTB logo" height="64px">   <img src="docs/src/assets/permedcoe.svg" alt="PerMedCoE logo" height="64px">
<!--insert_quickstart-->
## Tutorials
......@@ -132,9 +51,6 @@ Pages = ["functions.md"]
## Contribution guide
If you want to contribute, please read [the contribution guidelines and hints](howToContribute.md).
---
*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
If you aim to contribute code, patches or improvements to `COBREXA.jl` read the
basic guidelines at a separate page with [contribution guidelines and
hints](howToContribute.md).
function process_readme()
quick_start_section = ""
add_lines = false
open(joinpath(@__DIR__, "..", "..", "README.md")) do io
for ln in eachline(io)
if !add_lines && startswith(ln, "<!--start-->") # switch on
add_lines = true
continue # skip this line
end
startswith(ln, "<!--end-->") && break
if add_lines
quick_start_section *= "# " * ln * "\n"
end
end
end
return quick_start_section
end
function from_readme(content)
content = replace(content, "INSERT_QUICK_START" => process_readme())
return content
end
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment