Simulate

A fundamental task performed in our tool set is simulating the model (whether it is imported from an SBtab document or not). Typically, the solution to an initial value problem depends on the choices of initial states, parameter values and inputs (also parameters). But only the parameters will vary often, during ABC or MCMC in general as that is a parameter estimation task. For this reason we provide two closure generating functions:

• simulate <- simulator.c(experiments, modelName, parMap = identity)
• simulate <- simulator.R(experiments, model, parMap = identity)

Both return a function with the interface: simulate(k), where k is a parameter matrix of intrinsic parameters (each column is one parameter vector, without inputs). The experiments to simulate (with their inputs), the model to use and how to transform the parameter vectors before passing them to the model are all implicit in simulate. The function parMap can be used to sample k in logarithmic space. So, k can be some logarithmic vector and parMap = exp will transform them to linear space. But it can also re-order or reshape them in some way (or change type to something the model expects).

modelName <- checkModel("muModel","myModel_gvf.c") # will compile if necessary
simulate <- simulator.c(experiments, modelName, parMap = exp)
par<-matrix(c(1,2,3),3,5)
yf<-simulate(par)

will return a list yf of the same length as experiments, with solutions at the outputTimes indicated in the experiments, for state variables and output functions:

yf[[l]]$func[i,j,k]

This is the value of the output function i for experiment l, at outputTimes[j], for parameter set par[,k].

R-functions

runModel

Simulate an Experiment using an ODE Model, without using the closures from the previous sections.

runModel(experiments, modelName,  parABC, parMap=identity)

This function uses the GSL solvers, or the R solver deSolve [default] to simulate the ODE model with the initial states and input characteristic of the experiments provided in input.

If the model name has a comment that indicates a model file ending in .so, then this function will use the shared library and the GSL solvers.

Input arguments

• experiments (list) - experiments to simulate. Each experiment variable is an element of the variable experiments that is imported via function import_experiments
• modelName(character) - used to find model files and functions within the file (a prefix), and optionally a comment indicating a file
• parABC (numeric) - a matrix of column vectors; each column contains a vector of both normal parameters (e.g. kinetic parameters like kf and kr) and input_parameters (concatenated in that order, i.e. first parameters, then inputs). If the number of columns is N, N simulations will be performed.
• parMap (function) - re-mapping function to apply to parameters (e.g. to switch from a linear to a logarithmic scale)

Output (list)

List out whose elements correspond to a simulation for each experiment provided in the input argument experiments. Each element is in turn a list, with elements: - state (numeric) - value of the approximated solution of the ODE system at each time point as the experimental measurements - func (numeric) - value of the output at each time point as the experimental measurements

checkModel

Assign a simulation file for a given model, and compile the model if necessary, check for existence:

model.sbtab <- SBtabVFGEN::sbtab_from_tsv(model.tsv)
modelName <- checkModel(comment(model.sbtab),modelFile=NULL)

An SBtab document contains a model name, SBtabVFGEN::sbtab_from_tsv includes this information as a comment to the return value.

checkModel returns this model name as supplied in the first slot, with some additional comments about the file. The user can of course pick a different model name at this point. Or circumvent this function.

As an alternative to this function, it is sufficient to write

modelName <- "test_ode_model"             # or some other model name
comment(modelName) <- "test_ode_model.so" # e.g.: manually compiled

This function will not attempt to find a model file, other than in the current directory. But, checkModel will compile a GSL compatible C source file into a shared object if modelFile ends with .c and stop if that doesn’t work.

In any case, this function stops execution if the model file doesn’t exist.

Input arguments * modelName (character) * modelFile (character) - a string, if the model file is different from “modelName.R”. If the file name ends in .c, the c source will be compiled to a shared library.

Output (character) The returned value is “modelName” with an additional comment about which file to use for simulations.

makeObjective

Creates Objective functions from ingredients (as closures)

obj <- makeObjective(experiments,modelName,distance,parMap=identity)

This function creates a function obj (closure), that is used in the ABCMCMC parameter estimation. The created function accepts only one argument in input: a vectorial parameter or a matrix of parameters, with each column corresponding to a parameter vector.

The function obj(par) will: 1. apply the transformation parMap to each column of par: 1. for each experiment, append the input parameters (experiments[[i]]$input) 2. simulate all experiments, with inputs, events, and initial values from experiments 3. calculate the model’s output functions 4. use the distance measure function to obtain the distance between simulation and experimental data (experiments[[i]]$outputValues) 2. save all distances as a matrix: distance[i,j] is the distance between the data and model functions in experiment i and parameter set j

Input arguements * experiments (list) - simulation experiments * modelName (character) - model name as a string, and model storage file as comment to this variable * distance (function) - function that calculates ABC scores, i.e. distance between experimental and simulated data * parMap (function) - a function that transforms ABC variables into acceptable model parameters (e.g. allowing to switch from linear to logarithmic scale)

Output (function) The output is a function that accepts one parameter matrix par and calculates the distance between experimental data and data simulated from the model using par.