Merge pull request #682 from LCSB-BioCore/develop

Develop → master merge for v1.4.1

.github/workflows/CompatHelper.yml

@@ -3,10 +3,29 @@ on:
   schedule:
     - cron: 0 0 * * *
   workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
 jobs:
   CompatHelper:
     runs-on: ubuntu-latest
     steps:
+      - name: Check if Julia is already available in the PATH
+        id: julia_in_path
+        run: which julia
+        continue-on-error: true
+      - name: Install Julia, but only if it is not already available in the PATH
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+          arch: ${{ runner.arch }}
+        if: steps.julia_in_path.outcome != 'success'
+      - name: "Add the General registry via Git"
+        run: |
+          import Pkg
+          ENV["JULIA_PKG_SERVER"] = ""
+          Pkg.Registry.add("General")
+        shell: julia --color=yes {0}
       - name: "Install CompatHelper"
         run: |
           import Pkg

Project.toml

@@ -1,11 +1,12 @@
 name = "COBREXA"
 uuid = "babc4406-5200-4a30-9033-bf5ae714c842"
 authors = ["The developers of COBREXA.jl"]
-version = "1.4.0"
+version = "1.4.1"
 
 [deps]
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 DistributedData = "f6a0035f-c5ac-4ad0-b410-ad102ced35df"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
@@ -22,27 +23,28 @@ StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
+Clarabel = "0.3"
 DistributedData = "0.1.4, 0.2"
+DocStringExtensions = "0.8, 0.9"
 HDF5 = "0.16"
 JSON = "0.21"
-JuMP = "0.21.0, 0.22.0, 0.23, 1"
+JuMP = "1"
 MAT = "0.10"
 MacroTools = "0.5.6"
-OSQP = "0.6"
 OrderedCollections = "1.4"
-SBML = "~1.1"
+SBML = "~1.3"
 StableRNGs = "1.0"
 Tulip = "0.7.0, 0.8.0, 0.9.2"
 julia = "1.5"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+Clarabel = "61c947e1-3e6d-4ee4-985a-eec8c727bd6e"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
-OSQP = "ab2f91bb-94b4-55e3-9ba0-7f65df51de79"
 SHA = "ea8e919c-243c-51af-8825-aaa63cd721ce"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Tulip = "6dd1b50a-3aae-11e9-10b5-ef983d2400fa"
 
 [targets]
-test = ["Aqua", "Downloads", "GLPK", "OSQP", "SHA", "Test", "Tulip"]
+test = ["Aqua", "Clarabel", "Downloads", "GLPK", "SHA", "Test", "Tulip"]

README.md

@@ -84,7 +84,7 @@ add COBREXA
 ```
 
 You also need to install your favorite solver supported by `JuMP.jl` (such as
-Gurobi, Mosek, CPLEX, GLPK, OSQP, etc., see a [list
+Gurobi, Mosek, CPLEX, GLPK, Clarabel, etc., see a [list
 here](https://jump.dev/JuMP.jl/stable/installation/#Supported-solvers)).  For
 example, you can install `Tulip.jl` solver by typing:
 ```

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 COBREXA = "babc4406-5200-4a30-9033-bf5ae714c842"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Clarabel = "61c947e1-3e6d-4ee4-985a-eec8c727bd6e"
 Clustering = "aaaa29a8-35af-508c-8bc3-b662a17a0fe5"
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
@@ -10,7 +11,6 @@ InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-OSQP = "ab2f91bb-94b4-55e3-9ba0-7f65df51de79"
 Tulip = "6dd1b50a-3aae-11e9-10b5-ef983d2400fa"
 
 [compat]

docs/src/examples/05b_fba_mods.jl

@@ -10,7 +10,7 @@
 !isfile("e_coli_core.xml") &&
     download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
 
-using COBREXA, GLPK, Tulip
+using COBREXA, GLPK, Tulip, JuMP
 
 model = load_model("e_coli_core.xml")
 
@@ -33,6 +33,6 @@ fluxes = flux_balance_analysis_dict(
         knockout(["b0978", "b0734"]), # knock out two genes
         change_optimizer(Tulip.Optimizer), # ignore the above optimizer and switch to Tulip
         change_optimizer_attribute("IPM_IterationsLimit", 1000), # customize Tulip
-        change_sense(MAX_SENSE), # explicitly tell Tulip to maximize the objective
+        change_sense(JuMP.MAX_SENSE), # explicitly tell Tulip to maximize the objective
     ],
 )

docs/src/examples/08_pfba.jl

@@ -13,21 +13,21 @@
 !isfile("e_coli_core.xml") &&
     download("http://bigg.ucsd.edu/static/models/e_coli_core.xml", "e_coli_core.xml")
 
-using COBREXA, Tulip, OSQP
+using COBREXA, Tulip, Clarabel
 
 model = load_model("e_coli_core.xml")
 
 # Because the parsimonious objective is quadratic, we need a an optimizer
 # capable of solving quadratic programs.
 #
 # As the simplest choice, we can use
