pypesto.hierarchical

Hierarchical

Contains an implementation of the hierarchical optimization approach, which decomposes the parameter estimation problem into an outer and an inner problem. In the outer problem, only dynamic parameters are optimized. In the inner problem, conditional on the outer solution, static parameters are optimized. Static parameters can be parameters affecting directly the model observables, such as scaling factors, offsets, and noise parameters.

Hierarchical optimization has the advantage that the outer problem is typically less complex than the full problem, and thus can be solved more efficiently. Further, the inner problem can often be solved analytically, which is more efficient. Thus, hierarchical optimization can be used to speed up parameter estimation, finding optimal values more efficiently and reliably.

The implementation in this package is based on:

• Loos et al. 2018 (https://doi.org/10.1093/bioinformatics/bty514), who give an analytic solution for the inner problem for scaling factors and noise standard deviations, for Gaussian and Laplace noise, using forward sensitivity analysis (FSA).

• Schmiester et al. 2020 (https://doi.org/10.1093/bioinformatics/btz581), who give an analytic solution for the inner problem for scaling factors, offsets and noise standard deviations, for Gaussian and Laplace noise, using adjoint sensitivity analysis (ASA). ASA allows to calculate gradients substantially more efficiently in high dimension.

class pypesto.hierarchical.AnalyticalInnerSolver

Bases: InnerSolver

Solve the inner subproblem analytically.

Currently, supports offset and scaling parameters (coupled or not), and sigmas for additive Gaussian noise.

solve(problem: InnerProblem, sim: List[ndarray], sigma: List[ndarray], scaled: bool) → Dict[str, float]

Solve the subproblem analytically.

Parameters:

• problem – The inner problem to solve.

• sim – List of model output matrices, as provided in AMICI’s ReturnData.y. Same order as simulations in the PEtab problem.

• sigma – List of sigma matrices from the model, as provided in AMICI’s ReturnData.sigmay. Same order as simulations in the PEtab problem.

• scaled – Whether to scale the results to the parameter scale specified in problem.

class pypesto.hierarchical.HierarchicalAmiciCalculator(inner_problem: AmiciInnerProblem, inner_solver: InnerSolver | None = None)

Bases: AmiciCalculator

A calculator that is passed as calculator to the pypesto.AmiciObjective.

__call__(x_dct: Dict, sensi_orders: Tuple[int], mode: Literal['mode_fun', 'mode_res'], amici_model: Model | ModelPtr, amici_solver: Solver | SolverPtr, edatas: List[ExpData], n_threads: int, x_ids: Sequence[str], parameter_mapping: ParameterMapping, fim_for_hess: bool)

Perform the actual AMICI call, with hierarchical optimization.

See documentation for pypesto.objective.amici.amici_calculator.AmiciCalculator.__call__().

The return object also includes the simulation results that were generated to solve the inner problem, as well as the parameters that solver the inner problem.

__init__(inner_problem: AmiciInnerProblem, inner_solver: InnerSolver | None = None)

Initialize the calculator from the given problem.

Parameters:

• inner_problem – The inner problem of a hierarchical optimization problem.

• inner_solver – A solver to solve inner_problem. Defaults to pypesto.hierarchical.solver.AnalyticalInnerSolver.

get_inner_parameter_ids() → List[str]

Get the ids of the inner parameters.

initialize()

Initialize.

class pypesto.hierarchical.InnerParameter(inner_parameter_id: str, inner_parameter_type: InnerParameterType, scale: Literal['lin', 'log', 'log10'] = 'lin', lb: float = -inf, ub: float = inf, ixs: Any | None = None, dummy_value: float | None = None)

Bases: object

An inner parameter of a hierarchical optimization problem.

coupled

Whether the inner parameter is part of an observable that has both an offset and scaling inner parameter.

dummy_value

Value to be used when the optimal parameter is not yet known (in particular to simulate unscaled observables).

inner_parameter_id

The inner parameter ID.

inner_parameter_type

The inner parameter type.

ixs

A mask (boolean matrix) that indicates the measurements that this parameter is used in.

lb

The lower bound, for optimization.

scale

Scale on which to estimate this parameter.

ub

The upper bound, for optimization.

__init__(inner_parameter_id: str, inner_parameter_type: InnerParameterType, scale: Literal['lin', 'log', 'log10'] = 'lin', lb: float = -inf, ub: float = inf, ixs: Any | None = None, dummy_value: float | None = None)

Construct.

Parameters:

attributes. (See class) –

check_bounds()

Check bounds.

class pypesto.hierarchical.InnerProblem(xs: List[InnerParameter], data: List[ndarray])

Bases: object

Inner optimization problem in hierarchical optimization.

xs

Mapping of (inner) parameter ID to InnerParameters.

data

Measurement data. One matrix (num_timepoints x num_observables) per simulation condition. Missing observations as NaN.

__init__(xs: List[InnerParameter], data: List[ndarray])

static from_petab_amici(petab_problem: Problem, amici_model: Model, edatas: List[ExpData]) → InnerProblem

Create an InnerProblem from a PEtab problem and AMICI objects.

get_dummy_values(scaled: bool) → Dict[str, float]

Get dummy parameter values.

Get parameter values to be used for simulation before their optimal values are computed.

Parameters:

scaled – Whether the parameters should be returned on parameter or linear scale.

get_for_id(inner_parameter_id: str) → InnerParameter

Get InnerParameter for the given parameter ID.

get_x_ids() → List[str]

Get IDs of inner parameters.

get_xs_for_type(inner_parameter_type: str) → List[InnerParameter]

Get inner parameters of the given type.

is_empty() → bool

Check for emptiness.

Returns:

• True if there aren’t any parameters associated with this problem,

• False otherwise.

class pypesto.hierarchical.InnerSolver

Bases: object

Solver for an inner optimization problem.

initialize()

(Re-)initialize the solver.

Default: Do nothing.

solve(problem: InnerProblem, sim: List[ndarray], sigma: List[ndarray], scaled: bool) → Dict[str, float]

Solve the subproblem.

Parameters:

• problem – The inner problem to solve.

• sim – List of model output matrices, as provided in AMICI’s ReturnData.y. Same order as simulations in the PEtab problem.

• sigma – List of sigma matrices from the model, as provided in AMICI’s ReturnData.sigmay. Same order as simulations in the PEtab problem.

• scaled – Whether to scale the results to the parameter scale specified in problem.

class pypesto.hierarchical.NumericalInnerSolver(minimize_kwargs: Dict[str, Any] | None = None, n_cached: int = 1, problem_kwargs: Dict[str, Any] | None = None)

Bases: InnerSolver

Solve the inner subproblem numerically.

Advantage: The structure of the subproblem does not matter like, at all. Disadvantage: Slower.

Special features: We cache the best parameters, which substantially speeds things up.

minimize_kwargs

Passed to the pypesto.optimize.minimize call.

n_cached

Number of optimized parameter vectors to save.

problem_kwargs

Passed to the pypesto.Problem constructor.

x_guesses

Cached optimized parameter vectors, supplied as guesses to the next solve call.

__init__(minimize_kwargs: Dict[str, Any] | None = None, n_cached: int = 1, problem_kwargs: Dict[str, Any] | None = None)

initialize()

(Re-)initialize the solver.

solve(problem: InnerProblem, sim: List[ndarray], sigma: List[ndarray], scaled: bool) → Dict[str, float]

Solve the subproblem numerically.

Parameters:

• problem – The inner problem to solve.

• sim – List of model output matrices, as provided in AMICI’s ReturnData.y. Same order as simulations in the PEtab problem.

• sigma – List of sigma matrices from the model, as provided in AMICI’s ReturnData.sigmay. Same order as simulations in the PEtab problem.

• scale – Whether to scale the results to the parameter scale specified in problem.