Merge pull request #651 from LCSB-BioCore/develop

Develop → master merge for 1.4

.github/workflows/pr-cmd-format.yml → .github/workflows/pr-format.yml

@@ -1,27 +1,27 @@
-
 on:
+ pull_request:
  issue_comment:
  types: [created]
 
-name: PR auto-formatting command
+name: Formatting
 
 jobs:
- format:
- if: ${{ github.event.issue.pull_request && (github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'OWNER' || github.event.issue.user.id == github.event.comment.user.id) && startsWith(github.event.comment.body, '/format') }}
- name: auto-format
+ formatting:
+ if: github.event_name == 'pull_request' || (github.event_name == 'issue_comment' && github.event.issue.pull_request && (github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'COLLABORATOR' || github.event.comment.author_association == 'OWNER' || github.event.issue.user.id == github.event.comment.user.id) && startsWith(github.event.comment.body, '/format') )
  runs-on: ubuntu-latest
  steps:
  - name: Clone the repository
- uses: actions/checkout@v2
- - name: Checkout the pull request code
+ uses: actions/checkout@v3
+ - name: Checkout the pull request code # this checks out the actual branch so that one can commit into it
+ if: github.event_name == 'issue_comment'
  env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
  gh pr checkout ${{ github.event.issue.number }}
  - name: Install JuliaFormatter and format
  run: |
- julia -e 'import Pkg; Pkg.add("JuliaFormatter")'
- julia -e 'using JuliaFormatter; format(".")'
+ julia --color=yes -e 'import Pkg; Pkg.add("JuliaFormatter")'
+ julia --color=yes -e 'using JuliaFormatter; format(".")'
  - name: Remove trailing whitespace
  run: |
  find -name '*.jl' -or -name '*.md' -or -name '*.toml' -or -name '*.yml' | while read filename ; do
@@ -34,7 +34,15 @@ jobs:
  # squash superfluous final newlines
  sed -i -e :a -e '/^\n*$/{$d;N;};/\n$/ba' "$filename"
  done
- - name: Commit and push the changes
+ - name: Fail on formatting problems
+ if: github.event_name == 'pull_request'
+ run: |
+ if git diff --exit-code --quiet
+ then echo "Looks OK"
+ else echo "Formatting fixes required!"; git diff -p ; exit 1
+ fi
+ - name: Commit fixes
+ if: github.event_name == 'issue_comment'
  env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
@@ -44,10 +52,11 @@ jobs:
  git commit -a -m "automatic formatting" -m "triggered by @$GITHUB_ACTOR on PR #${{ github.event.issue.number }}"
  if git push
  then gh pr comment ${{ github.event.issue.number }} --body \
- ":heavy_check_mark: auto-formatting triggered by [this comment](${{ github.event.comment.html_url }}) succeeded, commited as `git rev-parse HEAD`"
+ ":heavy_check_mark: Auto-formatting triggered by [this comment](${{ github.event.comment.html_url }}) succeeded, commited as `git rev-parse HEAD`"
  else gh pr comment ${{ github.event.issue.number }} --body \
- ":x: auto-formatting triggered by [this comment](${{ github.event.comment.html_url }}) failed, perhaps someone pushed to the PR in the meantime?"
+ ":x: Auto-formatting triggered by [this comment](${{ github.event.comment.html_url }}) failed, perhaps someone pushed to the PR in the meantime?"
  fi
  else
- echo "No changes, all good!"
+ gh pr comment ${{ github.event.issue.number }} --body \
+ ":sunny: Auto-formatting triggered by [this comment](${{ github.event.comment.html_url }}) succeeded, but the code was already formatted correctly."
  fi

.gitignore

@@ -17,6 +17,7 @@ docs/site/
 *.mat
 *.xml
 *.json
+*.h5
 *.jl.*.cov
 .*.swp
 
@@ -33,8 +34,8 @@ temp.*
 .ipynb_checkpoints
 
 # add generated tutorial specifics
