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 only the model observables, such as scaling factors, offsets, and noise parameters. Further, they can be spline parameters, which are used to approximate non-linear measurement mappings of semi-quantitative data. Finally, they can be optimal scaling parameters, which are used for the integration of ordinal data.

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, in the relative data case, the inner problem can 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.

class pypesto.hierarchical.InnerCalculatorCollector

Bases: AmiciCalculator

Class to collect inner calculators in case of non-quantitative data types.

Upon import of a petab problem, the PEtab importer checks whether there are non-quantitative data types. If so, it creates an instance of this class instead of an AmiciCalculator. This class then collects the inner calculators for each data type and merges their results with the quantitative results.

Parameters:

• data_types (set[str]) – List of non-quantitative data types in the problem.

• petab_problem (Problem) – The PEtab problem.

• model (Union[Model, ModelPtr]) – The AMICI model.

• edatas (list[ExpData]) – The experimental data.

• inner_options (dict) – Options for the inner problems and solvers.

__call__(x_dct, sensi_orders, mode, amici_model, amici_solver, edatas, n_threads, x_ids, parameter_mapping, fim_for_hess)

Perform the actual AMICI call.

Called within the AmiciObjective.__call__() method. Calls all the inner calculators and combines the results.

Parameters:

• x_dct (dict) – Parameters for which to compute function value and derivatives.

• sensi_orders (tuple[int]) – Tuple of requested sensitivity orders.

• mode (Literal['mode_fun', 'mode_res']) – Call mode (function value or residual based).

• amici_model (Union[Model, ModelPtr]) – The AMICI model.

• amici_solver (Union[Solver, SolverPtr]) – The AMICI solver.

• edatas (list[ExpData]) – The experimental data.

• n_threads (int) – Number of threads for AMICI call.

• x_ids (Sequence[str]) – Ids of optimization parameters.

• parameter_mapping (ParameterMapping) – Mapping of optimization to simulation parameters.

• fim_for_hess (bool) – Whether to use the FIM (if available) instead of the Hessian (if requested).

__init__(data_types, petab_problem, model, edatas, inner_options)

Parameters:

• data_types (set[str]) –

• petab_problem (Problem) –

• model (Model | ModelPtr) –

• edatas (list[ExpData]) –

• inner_options (dict) –

construct_inner_calculators(petab_problem, model, edatas, inner_options)

Construct inner calculators for each data type.

Parameters:

• petab_problem (Problem) –

• model (Model | ModelPtr) –

• edatas (list[ExpData]) –

• inner_options (dict) –

get_inner_par_ids()

Return the ids of inner parameters of all inner problems.

Return type:

list[str]

get_interpretable_inner_par_bounds()

Return the bounds of interpretable inner parameters of all inner problems.

Return type:

tuple[ndarray, ndarray]

get_interpretable_inner_par_ids()

Return the ids of interpretable inner parameters of all inner problems.

See InnerProblem.get_interpretable_x_ids().

Return type:

list[str]

initialize()

Initialize.

validate_options(inner_options)

Validate the inner options.

Parameters:

inner_options (dict) – Options for the inner problems and solvers.

class pypesto.hierarchical.InnerParameter

Bases: object

An inner parameter of a hierarchical optimization problem.

coupled

If the inner parameter is part of an observable that has both an offset and scaling inner parameter, this attribute points to the other inner parameter. Otherwise, it is None.

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, inner_parameter_type, scale='lin', lb=-inf, ub=inf, ixs=None, dummy_value=None)

Construct.

Parameters:

• attributes. (See class) –

• inner_parameter_id (str) –

• inner_parameter_type (InnerParameterType) –

• scale (Literal['lin', 'log', 'log10']) –

• lb (float) –

• ub (float) –

• ixs (Any) –

• dummy_value (float) –

check_bounds()

Check bounds.

get_bounds()

Get the bounds.

Return type:

dict

get_unsatisfied_bound(value)

Get the unsatisfied bound index, if any.

Return type:

Optional[str]

is_within_bounds(value)

Check whether a value is within the bounds.

class pypesto.hierarchical.InnerProblem

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, data)

Parameters:

• xs (list[InnerParameter]) –

• data (list[ndarray]) –

static from_petab_amici(petab_problem, amici_model, edatas)

Create an InnerProblem from a PEtab problem and AMICI objects.

Return type:

InnerProblem

Parameters:

• petab_problem (Problem) –

• amici_model (Model) –

• edatas (list[ExpData]) –

get_bounds()

Get bounds of inner parameters.

Return type:

tuple[ndarray, ndarray]

get_dummy_values(scaled)

Get dummy parameter values.

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

Parameters:

scaled (bool) – Whether the parameters should be returned on parameter scale (True) or on linear scale (False).

Return type:

dict[str, float]

get_for_id(inner_parameter_id)

Get InnerParameter for the given parameter ID.

Return type:

InnerParameter

Parameters:

inner_parameter_id (str) –

get_interpretable_x_bounds()

Get bounds of interpretable inner parameters.

Return type:

tuple[ndarray, ndarray]

get_interpretable_x_ids()

Get IDs of interpretable inner parameters.

Interpretable parameters need to be easily interpretable by the user. Examples are scaling factors, offsets, or noise parameters. An example of non-interpretable inner parameters is the spline heights of spline approximation for semiquantitative data. It is challenging to interpret the meaning of these parameters based solely on their value.

Return type:

list[str]

get_x_ids()

Get IDs of inner parameters.

Return type:

list[str]

get_xs_for_type(inner_parameter_type)

Get inner parameters of the given type.

Return type:

list[InnerParameter]

Parameters:

inner_parameter_type (str) –

is_empty()

Check for emptiness.

Return type:

bool

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, sim, sigma, scaled)

Solve the subproblem.

Parameters:

• problem (InnerProblem) – The inner problem to solve.

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

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

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

Return type:

Union[dict[str, float], list]

Returns:

• A dictionary of inner parameter ids and their optimal values for the

• relative inner problem, or a list of inner optimization results

• for the semiquantitative and ordinal inner problems.