Simulation of Pumas Models

The simobs Function

Simulation of a PumasModel are performed via the simobs function. The function is given by the values:

simobs(m, data, param, [randeffs]; kwargs...)

The terms in the function call are:

• m: the PumasModel, either defined via the @model DSL or the function-based interface.
• data: either a Subject or a Population.
• param: a NamedTuple of parameters which conform to the ParamSet of the model.
• randeffs: an optional argument for the random effects for the simulation. If the random effects are not given, they are sampled as described in the model.
• kwargs: extra keyword arguments.

Additionally, the following keyword arguments can be used:

• alg: the type for which differential equation solver method to use. For example, alg=Rodas5() specifies the usage of the 5th order Rosenbrock method for ODEs described in the DifferentialEquations.jl solver documentation page. Defaults to an automatic stiffness detection algorithm for ODEs.
• ensemblealg: the parallel algorithm to use internally for simulating a Population. The options are derived from DifferentialEquations.jl. The default is EnsembleThreads().
• Any keyword argument in the DifferentialEquations.jl common solver arguments. These are documented on the DifferentialEquations.jl common solver options page.

The result of simobs function is a SimulatedObservation if the data was Subject and a SimulatedPopulation if the data was a Population.

Handling Simulated Returns

When running

sim = simobs(m, data, param)

sim is a SimulatedObservation which can be accessed via its fields. These fields are:

• subject: the Subject used to generate the observation
• time: the times associated with the observations
• observations: the resulting observations of the simulation

If the @model DSL is used, then observed is a NamedTuple where the names give the associated values. From the function-based interface, observed is the chosen return type of the observed function in the model specification.

A SimulatedPopulation is a collection of SimulatedObservations, and when indexed like sim[i] it returns the SimulatedObservation of the ith simulation subject.

Visualizing Simulated Returns

These objects have automatic plotting and dataframe visualization. To plot a simulation return, simply call plot on the output using Plots.jl. For example, the following will run a simulation and plot the observed variables:

obs = simobs(m, data, param)
using Plots
plot(obs)

By default this generates a plot for each derived variable. To choose which variables to plot, the obsnames argument can be given which declares indices or derived variable names to plot. For example, plot(obs,obsnames=[:dv1,:dv2]) would only plot the values dv1 and dv2. In addition, all of the Plots.jl attributes can be used in this plot command. For more information on using Plots.jl, please see the Plots.jl tutorial. Note that if the simulated return is a SimulatedPopulation, then the plots overlay the results of the various subjects.

To generate the DataFrame associated with the observed outputs, simply call DataFrame on the simulated return. For example, the following builds the tabular output from the returned object:

obs = simobs(m, data, param)
df = DataFrame(obs)