-docs/src/notebooks/*
-!docs/src/notebooks/*.jl
+docs/src/examples/*
+!docs/src/examples/*.jl
 
 # add generated docs and tutorial specifics
 docs/src/index.md

Project.toml

@@ -1,11 +1,12 @@
 name = "COBREXA"
 uuid = "babc4406-5200-4a30-9033-bf5ae714c842"
 authors = ["The developers of COBREXA.jl"]
-version = "1.3.1"
+version = "1.4.0"
 
 [deps]
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 DistributedData = "f6a0035f-c5ac-4ad0-b410-ad102ced35df"
+HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -22,13 +23,14 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 DistributedData = "0.1.4, 0.2"
+HDF5 = "0.16"
 JSON = "0.21"
 JuMP = "0.21.0, 0.22.0, 0.23, 1"
 MAT = "0.10"
 MacroTools = "0.5.6"
 OSQP = "0.6"
 OrderedCollections = "1.4"
-SBML = "0.10.0"
+SBML = "~1.1"
 StableRNGs = "1.0"
 Tulip = "0.7.0, 0.8.0, 0.9.2"
 julia = "1.5"

README.md

@@ -11,6 +11,9 @@
 [docs-img-dev]: https://img.shields.io/badge/docs-latest-0af.svg
 [docs-url-dev]: https://lcsb-biocore.github.io/COBREXA.jl/dev/
 
+[docs-url-quickstart]: https://lcsb-biocore.github.io/COBREXA.jl/stable/quickstart/
+[docs-url-examples]: https://lcsb-biocore.github.io/COBREXA.jl/stable/examples/
+
 [docker-url]: https://hub.docker.com/r/lcsbbiocore/cobrexa.jl
 [docker-img]: https://img.shields.io/docker/image-size/lcsbbiocore/cobrexa.jl
 
@@ -66,7 +69,12 @@ 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
+### Quick start
+
+[COBREXA.jl documentation][docs-url-stable]
+is available online (also for
+[development version][docs-url-dev]
+of the package).
 
 <!--quickstart_begin-->
 You can install COBREXA from Julia repositories. Start `julia`, **press `]`** to
@@ -75,14 +83,21 @@ switch to the Packaging environment, and type:
 add COBREXA
 ```
 
-You also need to install your favorite solver supported by `JuMP.jl`, typing
-e.g.:
+You also need to install your favorite solver supported by `JuMP.jl` (such as
+Gurobi, Mosek, CPLEX, GLPK, OSQP, etc., see a [list
+here](https://jump.dev/JuMP.jl/stable/installation/#Supported-solvers)). For
+example, you can install `Tulip.jl` solver by typing:
 ```
 add Tulip
 ```
 
 Alternatively, you may use [prebuilt Docker and Apptainer images](#prebuilt-images).
 
+If you are running COBREXA.jl for the first time, it is very likely that upon
+installing and importing the packages, your Julia installation will need to
+precompile their source code from the scratch. In fresh installations, the
+precompilation process should take less than 5 minutes.
+
 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
@@ -119,100 +134,13 @@ Dict{String,Float64} with 95 entries:
  "R_TALA" => 1.49698
  ⋮ => ⋮
 ```
-
-#### Model variant processing
-
-The main feature of COBREXA.jl is the ability to easily specify and process
-many analyses in parallel. To demonstrate, let's see how the organism would perform if
-some reactions were disabled independently:
-
-```julia
-# convert to a model type that is efficient to modify
-m = convert(StandardModel, model)
-
-# find the model objective value if oxygen or carbon dioxide transports are disabled
-screen(m, # the base model
- variants=[ # this specifies how to generate the desired model variants
- [], # one with no modifications, i.e. the base case
- [with_changed_bound("R_O2t", lower=0.0, upper=0.0)], # disable oxygen
- [with_changed_bound("R_CO2t", lower=0.0, upper=0.0)], # disable CO2
- [with_changed_bound("R_O2t", lower=0.0, upper=0.0),
- with_changed_bound("R_CO2t", lower=0.0, upper=0.0)], # disable both
- ],
- # this specifies what to do with the model variants (received as the argument `x`)
- analysis = x ->
- flux_balance_analysis_dict(x, Tulip.Optimizer)["R_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 modifications to be applied to the model, and
-parallelized.
-
-Knocking out each reaction in the model is efficiently accomplished:
-
-```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=[
- # create 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 optimizer 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 in 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
- ⋮ => ⋮
-```
 <!--quickstart_end-->
 
+The main feature of COBREXA.jl is the ability to easily specify and process a
+huge number of analyses in parallel. You. You can have a look at a
+[longer guide that describes the parallelization and screening functionality][docs-url-quickstart],
+or dive into the [example analysis workflows][docs-url-examples].
+
 ### Testing the installation
 
 If you run a non-standard platform (e.g. a customized operating system), or if
@@ -262,7 +190,8 @@ The development was supported by European Union's Horizon 2020 Programme under
 PerMedCoE project ([permedcoe.eu](https://permedcoe.eu/)) agreement no. 951773.
 <!--acknowledgements_end-->
 
-If you use COBREXA.jl and want to refer to it in your work, use the following citation format (also available as BibTeX in [cobrexa.bib](cobrexa.bib)):
+If you use COBREXA.jl and want to refer to it in your work, use the following
+citation format (also available as BibTeX in [cobrexa.bib](cobrexa.bib)):
 
 > Miroslav Kratochvíl, Laurent Heirendt, St Elmo Wilken, Taneli Pusa, Sylvain Arreckx, Alberto Noronha, Marvin van Aalst, Venkata P Satagopam, Oliver Ebenhöh, Reinhard Schneider, Christophe Trefois, Wei Gu, *COBREXA.jl: constraint-based reconstruction and exascale analysis*, Bioinformatics, Volume 38, Issue 4, 15 February 2022, Pages 1171–1172, https://doi.org/10.1093/bioinformatics/btab782
 

docs/Project.toml

@@ -1,10 +1,12 @@
 [deps]
-CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 COBREXA = "babc4406-5200-4a30-9033-bf5ae714c842"
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Clustering = "aaaa29a8-35af-508c-8bc3-b662a17a0fe5"
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Escher = "8cc96de1-1b23-48cb-9272-618d67962629"
 GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"