clean up analysis documentation and examples

Closes #318

src/analysis/flux_balance_analysis.jl

@@ -50,17 +50,21 @@ The `optimizer` must be set to a `JuMP`-compatible optimizer, such as
 `GLPK.Optimizer` or `Tulip.Optimizer`
 
 Optionally, you may specify one or more modifications to be applied to the
-model before the analysis, such as
-[`change_optimizer_attribute`](@ref),[`change_objective`](@ref), and
-[`change_sense`](@ref).
+model before the analysis, such as [`change_optimizer_attribute`](@ref),
+[`change_objective`](@ref), and [`change_sense`](@ref).
 
 Returns an optimized `JuMP` model.
 
 # Example
 ```
-model = load_model(StandardModel, "e_coli_core.json")
-biomass = findfirst(model.reactions, "BIOMASS_Ecoli_core_w_GAM")
-solution = flux_balance_analysis(model, GLPK.optimizer; modifications=[change_objective(biomass)])
+model = load_model("e_coli_core.json")
+solution = flux_balance_analysis(model, GLPK.optimizer)
+value.(solution[:x])  # extract flux steady state from the optimizer
+
+biomass_reaction_id = findfirst(model.reactions, "BIOMASS_Ecoli_core_w_GAM")
+
+modified_solution = flux_balance_analysis(model, GLPK.optimizer;
+    modifications=[change_objective(biomass_reaction_id)])
 ```
 
 """

src/analysis/flux_variability_analysis.jl

@@ -19,9 +19,8 @@ s.t. S x = b
      cᵀx ≤ bounds(Z₀)[2]
 ```
 where Z₀:= cᵀx₀ is the objective value of an optimal solution of the associated
-FBA problem (see [`flux_balance_analysis`](@ref)). See "Gudmundsson, S., Thiele,
-I. Computationally efficient flux variability analysis. BMC Bioinformatics 11,
-489 (2010). https://doi.org/10.1186/1471-2105-11-489" for more information.
+FBA problem (see [`flux_balance_analysis`](@ref) for a related analysis, also
+for explanation of the `modifications` argument).
 
 The `bounds` is a user-supplied function that specifies the objective bounds
 for the variability optimizations, by default it restricts the flux objective
@@ -43,6 +42,12 @@ Returns a matrix of extracted `ret` values for minima and maxima, of total size
 (`length(reactions)`,2). The optimizer result status is checked with
 [`is_solved`](@ref); `nothing` is returned if the optimization failed for any
 reason.
+
+# Example
+```
+model = load_model("e_coli_core.json")
+flux_variability_analysis(model, [1, 2, 3, 42], GLPK.optimizer)
+```
 """
 function flux_variability_analysis(
     model::MetabolicModel,
@@ -98,7 +103,8 @@ end
         kwargs...
     )
 
-A simpler version of [`flux_variability_analysis`](@ref) that maximizes and minimizes all reactions in the model. Arguments are forwarded.
+A simpler version of [`flux_variability_analysis`](@ref) that maximizes and
+minimizes all reactions in the model. Arguments are forwarded.
 """
 function flux_variability_analysis(model::MetabolicModel, optimizer; kwargs...)
     n = n_reactions(model)

src/analysis/parsimonious_flux_balance_analysis.jl

@@ -35,7 +35,8 @@ pFBA gets the model optimum by standard FBA (using
 finds a minimal total flux through the model that still satisfies the (slightly
 relaxed) optimum. This is done using a quadratic problem optimizer. If the
 original optimizer does not support quadratic optimization, it can be changed
-using the callback in `qp_modifications`, which are applied after the FBA.
+using the callback in `qp_modifications`, which are applied after the FBA. See
+the documentation of flux_balance_analysis for usage examples of modifications.
 
 Thhe optimum relaxation sequence can be specified in `relax` parameter, it
 defaults to multiplicative range of `[1.0, 0.999999, ..., 0.99]` of the
@@ -46,11 +47,9 @@ optimization failed.
 
 # Example
 ```
-optimizer = Gurobi.Optimizer
-atts = Dict("OutputFlag" => 0)
-model = load_model(StandardModel, "iJO1366.json")
-biomass = findfirst(model.reactions, "BIOMASS_Ec_iJO1366_WT_53p95M")
-sol = pfba(model, biomass, Gurobi.optimizer)
+model = load_model("e_coli_core.json")
+optmodel = parsimonious_flux_balance_analysis(model, biomass, Gurobi.Optimizer)
+value.(solution[:x])  # extract the flux from the optimizer
 ```
 """
 function parsimonious_flux_balance_analysis(
@@ -97,9 +96,10 @@ end
 """
     parsimonious_flux_balance_analysis_vec(args...; kwargs...)
 
-Perform parsimonious flux balance analysis on `model` using `optimizer`. 
-Returns a vector of fluxes in the same order as the reactions in `model`. 
-Arguments are forwarded to [`parsimonious_flux_balance_analysis`](@ref) internally.
+Perform parsimonious flux balance analysis on `model` using `optimizer`.
+Returns a vector of fluxes in the same order as the reactions in `model`.
+Arguments are forwarded to [`parsimonious_flux_balance_analysis`](@ref)
+internally.
 """
 function parsimonious_flux_balance_analysis_vec(args...; kwargs...)
     opt_model = parsimonious_flux_balance_analysis(args...; kwargs...)
@@ -112,9 +112,9 @@ end
 """
     parsimonious_flux_balance_analysis_dict(model::MetabolicModel, args...; kwargs...)
 
-Perform parsimonious flux balance analysis on `model` using `optimizer`. 
-Returns a dictionary mapping the reaction IDs to fluxes. 
-Arguments are forwarded to [`parsimonious_flux_balance_analysis`](@ref) internally.
+Perform parsimonious flux balance analysis on `model` using `optimizer`.
+Returns a dictionary mapping the reaction IDs to fluxes. Arguments are
+forwarded to [`parsimonious_flux_balance_analysis`](@ref) internally.
 """
 function parsimonious_flux_balance_analysis_dict(model::MetabolicModel, args...; kwargs...)
     opt_fluxes = parsimonious_flux_balance_analysis_vec(model, args...; kwargs...)