Specialized analysis functions

optimized_values(
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint};
    settings,
    output,
    kwargs...
)

Make an JuMP model out of constraints using optimization_model (most arguments are forwarded there), then apply the settings, optimize the model, and return either nothing if the optimization failed, or output substituted with the solved values (output defaults to constraints.

For a "nice" version for simpler finding of metabolic model optima, use flux_balance_analysis.

parsimonious_optimized_values(
    constraints::Union{ConstraintTrees.Constraint, ConstraintTrees.Tree{ConstraintTrees.Constraint}};
    objective,
    objective_value,
    settings,
    parsimonious_objective,
    parsimonious_optimizer,
    parsimonious_sense,
    parsimonious_settings,
    tolerances,
    output,
    kwargs...
)

Optimize the system of constraints to get the optimal objective value. Then try to find a "parsimonious" solution with the same objective value, which optimizes the parsimonious_objective (possibly also switching optimization sense, optimizer, and adding more settings).

For efficiency, everything is performed on a single instance of JuMP model.

A simpler version suitable for direct work with metabolic models is available in parsimonious_flux_balance_analysis.

screen(f, args...; workers) -> Any

Execute a function with arguments given by args on workers.

This is merely a nice shortcut for Distributed.pmap running over a Distributed.CachingPool of the given workers.

screen_optimization_model(
    f,
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint},
    args...;
    objective,
    sense,
    optimizer,
    settings,
    workers
)

Execute a function arguments from arrays args on workers, with a pre-cached JuMP optimization model created from constraints, objective and optimizer using optimization_model. settings are applied to the optimization model before first execution of f.

Since the model is cached and never re-created, this may be faster than just plain screen in many use cases.

The function f is supposed to take length(args)+1 arguments, the first argument is the JuMP model, and the other arguments are taken from args as with Distributed.pmap. While the model may be modified in place, one should take care to avoid modifications that change results of subsequent invocations of f, as that almost always results in data races and irreproducible executions. Ideally, all modifications of the model should be either manually reverted in the invocation of f, or the future invocations of f must be able to overwrite them.

f may use optimized_model to extract results easily w.r.t. some given ConstraintTree.

constraints_variability(
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint},
    targets::ConstraintTrees.Tree{ConstraintTrees.Constraint};
    kwargs...
)

Simplified variant of constraints_variability that computes the variability of all values in tree targets, and returns a new tree of the same shape as targets that contains tuples for minima and maxima.

All other arguments are forwarded to the matrix-returning overload of constraints_variability.

constraints_variability(
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint},
    targets::Vector{<:ConstraintTrees.Value};
    output,
    output_type,
    kwargs...
)

In a feasible space specified by constraints, compute the feasible range of individual targets values. The output is a matrix with one column for minima and second column for maxima of the individual target's values.

This is used e.g. to compute the flux_variability_analysis, and can be viewed as a more generalized version thereof.

output and output_type can be used to customize the information reported from the solved models.

Extra arguments are passed to screen_optimization_model.

constraints_objective_envelope(
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint},
    dims...;
    objective,
    sense,
    optimizer,
    settings,
    workers
)

Optimize the system given by constraints and objective with optimizer (with custom settings) for all combination of constriants given by dims.

dims should be compatible with pairs that assign a sequence of breaks to a ConstraintTrees.Value: For example, organism.fluxes.PFK => 1:3 will compute optima of the model with the flux through PFK constrained to be equal to 1, 2 and 3.

In turn, all dims are converted to groups of equality constraints, and the model is solved for all combinations. Shape of the output matrix corresponds to Iterators.product(last.(dims)...).

Operation is parallelized by distribution over workers; by default all Distributed.workers() are used.

sample_chain_achr(
    sample_c::AbstractArray{F<:Real, 2};
    variable_lower_bounds,
    variable_upper_bounds,
    coupling,
    lower_bounds,
    upper_bounds,
    epsilon,
    collect_iterations,
    generator
)

Implementation of a single chain run for the Artificially-Centered Hit and Run algorithm (ACHR).

To use this on a model, use flux_sample or sample_constraints; most parameters are filled in correctly by these functions.

epsilon is defaulted from configuration.

sample_constraint_variables(
    sampler::Function,
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint};
    start_variables,
    seed,
    workers,
    n_chains,
    kwargs...
)

Sample the feasible space constrained by constraints by sampling algorithm sampler, using the start_variables as a "warm-up" for the sampling runs. Random values are derived from the seed. Computation of individual n_chains chains by sampler is parallelized over workers using screen. Extra arguments are passed to sampler.

This function returns a matrix of the samples (one sample per row). To nicely aggregate the statistics in the constraint tree, use sample_constraints.

sample_constraints(
    sampler::Function,
    constraints::ConstraintTrees.Tree{ConstraintTrees.Constraint};
    output,
    aggregate,
    aggregate_type,
    kwargs...
)

A front-end for sample_constraint_variables that saves the sampling results in a constraint tree of the same shape as output. Additionally, aggregate function and aggregate_type can be specified to customize the output.

All other parameters are forwarded to sample_constraint_variables.

frontend_optimized_values(
    builder,
    args...;
    builder_kwargs,
    objective,
    output,
    sense,
    optimizer,
    settings,
    kwargs...
)

A helper that converts a front-end constraint builder function (the output of which would normally be just passed through optimized_values) to front-end analysis function.

frontend_parsimonious_optimized_values(
    builder,
    args...;
    builder_kwargs,
    objective,
    objective_value,
    output,
    sense,
    optimizer,
    settings,
    parsimonious_objective,
    parsimonious_optimizer,
    parsimonious_sense,
    parsimonious_settings,
    tolerances,
    kwargs...
)

A helper that converts a parsimonious-style front-end constraint builder function to front-end analysis function.

Like frontend_optimized_values, but internally calls parsimonious_optimized_values.