# API Documentation

## High Level

`PumasQSP.QSPCost`

— Type`QSPCost(model, trials; search_space)`

The `QSPCost`

stores the information needed to setup a virtual population simulation. The `model`

is an MTK `ODESystem`

describing the particular case of interest. The `trials`

are a trial collection that groups the individual trials according to their interpretation, such as `IndependentTrials`

(there is no link between trials) or `SteadyStateTrials`

(the first trial computes a steady state that other trials may continue to solve from). The `search_space`

defines the parameters (or initial conditions) to be optimized during the virtual population simulation and their bounds.

The resulting object is callable, taking as a single argument the states of the `OptimizationProblem`

that describes one virtual patient of the simulation.

`PumasQSP.solve_trial`

— Function`solve_trial(trial, x, cost)`

Solve the given `trial`

corresponding to the `cost`

object with the optimization state given by `x`

.

`PumasQSP.VpopResult`

— Type`VpopResult`

The structure that contains virtual population results. You can export these results to a `DataFrame`

with `DataFrame(vp)`

, or you can plot them using `plot(vp, trial)`

, where `vp`

is your `VpopResult`

and `trial`

is the `AbstractTrial`

that you want to use for the default parameter (or initial condition) values.

`PumasQSP.vpop_ensemble`

— Function`vpop_ensemble(vp, trial; ss_trial=nothing)`

Create an `EnsembleProblem`

descrbing the patients in the virtual population `vp`

and using `trial`

for the parameter and initial condition values. If the trial depends on a steady state trial, it can be specified with `ss_trial`

.

Missing docstring for `vpop`

. Check Documenter's build log for details.

## Trial Types

`PumasQSP.Trial`

— Type`Trial(data, model; kwargs...)`

The `Trial`

describes one instance in which `data`

was obtained for the specified `model`

. The trial will then be used to compute the cost function of the optimization problem that corresponds to a virtual population simulation or to a global sensitivity analysis (GSA). In the case of GSA, the `data`

is not needed, so it can be assigned to `nothing`

.

A trial describes what happens with the model in a certain situation that corresponds to parameter (or initial condition) values that differ from the defaults of the model. In order to specify the modifications, you can use the `u0`

keyword argument for initial conditions (e.g. u0 = [state*name => custom*initial*value]) and params for the parameters (e.g. params = [p1 => specific*value, p2 => other_value]).

A required keyword of the `Trial`

constructor is `tspan`

, which indicates the timespan for which we solve the model equations.

In order to specify what states are saved in the data, the `save_names`

keyword argument can be used.

The cost contribution for the trial is computed using the L2 loss function by default, but this can be changed by using the `err`

keyword argument (e.g. err = (sol, data) -> compute_error). The function will be passed 2 arguments, the solution of the trial and the data and is expected to return a scalar value that will represent the cost contribution of the respective trial.

In the case of GSA, a `reduction`

function will be used instead, and that will correspond to what we are computing the sensitivity against.

If the trial is part of a collection of `SteadyStateTrials`

, then `forward_u0=true`

should be passed for the trial to continue solving from the steady state.

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.

`PumasQSP.IndependentTrials`

— Type`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])

`PumasQSP.SteadyStateTrials`

— Type`SteadyStateTrials(ss_trial, trials...; postprocess=last)`

`SteadyStateTrials`

are a trial collection that describes a steady state trial (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.

## Virtual Population Methods

`PumasQSP.StochGlobalOpt`

— Type`StochGlobalOpt(; maxiters, parallel_type=EnsembleSerial(), solver=BBO_adaptive_de_rand_1_bin_radiuslimited())`

A stochastic global optimization method for computing virtual populations. The keyword `maxiters`

is required and represents the maximum number of iterations taken by the global optimization method (chosen via the `solver`

keyword).

The keyword `parallel_type`

can be used to pass a parallelization method. The ensemble types from SciML are supported.