-# [`OSQP.jl`](https://osqp.org/docs/get_started/julia.html), but any any
+# [`Clarabel.jl`](https://osqp.org/docs/get_started/julia.html), but any any
 # [`JuMP.jl`-supported
 # optimizer](https://jump.dev/JuMP.jl/stable/installation/#Supported-solvers)
 # that supports quadratic programming will work.
 
-#md # !!! note "Note: OSQP can be sensitive"
-#md #       We recommend reading the documentation of `OSQP` before using it, since
+#md # !!! note "Note: Clarabel can be sensitive"
+#md #       We recommend reading the documentation of `Clarabel` before using it, since
 #md #       it may give inconsistent results depending on what settings
 #md #       you use. Commercial solvers like `Gurobi`, `Mosek`, `CPLEX`, etc.
 #md #       require less user engagement.
@@ -40,10 +40,9 @@ model = load_model("e_coli_core.xml")
 
 fluxes = parsimonious_flux_balance_analysis_dict(
     model,
-    OSQP.Optimizer;
+    Clarabel.Optimizer;
     modifications = [
-        silence, # optionally silence the optimizer (OSQP is very verbose by default)
-        change_optimizer_attribute("polish", true), # tell OSQP to invest time into improving the precision of the solution
+        silence, # optionally silence the optimizer (Clarabel is very verbose by default)
         change_constraint("R_EX_glc__D_e"; lb = -12, ub = -12), # fix glucose consumption rate
     ],
 )
@@ -69,8 +68,7 @@ flux_vector = parsimonious_flux_balance_analysis_vec(
         change_optimizer_attribute("IPM_IterationsLimit", 500), # we may change Tulip-specific attributes here
     ],
     qp_modifications = [
-        change_optimizer(OSQP.Optimizer), # now switch to OSQP (Tulip wouldn't be able to finish the computation)
-        change_optimizer_attribute("polish", true), # get an accurate solution, see OSQP's documentation
+        change_optimizer(Clarabel.Optimizer), # now switch to Clarabel (Tulip wouldn't be able to finish the computation)
         silence, # and make it quiet.
     ],
 )

docs/src/examples/13_moma.jl

@@ -19,17 +19,14 @@ using COBREXA
 
 model = load_model(StandardModel, "e_coli_core.xml")
 
-# MOMA analysis requires solution of a quadratic model, we will thus use OSQP as the main optimizer.
+# MOMA analysis requires solution of a quadratic model, we will thus use Clarabel as the main optimizer.
 
-using OSQP
+using Clarabel
 
 # We will need a reference solution, which represents the original state of the
 # organism before the change.
-reference_flux = flux_balance_analysis_dict(
-    model,
-    OSQP.Optimizer;
-    modifications = [silence, change_optimizer_attribute("polish", true)],
-)
+reference_flux =
+    flux_balance_analysis_dict(model, Clarabel.Optimizer; modifications = [silence])
 
 # As the change here, we manually knock out CYTBD reaction:
 changed_model = change_bound(model, "R_CYTBD", lower = 0.0, upper = 0.0);
@@ -40,8 +37,8 @@ flux_summary(
     minimize_metabolic_adjustment_analysis_dict(
         changed_model,
         reference_flux,
-        OSQP.Optimizer;
-        modifications = [silence, change_optimizer_attribute("polish", true)],
+        Clarabel.Optimizer;
+        modifications = [silence],
     ),
 )
 
