Trials

Trial(data, model; kwargs...)

The Trial describes an experiment in which data was obtained. The dynamics of the investigated system are represented in model as an ODESystem. The trial is used within the optimization problem, as part of InverseProblem to fit the unknown model parameters and initial conditions to data. In the case of Global Sensitivity Analysis (GSA), the data is not needed and can be assigned to nothing.

Required Keyword Arguments

• tspan, which indicates the timespan for which the model equations are solved.

Optional Keywords Arguments

• u0 modifies the default values of the initial conditions of some or all of the states, e.g. u0 = [state_name => custom_initial_value]
• params modifies the default values of some or all the parameters, e.g. params = [p1 => specific_value, p2 => other_value]
• err specifies the trial's contribution to the cost function. Defaults to the l2loss function. The function requires 2 arguments, the solution of the trial and the data and is expected to return a scalar value corresponding to the cost of the trial, i.e. err = (sol, data) -> compute_error.
• likelihood is used for MCMCOpt methods. This likelihood describes the distribution that generated the data. By default, a multivariate Normal distribution is used, centered at the solution of the trial at each saved timepoint u with a standard deviation s around it, but different distributions can be used, e.g., likelihood = (u, s) -> MvNormal(u, s).
• noise_priors is used for MCMCOpt methods. Describes the prior for s. The s parameter represents any observation noise around the solution of the trial at each timepoint, u. The default value for this prior distribution is an InverseGamma(2,3), but this can be changed, e.g. noise_prior = [s1 => Exponential(1), s2 => Gamma(3,2)]). If only one prior is given, then it is assumed that it applies to all saved states (save_names). Otherwise, a vector containing pairs of states and prior distributions with length equal to saved_names needs to be provided, to set different priors for each state. In the example above, the model had two states s1 and s2 so two pairs were provided. The noise parameters s are assumed to be unique for each trial and to be constant across timepoints for each state of each trial.
• reduction is used for GSA methods. The output of reduction is expected to be the quantity whose sensitivity is being investigated.
• doses specifies the doses that occur in a trial. This argument can be equal to an instance of Bolus, PeriodicBolus, Infusion, PeriodicInfusion or a Vector of multiple instances of any of these dose types.
• save_names is used to specify which model states are saved. The same states are extracted from data.
• trial_name, an identifying name. The default name is "Trial".
• forward_u0=true, if the trial is part of a collection of SteadyStateTrials, then forward_u0=true signals that the trial should use the outcome of the SteadyStateTrial of the same collection as its initial condition.

If additional keywords are passed, they will be forwarded to the solve call. For example, one can pass alg=Tsit5() to specify what solver will be used. More information about supported arguments can be found here.

SteadyStateTrial(data, model; kwargs...)

Describes a trial that is ran until a steady state is reached. This object can be initialized in the same way as a Trial object, with the only difference being that data needs to be a Vector here. The data in this case represents the values of the saved states when the system has reached its steady state.

See the SciML documentation for background information on steady state problems.

IndependentTrials(trials...)

This trial collection type indicates that each trial can be solved individualy and that there is no interaction between them. This trial type is automatically created it the trials are passed as a Vector (i.e. [trial1, trial2])

SteadyStateTrials(ss_trial, trials...; postprocess=last)

SteadyStateTrials are a trial collection that describes a steady state trial (see SteadyStateTrial) (specified as the first argument) followed by subsequent trials that can continue using the steady state by setting forward_u0=true. The steady state solution that is passed on can be modified using the postprocess keyword argument, which accepts a function with a single argument that represents the solution of the first trial and returns the state to be further passed on.

simulate(experiment::AbstractExperiment, prob::InverseProblem, x)

Simulate the given experiment using optimization-state point x, which contains values for each parameter and initial condition that is optimized in InverseProblemprob.

l2loss(sol, data)

Squared error loss :

$\sum_{i=1}^{M} \sum_{j=1}^{N} \left( \text{sol}_{i,j} - \text{data}_{i,j} \right)^2$

where N is the number of saved timepoints and M the number of measured states in the solution

ARMLoss(sol, bounds)

Allen-Rieger-Musante (ARM) loss :

$\sum_{i=1}^{M} \sum_{j=1}^{N} \text{max} \left[ \left( \text{sol}_{i,j} - \frac{\text{u}_{i,j} + \text{l}_{i,j}}{2} \right)^2 - \left( \frac{\text{u}_{i,j} - \text{l}_{i,j}}{2} \right)^2, 0 \right]$

where N is the number of saved timepoints, M the number of measured states in the solution and l, u are the lower and upper bounds of each measured state respectively.

Reference

Allen RJ, Rieger TR, Musante CJ. Efficient Generation and Selection of Virtual Populations in Quantitative Systems Pharmacology Models. CPT Pharmacometrics Syst Pharmacol. 2016 Mar;5(3):140-6. doi: 10.1002/psp4.12063. Epub 2016 Mar 17. PMID: 27069777; PMCID: PMC4809626.