Merge pull request #441 from LCSB-BioCore/mk-envelope-example

add an example for objective_envelope

src/analysis/envelopes.jl

@@ -19,7 +19,7 @@ envelope_lattice(model::MetabolicModel, rids::Vector{String}; kwargs...) =
 
 Create a lattice (list of "tick" vectors) for reactions at indexes `ridxs` in a
 model. Arguments `samples`, `ranges`, and `reaction_samples` may be optionally
-specified to customize the latice creation process.
+specified to customize the lattice creation process.
 """
 envelope_lattice(
     model::MetabolicModel,
@@ -35,7 +35,7 @@ envelope_lattice(
 """
     objective_envelope(model::MetabolicModel, rids::Vector{String}, args...; kwargs...)
 
-Versioin of [`objective_envelope`](@ref) that works on string reaction IDs
+Version of [`objective_envelope`](@ref) that works on string reaction IDs
 instead of integer indexes.
 """
 objective_envelope(model::MetabolicModel, rids::Vector{String}, args...; kwargs...) =
@@ -51,7 +51,8 @@ objective_envelope(model::MetabolicModel, rids::Vector{String}, args...; kwargs.
         model::MetabolicModel,
         ridxs::Vector{Int},
         optimizer;
-        lattice = envelope_lattice(model, ridxs),
+        lattice_args = (),
+        lattice = envelope_lattice(model, ridxs; lattice_args...),
         kwargs...,
     )
 
@@ -71,15 +72,42 @@ Returns a named tuple that contains `lattice` with reference values of the
 metabolites, and an N-dimensional array `values` with the computed objective
 values, where N is the number of specified reactions.  Because of the
 increasing dimensionality, the computation gets very voluminous with increasing
-length of `ridxs`.
+length of `ridxs`. The `lattice` for computing the optima can be supplied in
+the argument; by default it is created by [`envelope_lattice`](@ref) called on
+the model and reaction indexes. Additional arguments for the call to
+[`envelope_lattice`](@ref) can be optionally specified in `lattice_args`.
 
 `kwargs` are internally forwarded to [`screen_optmodel_modifications`](@ref).
+
+# Example
+```
+julia> m = load_model("test/downloaded/e_coli_core.xml");
+
+julia> envelope = objective_envelope(m, ["R_EX_gln__L_e", "R_EX_fum_e"],
+                                     Tulip.Optimizer;
+                                     lattice_args=(samples=6,));
+
+julia> envelope.lattice   # the reaction rates for which the optima were computed
+2-element Vector{Vector{Float64}}:
+ [0.0, 200.0, 400.0, 600.0, 800.0, 1000.0]
+ [0.0, 200.0, 400.0, 600.0, 800.0, 1000.0]
+
+julia> envelope.values   # the computed flux objective values for each reaction rate combination
+6×6 Matrix{Float64}:
+  0.873922   9.25815  17.4538  19.56   20.4121  20.4121
+ 13.0354    17.508    19.9369  21.894  22.6825  22.6825
+ 16.6666    18.6097   20.2847  21.894  22.6825  22.6825
+ 16.6666    18.6097   20.2847  21.894  22.6825  22.6825
+ 16.6666    18.6097   20.2847  21.894  22.6825  22.6825
+ 16.6666    18.6097   20.2847  21.894  22.6825  22.6825
+```
 """
 objective_envelope(
     model::MetabolicModel,
     ridxs::Vector{Int},
     optimizer;
-    lattice = envelope_lattice(model, ridxs),
+    lattice_args = (),
+    lattice = envelope_lattice(model, ridxs; lattice_args...),
     kwargs...,
 ) = (
     lattice = collect.(lattice),