@@ -51,7 +48,7 @@ flux_summary(
 flux_summary(
     flux_balance_analysis_dict(
         changed_model,
-        OSQP.Optimizer;
-        modifications = [silence, change_optimizer_attribute("polish", true)],
+        Clarabel.Optimizer;
+        modifications = [silence],
     ),
 )

docs/src/quickstart.md

@@ -8,7 +8,7 @@ add COBREXA
 ```
 
 You also need to install your favorite solver supported by `JuMP.jl` (such as
-Gurobi, Mosek, CPLEX, GLPK, OSQP, etc., see a [list
+Gurobi, Mosek, CPLEX, GLPK, Clarabel, etc., see a [list
 here](https://jump.dev/JuMP.jl/stable/installation/#Supported-solvers)).  For
 example, you can install `Tulip.jl` solver by typing:
 ```

src/COBREXA.jl

@@ -1,3 +1,28 @@
+"""
+```
+\\\\\\\\\\  // //     | COBREXA.jl  v$(COBREXA.COBREXA_VERSION)
+ \\\\ \\\\// //      |
+  \\\\ \\/ //       | COnstraint-Based Reconstruction
+   \\\\  //        | and EXascale Analysis in Julia
+   //  \\\\        |
+  // /\\ \\\\       | See documentation and examples at:
+ // //\\\\ \\\\      | https://lcsb-biocore.github.io/COBREXA.jl
+// //  \\\\\\\\\\     |
+```
+
+To start up quickly, install your favorite optimizer, load a metabolic model in
+a format such as SBML or JSON, and run a metabolic analysis such as the flux
+balance analysis:
+```
+import Pkg; Pkg.add("GLPK")
+using COBREXA, GLPK
+model = load_model("e_coli_core.xml")
+x = flux_balance_analysis_dict(model, GLPK.Optimizer)
+flux_summary(x)
+```
+
+A complete overview of the functionality can be found in the documentation.
+"""
 module COBREXA
 
 using Distributed
@@ -14,12 +39,17 @@ using Serialization
 using SparseArrays
 using StableRNGs
 using Statistics
+using DocStringExtensions
 
 import Base: findfirst, getindex, show
 import Pkg
 import SBML # conflict with Reaction struct name
 
-include("banner.jl")
+const _PKG_ROOT_DIR = normpath(joinpath(@__DIR__, ".."))
+include_dependency(joinpath(_PKG_ROOT_DIR, "Project.toml"))
+
+const COBREXA_VERSION =
+    VersionNumber(Pkg.TOML.parsefile(joinpath(_PKG_ROOT_DIR, "Project.toml"))["version"])
 
 # autoloading
 const _inc(path...) = include(joinpath(path...))
@@ -34,6 +64,7 @@ _inc_all.(
             joinpath("base", "macros"),
             joinpath("base", "types"),
             joinpath("base", "types", "wrappers"),
+            joinpath("base", "ontologies"),
             "base",
             "io",
             joinpath("io", "show"),

src/analysis/envelopes.jl

@@ -1,6 +1,6 @@
 
 """
-    envelope_lattice(model::MetabolicModel, rids::Vector{String}; kwargs...)
+$(TYPEDSIGNATURES)
 
 Version of [`envelope_lattice`](@ref) that works on string reaction IDs instead
 of integer indexes.
@@ -9,13 +9,7 @@ envelope_lattice(model::MetabolicModel, rids::Vector{String}; kwargs...) =
     envelope_lattice(model, Vector{Int}(indexin(rids, reactions(model))); kwargs...)
 
 """
-    envelope_lattice(
-        model::MetabolicModel,
-        ridxs::Vector{Int};
-        samples = 10,
-        ranges = collect(zip(bounds(model)...))[ridxs],
-        reaction_samples = fill(samples, length(ridxs)),
-    )
+$(TYPEDSIGNATURES)
 
 Create a lattice (list of "tick" vectors) for reactions at indexes `ridxs` in a
 model. Arguments `samples`, `ranges`, and `reaction_samples` may be optionally
@@ -33,7 +27,7 @@ envelope_lattice(
 )
 
 """
-    objective_envelope(model::MetabolicModel, rids::Vector{String}, args...; kwargs...)
+$(TYPEDSIGNATURES)
 
 Version of [`objective_envelope`](@ref) that works on string reaction IDs
 instead of integer indexes.
@@ -47,16 +41,7 @@ objective_envelope(model::MetabolicModel, rids::Vector{String}, args...; kwargs.
     )
 
 """
-    objective_envelope(
-        model::MetabolicModel,
-        ridxs::Vector{Int},
-        optimizer;
-        modifications = [],
-        lattice_args = (),
-        lattice = envelope_lattice(model, ridxs; lattice_args...),
-        analysis = screen_optimize_objective,
-        kwargs...,
-    )
+$(TYPEDSIGNATURES)
 
 Compute an array of objective values for the `model` for rates of reactions
 specified `ridxs` fixed to a regular range of values between their respective

src/analysis/flux_balance_analysis.jl

@@ -1,5 +1,5 @@
 """
-    flux_balance_analysis_vec(model::MetabolicModel, args...)::Maybe{Vector{Float64}}
+$(TYPEDSIGNATURES)
 
 A variant of FBA that returns a vector of fluxes in the same order as reactions
 of the model, if the solution is found.
@@ -17,7 +17,7 @@ flux_balance_analysis_vec(
     flux_vector(model, flux_balance_analysis(model, args...; kwargs...))
 
 """
-    flux_balance_analysis_dict(model::MetabolicModel, args...)::Maybe{Dict{String, Float64}}
+$(TYPEDSIGNATURES)
 
 A variant of FBA that returns a dictionary assigning fluxes to reactions, if
 the solution is found. Arguments are passed to [`flux_balance_analysis`](@ref).
@@ -33,11 +33,7 @@ flux_balance_analysis_dict(
     flux_dict(model, flux_balance_analysis(model, args...; kwargs...))
 
 """
-    flux_balance_analysis(
-        model::M,
-        optimizer;
-        modifications = [],
-    ) where {M<:MetabolicModel}
+$(TYPEDSIGNATURES)
 
 Run flux balance analysis (FBA) on the `model` optionally specifying
 `modifications` to the problem.  Basically, FBA solves this optimization problem: