| Title: | Optimization Toolkit for Pharmacokinetic-Pharmacodynamic Models |
|---|---|
| Description: | A port of the Scarabee toolkit originally written as a Matlab-based application. scaRabee provides a framework for simulation and optimization of pharmacokinetic-pharmacodynamic models at the individual and population level. It is built on top of the neldermead package, which provides the direct search algorithm proposed by Nelder and Mead for model optimization. |
| Authors: | Sebastien Bihorel [aut, cre] |
| Maintainer: | Sebastien Bihorel <[email protected]> |
| License: | GPL-3 |
| Version: | 1.1-4 |
| Built: | 2024-12-17 06:52:09 UTC |
| Source: | CRAN |
Framework for Pharmacokinetic-Pharmacodynamic Model Simulation and Optimization
| Package: | scaRabee |
| Type: | Package |
| Version: | 1.1-4 |
| Date: | 2022-02-04 |
| License: | GPL-v3 |
| LazyLoad: | yes |
scaRabee is a toolkit for modeling and simulation primarily intended for the field of pharmacometrics. This package is a R port of Scarabee, a Matlab-based piece of software developed as a fairly simple application for the simulation and optimization of pharmacokinetic and/or pharmacodynamic models specified with explicit solutions, ordinary or delay differential equations.
The method of optimization used in scaRabee is based upon the Nelder-Mead simplex
algorithm, as implemented by the fminsearch function from the
neldermead package.
Please, refer to the vignette to learn how to run analyses with scaRabee and read more about the methods used in scaRabee.
scaRabee is available on the Comprehensive R Archive Network and also at: https://github.com/sbihorel/scaRabee
Sebastien Bihorel ([email protected])
bound.parameters is a utility function called during estimation runs.
It forces the parameter estimates to remain within the boundaries defined in
the .csv file of initial estimates. bound.parameters is typically not
called directly by users.
bound.parameters(x = NULL, lb = NULL, ub = NULL)bound.parameters(x = NULL, lb = NULL, ub = NULL)
x |
A vector of p parameter estimates. |
lb |
A vector of p lower boundaries. |
ub |
A vector of p upper boundaries. |
Returns a vector of p values. The ith element of the returned vector is:
x[i] if lb[i] < x[i] < ub[i]
lb[i] if x[i] <= lb[i]
ub[i] if ub[i] <= x[i]
Sebastien Bihorel ([email protected])
bound.parameters(seq(1:5), lb=rep(3,5), ub=rep(4,5)) # The following call should return an error message bound.parameters(1, lb=rep(3,5), ub=rep(4,5))bound.parameters(seq(1:5), lb=rep(3,5), ub=rep(4,5)) # The following call should return an error message bound.parameters(1, lb=rep(3,5), ub=rep(4,5))
compute.secondary is a secondary function called during estimations
runs. It evaluates the code provided in the $SECONDARY block of the model
file; all parameters defined in this block are considered as secondary
parameters at the initial and the final estimates of the model parameters.
compute.secondary is typically not called directly by users.
compute.secondary(subproblem = NULL, x = NULL)compute.secondary(subproblem = NULL, x = NULL)
subproblem |
A list containing the following levels:
|
x |
The vector of p final parameter estimates. |
Return a list of with the following elements:
The vector of s secondary parameter estimates derived from initial structural model parameter estimates.
The vector of s secondary parameter estimates derived from final structural model parameter estimates.
The vector of s secondary parameter names.
Sebastien Bihorel ([email protected])
scarabee.analysis,
weighting,
fitmle,
get.secondary
convert.infusion is a secondary function, which main purpose is to
transform infusion information provided using NONMEM standards into an object
that can be used by scaRabee model functions. convert.infusion is
typically not called directly by users.
convert.infusion(infusion.data = NULL)convert.infusion(infusion.data = NULL)
infusion.data |
A data.frame with the following variables: trt, time, cmt, amt, and rate. |
Return a data.frame with the following variables: trt, time, state, bolus, and infusion.
Sebastien Bihorel ([email protected])
dde.model is the system evaluation function called when a $DDE block is
detected in the model file, indicating that the model is defined by delay
differential equations. dde.model is typically not called directly by
users
dde.model(parms = NULL, derparms = NULL, code = NULL, bolus = NULL, infusion = NULL, xdata = NULL, covdata = NULL, issim = 0, check = FALSE, options = list(method='lsoda'))dde.model(parms = NULL, derparms = NULL, code = NULL, bolus = NULL, infusion = NULL, xdata = NULL, covdata = NULL, issim = 0, check = FALSE, options = list(method='lsoda'))
parms |
A vector of primary parameters. |
derparms |
A list of derived parameters, specified in the $DERIVED block of code. |
code |
A list of R code extracted from the model file. Depending on content of the model file, the levels of this list could be: template, derived, lags, ode, dde, output, variance, and/or secondary. |
bolus |
A data.frame providing the instantaneous inputs entering the system of delay differential equations for the treatment and individual being evaluated. |
infusion |
A data.frame providing the zero-order inputs entering the system of delay differential equations for the treatment and individual being evaluated. |
xdata |
A vector of times at which the system is being evaluated. |
covdata |
A data.frame of covariate data for the treatment and individual being evaluated. |
issim |
An indicator for simulation or estimation runs. |
check |
An indicator whether checks should be performed to validate function inputs. |
options |
A list of delay differential equation solver options. Currently not modifiable by users. |
dde.model evaluates the model for each treatment of each individual
contained in the dataset using, among other, the dedicated utility functions:
dde.syst, and dde.lags. The actual evaluation of the system is
performed by dede from the deSolve package.
dde.model also make use of utility functions which it shares with the
other system evaluation functions explicit.model, and ode.model,
such as create.intervals, derived.parms, init.cond,
input.scaling, make.dosing, init.update, and
de.output.
Returns a matrix of system predictions.
Sebastien Bihorel ([email protected])
dede,
dde.syst, dde.lags,
explicit.model, ode.model,
init.cond, input.scaling,
make.dosing, init.update,
de.output
This is a collection of utility functions called by dde.model when
a model defined by delay differential equations is evaluated. None of these
functions is typically called directly by users.
dde.syst(t = NULL, y = NULL, ic = NULL, parms = NULL, derparms = NULL, delags = NULL, codedde = NULL, dosing = NULL, has.dosing = NULL, dose.states = NULL, xdata = NULL, covdata = NULL, scale = NULL, check = FALSE) dde.lags(parms = NULL, derparms = NULL, codelags = NULL, check = FALSE)dde.syst(t = NULL, y = NULL, ic = NULL, parms = NULL, derparms = NULL, delags = NULL, codedde = NULL, dosing = NULL, has.dosing = NULL, dose.states = NULL, xdata = NULL, covdata = NULL, scale = NULL, check = FALSE) dde.lags(parms = NULL, derparms = NULL, codelags = NULL, check = FALSE)
t |
A scalar or a vector of numerical time values. |
y |
A vector of system state values. |
ic |
A vector of initial conditions, typically returned by
|
parms |
A vector of primary parameters. |
derparms |
A list of derived parameters, specified in the $DERIVED block of code. |
delags |
A vector of delay parameters, typically returned by
|
codedde |
The content of the R code specified within the $DDE block in the model file. |
dosing |
A data.frame of dosing information created by
|
has.dosing |
A logical variable, indicating whether any input has to be assigned to a system state. |
dose.states |
A vector of integers, indicating in which system state one or more doses have to be assigned to. |
xdata |
A vector of times at which the system is being evaluated. |
covdata |
A matrix of covariate data extracted from the dataset. |
scale |
A vector of system scale, typically returned by
|
check |
An indicator whether checks should be performed to validate function inputs |
codelags |
The content of the R code specified within the $LAGS block in the model file. |
dde.syst is the function which actually evaluates the system of delay
differential equations specified in the $DDE block.
dde.lags is the function which evaluates the code specified in the $LAG
block and defines the delays at which the system needs to be computed.
Sebastien Bihorel ([email protected])
estimation.plot is a secondary function called at the end of the
estimation runs. It generates plots from the iteration log file and the
prediction & residual file. Those plots are: a figure summarizing the changes
in the objective function and the estimated parameter values as a function of
the iteration plus, for each subject and sub-problem (i.e. treatment), a
figure overlaying model predictions and observed data, and another figure
showing 4 goodness-of-fit plots (predictions vs observations, weighted
residuals vs time, weighted residuals vs observations, weighted residuals vs
predictions). See vignette('scaRabee',package='scaRabee') for more
details. estimation.plot is typically not called directly by users.
estimation.plot(problem = NULL, Fit = NULL, files = NULL)estimation.plot(problem = NULL, Fit = NULL, files = NULL)
problem |
A list containing the following levels:
|
Fit |
A list containing the following elements:
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Sebastien Bihorel ([email protected])
Datasets for scaRabee demo.
data(example1.data) data(example1.initials) data(example2.data) data(example2.initials) data(example3.data) data(example3.initials) data(example4.data) data(example4.initials) data(example6.data) data(example6.initials) data(example8.data) data(example8.initials)data(example1.data) data(example1.initials) data(example2.data) data(example2.initials) data(example3.data) data(example3.initials) data(example4.data) data(example4.initials) data(example6.data) data(example6.initials) data(example8.data) data(example8.initials)
All example#.data are data.frame of observations and dosing events organized as typical scaRabee datasets.
All example#.initials are data.frame of parameter names and values organized as typical scaRabee parameter files.
These datasets are intended to be used in the scaRabee package demos.
data(example1.data) data(example1.initials)data(example1.data) data(example1.initials)
explicit.model is the system evaluation function called when neither
$ODE or $DDE blocks are detected in the model file, indicating that the model
is defined by explicit equations. explicit.model is typically not
called directly by users.
explicit.model(parms = NULL, derparms = NULL, code = NULL, bolus = NULL, infusion = NULL, xdata = NULL, covdata = NULL, issim = 0, check = FALSE)explicit.model(parms = NULL, derparms = NULL, code = NULL, bolus = NULL, infusion = NULL, xdata = NULL, covdata = NULL, issim = 0, check = FALSE)
parms |
A vector of primary parameters. |
derparms |
A list of derived parameters, specified in the $DERIVED block
of code. (NULL for |
code |
A list of R code extracted from the model file. Depending on content of the model file, the levels of this list could be: template, derived, lags, ode, dde, output, variance, and/or secondary. |
bolus |
A data.frame providing the instantaneous inputs entering the system of delay differential equations for the treatment and individual being evaluated. |
infusion |
A data.frame providing the zero-order inputs entering the system of delay differential equations for the treatment and individual being evaluated. |
xdata |
A vector of times at which the system is being evaluated. |
covdata |
A data.frame of covariate data for the treatment and individual being evaluated. |
issim |
An indicator for simulation or estimation runs. |
check |
An indicator whether checks should be performed to validate function inputs. |
explicit.model evaluates the model for each treatment of each
individual contained in the dataset, based upon the code specified in the
$OUTPUT block in the model file.
Returns a matrix of system predictions.
Sebastien Bihorel ([email protected])
finalize.grid.report is a secondary function called at the end of the
direct grid search step of the direct grid search runs (this step is actually
by a simulation step). It outputs to the report file the grid search summary
table produced by scarabee.gridsearch. finalize.grid.report is
typically not called directly by users.
finalize.grid.report(problem = NULL, fgrid = NULL, files = NULL)finalize.grid.report(problem = NULL, fgrid = NULL, files = NULL)
problem |
A list containing the following levels:
|
fgrid |
A data.frame with pe+2 columns. The last 2 columns report the value and the feasibility of the objective function at each specific vector of parameter estimates which is documented in the first pe columns. This data.frame must be ordered by feasibility and increasing value of the objective function. |
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Does not return any value.
Sebastien Bihorel ([email protected])
finalize.report is a secondary function called at the end of the
estimation runs. It outputs to the report file the final parameter estimates
for structural model parameters, residual variability and secondary parameters
as well as the related statistics (coefficients of variation, confidence
intervals, covariance and correlation matrix). finalize.report is
typically not called directly by users.
finalize.report(problem = NULL, Fit = NULL, files = NULL)finalize.report(problem = NULL, Fit = NULL, files = NULL)
problem |
A list containing the following levels:
|
Fit |
A list containing the following elements:
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Return a modified version of Fit, containing the following elements:
The vector of final parameter estimates.
The minimal value of the objective function.
The matrix of covariance for the parameter estimates.
A data.frame with the same structure as
problem$init but only containing the sorted estimated estimates.
The sorting is performed by order.param.list.
The upper triangle of the correlation matrix for the parameter estimates.
The coefficients of variations for the parameter estimates.
The confidence interval for the parameter estimates.
The Akaike Information Criterion.
A list of data related to the secondary parameters, containing the following elements:
A vector of secondary parameter estimates.
The matrix of covariance for the secondary parameter estimates.
The coefficients of variations for the secondary parameter estimates.
The confidence interval for the secondary parameter estimates.
A data.frame with the same structure as
problem$init but only containing the sorted fixed estimates.
The sorting is performed by order.param.list.
A data.frame with the same content as
problem$init but sorted by order.param.list.
Sebastien Bihorel ([email protected])
fitmle is a secondary function called during estimation runs. It
performs the optimization of the model parameters by the method of the maximum
likelihood, i.e. the minimization of an objective function defined as the
exact negative log likelihood of the observed data, given the structural
model, the model of residual variability, and the parameter estimates. This
minimization is performed by the Nelder-Mead simplex algorithm implemented in
fminsearch from the neldermead package. fitmle is
typically not called directly by users.
fitmle(problem = NULL, estim.options = NULL, files = NULL)fitmle(problem = NULL, estim.options = NULL, files = NULL)
problem |
A list containing the following levels:
|
estim.options |
A list of estimation options containing two elements
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Return a list with two elements: estimations which contains the vector
of final parameter estimates and fval the minimal value of the
objective function.
Sebastien Bihorel ([email protected])
Pawel Wiczling
fitmle.cov is a secondary function called during estimation runs. It
performs multiple tasks after completion of the model optimization by
fitmle:
1- It computes the matrix of covariance (as described by D'Argenio and
Schumitzky) by calling get.cov.matrix and derives some related
statistics: correlation matrix, coefficient of variation of parameter
estimates, confidence intervals and Akaike Information criterion,
2- It estimates secondary parameters and computes the coefficient of variation of those estimates, as well as the confidence intervals.
fitmle.cov is typically not called directly by users.
fitmle.cov(problem = NULL, Fit = NULL)fitmle.cov(problem = NULL, Fit = NULL)
problem |
A list containing the following levels:
|
Fit |
A list of containing the following levels:
|
Return a list containing the following elements:
The vector of final parameter estimates.
The minimal value of the objective function.
The matrix of covariance for the parameter estimates.
A data.frame with the same structure as
problem$init but only containing the sorted estimated estimates.
The sorting is performed by order.param.list.
The upper triangle of the correlation matrix for the parameter estimates.
The coefficients of variations for the parameter estimates.
The confidence interval for the parameter estimates.
The Akaike Information Criterion.
A list of data related to the secondary parameters, containing the following elements:
The vector of secondary parameter estimates calculated using the initial estimates of the primary model parameters.
The vector of secondary parameter estimates calculated using the final estimates of the primary model parameters.
The vector of names of the secondary parameter estimates.
The matrix of partial derivatives for the secondary parameter estimates.
The matrix of covariance for the secondary parameter estimates.
The coefficients of variations for the secondary parameter estimates.
The confidence interval for the secondary parameter estimates.
Sebastien Bihorel ([email protected])
Pawel Wiczling
D.Z. D'Argenio and A. Schumitzky. ADAPT II User's Guide: Pharmacokinetic/ Pharmacodynamic Systems Analysis Software. Biomedical Simulations Resource, Los Angeles, 1997.
get.cov.matrix is a secondary function called during estimation runs by
fitmle.cov. It computes the covariance matrix for the parameter
estimates. get.cov.matrix is typically not called directly by users.
get.cov.matrix(problem = NULL, Fit = NULL)get.cov.matrix(problem = NULL, Fit = NULL)
problem |
A list containing the following levels:
|
Fit |
A list of containing the following levels:
|
Return a list with the following elements:
The matrix of covariance for the parameter estimates.
A data.frame with the same structure as
problem$init but only containing the sorted estimated estimates.
The sorting is performed by order.param.list.
Sebastien Bihorel ([email protected])
get.events is a secondary function called by dde.model. It
creates a data.frame of events from the bolus dosing records found in the
dataset. get.events is typically not called directly by users.
get.events(bolus = NULL, scale = NULL)get.events(bolus = NULL, scale = NULL)
bolus |
b x 4 data.frame providing the instantaneous inputs |
scale |
s x 1 vector of scaling factors |
Return a data.frame of events with the following elements:
A name of the state affected by the event
The time of the event
The value associated with the event
How the event affects the state ('add' by default)
See events for more details
Sebastien Bihorel ([email protected])
codeevents
get.layout is a utility function called by estimation.plot and
simulation.plot. It provides a layout for lattice functions based
upon a user-defined number of plots per page. get.layout is typically
not called directly by users.
get.layout(nplot = NULL)get.layout(nplot = NULL)
nplot |
A integer scalar defining the number of plots per page. |
Return a vector of two integers (nx,ny), where nx is the number of rows and ny the number of columns for the lattice layout.
Sebastien Bihorel ([email protected])
estimation.plot,
simulation.plot
get.layout(1) get.layout(7) ## Not run: get.layout(1:5) ## Not run: get.layout(NA)get.layout(1) get.layout(7) ## Not run: get.layout(1:5) ## Not run: get.layout(NA)
get.parms.data is a utility function in scaRabee. It allows to
extract from a parameter table x all the data of a given type
which for a set of parameter of type type. get.parms.data
is typically not called directly by users.
get.parms.data(x = NULL, which = NULL, type = NULL)get.parms.data(x = NULL, which = NULL, type = NULL)
x |
A data.frame of parameter data with the following columns: 'names', 'type', 'value', 'isfix', 'lb', and 'ub'. |
which |
A single string of characters, either 'names', 'type', 'value' or 'isfix'. |
type |
A single string of characters, either 'P', 'L', 'V' or 'IC'. |
Return as a vector the content of the which column of x
corresponding to the type parameters.
Sebastien Bihorel ([email protected])
get.secondary is a secondary function called during estimation runs by
fitmle.cov. It computes estimates of secondary parameters and related
statistics (covariance, coefficient of variations, and confidence intervals).
get.secondary is typically not called directly by users.
get.secondary(subproblem = NULL, x = NULL)get.secondary(subproblem = NULL, x = NULL)
subproblem |
A list containing the following levels:
|
x |
The vector of p parameter estimates. |
Return a list of with the following elements:
The vector of s secondary parameter estimates derived from initial structural model parameter estimates.
The vector of s secondary parameter estimates derived from final structural model parameter estimates.
The vector of s secondary parameter names.
The p x s matrix of partial derivatives for the secondary parameters.
Sebastien Bihorel ([email protected])
initialize.report is a secondary function called during direct grid
search or estimation runs.
For direct grid search runs, initialize.report creates the report file
in the results & backup directory. This report file reports information about
the run, including a summary table of the grid search which gives the value of
the objective function for the different vector of estimates tested.
For estimation runs, initialize.report creates the log file and the
report file in the results & backup directory. The log file stores, for each
subject in the analysis, the values of the objective function and the
parameter estimates at each iteration of the estimation process. The report
file reports information about the estimation run, including the final
estimates and some related statistics.
initialize.report is typically not called directly by users.
initialize.report(problem = NULL, param = NULL, files = NULL, isgrid = 0)initialize.report(problem = NULL, param = NULL, files = NULL, isgrid = 0)
problem |
A list containing the following levels:
|
param |
A data.frame containing the values of fixed and variable parameter estimates. Expected to contain the 'names', 'type', 'value', 'isfix', 'lb', and 'ub' columns. |
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
isgrid |
Indicator of direct grid search runs. |
Sebastien Bihorel ([email protected])
ode.model is the system evaluation function called when an $ODE block
is detected in the model file, indicating that the model is defined by
ordinary differential equations. ode.model is typically not called
directly by users
ode.model(parms = NULL, derparms = NULL, code = NULL, bolus = NULL, infusion = NULL, xdata = NULL, covdata = NULL, issim = 0, check = FALSE, options = list(method='lsoda'))ode.model(parms = NULL, derparms = NULL, code = NULL, bolus = NULL, infusion = NULL, xdata = NULL, covdata = NULL, issim = 0, check = FALSE, options = list(method='lsoda'))
parms |
A vector of primary parameters. |
derparms |
A list of derived parameters, specified in the $DERIVED block of code. |
code |
A list of R code extracted from the model file. Depending on content of the model file, the levels of this list could be: template, derived, lags, ode, dde, output, variance, and/or secondary. |
bolus |
A data.frame providing the instantaneous inputs entering the system of delay differential equations for the treatment and individual being evaluated. |
infusion |
A data.frame providing the zero-order inputs entering the system of delay differential equations for the treatment and individual being evaluated. |
xdata |
A vector of times at which the system is being evaluated. |
covdata |
A data.frame of covariate data for the treatment and individual being evaluated. |
issim |
An indicator for simulation or estimation runs. |
check |
An indicator whether checks should be performed to validate function inputs. |
options |
A list of differential equation solver options. Currently not modifiable by users. |
ode.model evaluates the model for each treatment of each individual
contained in the dataset using several utility functions: derived.parms,
init.cond, input.scaling, make.dosing, init.update,
and de.output.
The actual evaluation of the system is performed by ode from the
deSolve package.
Returns a matrix of system predictions.
Sebastien Bihorel ([email protected])
ode,
init.cond, input.scaling,
make.dosing, init.update,
de.output
This is a collection of utility functions called by ode.model (and for
some by dde.model when a model defined by ordinary (or delay)
differential equations is evaluated. None of these functions is typically
called directly by users.
ode.syst(t = NULL, y = NULL, parms = NULL, derparms = NULL, codeode = NULL, dosing = NULL, has.dosing = NULL, dose.states = NULL, covdata = NULL, scale = NULL, check = FALSE) create.intervals(xdata = NULL, bolus = NULL, infusion = NULL) de.output(f = NULL, parms = NULL, derparms = NULL, codeoutput = NULL, dosing = NULL, xdata = NULL, check = FALSE) derived.parms(parms = NULL, covdata, codederiv = NULL, check = FALSE) init.cond(parms = NULL, derparms = NULL, codeic = NULL, dosing = NULL, check = FALSE) input.scaling(parms = NULL, derparms = NULL, codescale = NULL, ic = NULL, check = FALSE) make.dosing(allparms = NULL, bolus = NULL, infusion = NULL, check = FALSE) init.update(a = NULL, t = NULL, dosing = NULL, scale = NULL)ode.syst(t = NULL, y = NULL, parms = NULL, derparms = NULL, codeode = NULL, dosing = NULL, has.dosing = NULL, dose.states = NULL, covdata = NULL, scale = NULL, check = FALSE) create.intervals(xdata = NULL, bolus = NULL, infusion = NULL) de.output(f = NULL, parms = NULL, derparms = NULL, codeoutput = NULL, dosing = NULL, xdata = NULL, check = FALSE) derived.parms(parms = NULL, covdata, codederiv = NULL, check = FALSE) init.cond(parms = NULL, derparms = NULL, codeic = NULL, dosing = NULL, check = FALSE) input.scaling(parms = NULL, derparms = NULL, codescale = NULL, ic = NULL, check = FALSE) make.dosing(allparms = NULL, bolus = NULL, infusion = NULL, check = FALSE) init.update(a = NULL, t = NULL, dosing = NULL, scale = NULL)
t |
A scalar or a vector of numerical time values. |
y |
A vector of system state values. |
parms |
A vector of primary parameters. |
derparms |
A list of derived parameters, specified in the $DERIVED block of code. |
codeode |
The content of the R code specified within the $ODE block in the model file. |
dosing |
A data.frame of dosing information created by
|
has.dosing |
A logical variable, indicating whether any input has to be assigned to a system state. |
dose.states |
A vector of integers, indicating in which system state one or more doses have to be assigned to. |
covdata |
A matrix of covariate data extracted from the dataset. |
scale |
A vector of system scale, typically returned by
|
check |
An indicator whether checks should be performed to validate function inputs |
xdata |
A vector of times at which the system is being evaluated. |
bolus |
bij x 4 data.frame providing the instantaneous inputs for a treatment and individual. |
infusion |
fij x (4+c) data.frame providing the zero-order inputs for a treatment and individual. |
f |
A matrix of time (first row) and system predictions. In the
|
codeoutput |
The content of the R code specified within the $OUTPUT block in the model file. |
codederiv |
The content of the R code specified within the $DERIVED block in the model file. |
codeic |
The content of the R code specified within the $IC block in the model file. |
codescale |
The content of the R code specified within the $SCALE block in the model file. |
ic |
A vector of initial conditions, typically returned by |
allparms |
A vector of parameters (primary+derived). |
a |
A vector of system state values, similar to |
ode.syst is the function which actually evaluates the system of
ordinary differential equations specified in the $ODE block.
create.intervals is a function that allows the overall integration
interval to be split into sub-intervals based upon dosing history.
This allows for the exact implementation of bolus inputs into the system. It
determines the number of unique bolus dosing events there is by system state
in dosing. It then creates the sub-intervals using these unique event
times. If the first dosing events occurs after the first observation time, an
initial sub-interval is added.
de.output is the function which evaluates the code specified in the
$OUTPUT block and, thus, defines the output of the model.
derived.parms is the function which evaluates the code provided in the
$DERIVED block and calculate derived parameters. It prevents primary
parameters and covariates from being edited.
init.cond is the function which evaluates the code provided in the $IC
block, and, thus, defines the initial conditions of the system.
input.scaling is the function which evaluates the code provided in the
$SCALE block, and, thus, defines how system inputs are scaled.
make.dosing is the function which processes the instantaneous and
zero-order inputs provided in the dataset and creates the dosing
object. This function also implements absorption lags if the user included
ALAGx parameters in parms or derpamrs.
init.update is a function that updates the system states at the
beginning of each integration interval created by create.intervals to
provide an exact implementation of bolus inputs into the system.
Sebastien Bihorel ([email protected])
order.parms.list is a secondary function called during estimation runs.
It reorder a data.frame of initial parameter estimates by type: structural
('P'), delays ('L'), initial conditions ('IC'), and finally variance ('V').
order.parms.list is typically not called directly by users.
order.parms.list(x = NULL)order.parms.list(x = NULL)
x |
A data.frame of parameter data with the following columns: 'names', 'type', 'value', 'isfix', 'lb', and 'ub'. |
A data.frame of parameter data with the following columns: 'names', 'type', 'value', 'isfix', 'lb', and 'ub'.
Sebastien Bihorel ([email protected])
pder is a secondary function called by get.cov.matrix. It
computes the matrix of partial derivatives for the model predictions and the
residual variability. pder is typically not called directly by users.
pder(subproblem = NULL, x = NULL)pder(subproblem = NULL, x = NULL)
subproblem |
A list containing the following levels:
|
x |
The vector of p final parameter estimates. |
Return a list containing the p x p matrices of partial
derivatives for model predictions (mpder) and residual variability
(wpder).
Sebastien Bihorel ([email protected])
problem.eval is a secondary function called during estimation runs. It
evaluates the structural model and the residual variability model at given
point estimates and at given values of the time variable. problem.eval
is typically not called directly by users.
problem.eval(subproblem = NULL, x = NULL, grid = FALSE, check = FALSE)problem.eval(subproblem = NULL, x = NULL, grid = FALSE, check = FALSE)
subproblem |
A list containing the following levels:
|
x |
A vector of numerical estimates of numerical parameters. |
grid |
A logical variable, indicating whether the analysis is a direct grid search or not. |
check |
An indicator whether checks should be performed to validate function inputs. |
Return a list of two elements:
A vector of model evaluations at all requested time points (all states values are concatenated into a single vector).
A vector of residual variability related to the model evaluations.
Sebastien Bihorel ([email protected])
residual.report is a secondary function called at the end of the
estimations runs. It creates a file containing the predictions, residuals and
weighted residuals at all observation time points. residual.report is
typically not called directly by users.
residual.report(problem = NULL, Fit = NULL, files = NULL)residual.report(problem = NULL, Fit = NULL, files = NULL)
problem |
A list containing the following levels:
|
Fit |
A list containing the following elements:
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Creates the prediction and residual report in the run directory.
Sebastien Bihorel ([email protected])
scarabee.analysis is the de facto gateway for running any kind
of analysis with scaRabee. All other functions distributed with this
package are secondary functions called directly or indirectly by
scarabee.analysis.
Arguments for scarabee.analysis are best defined using the template
distributed with the package.
scarabee.analysis(files = NULL, method = 'population', runtype = NULL, debugmode = FALSE, estim.options = NULL, npts = NULL, alpha = NULL, solver.options = list(method='lsoda'))scarabee.analysis(files = NULL, method = 'population', runtype = NULL, debugmode = FALSE, estim.options = NULL, npts = NULL, alpha = NULL, solver.options = list(method='lsoda'))
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
method |
A character string, indicating the scale of the analysis. Should be 'population' or 'subject'. |
runtype |
A character string, indicating the type of analysis. Should be 'simulation', 'estimation', or 'gridsearch'. |
debugmode |
A logical value, indicating the debug mode should be turn on
( |
estim.options |
A list of estimation options containing two elements
|
npts |
Only necessary if |
alpha |
Only necessary if |
solver.options |
A list of differential equation solver options. Currently not modifiable by users. |
Run an analysis until completion. See
vignette('scaRabee',package='scaRabee') for more details about the
expected outputs for an estimation, a simulation, or a gird search run.
Sebastien Bihorel ([email protected])
scarabee.check.model is a secondary function called at each
scaRabee estimation run. It runs a first set of model evaluation at the
initial parameter estimates turning all checks on. If all checks are passed,
the estimation starts with all checks turned off. scarabee.check.model
is typically not called directly by users.
scarabee.check.model(problem = NULL, files = NULL)scarabee.check.model(problem = NULL, files = NULL)
problem |
A list containing the following levels:
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Sebastien Bihorel ([email protected])
scarabee.check.reserved is a secondary function called at each
scaRabee run. It determined whether user-defined parameter names use
reserved names and if some user-defined parameters are related to the dosing
history. scarabee.check.reserved is typically not called directly by
users. scarabee.check.reserved is typically not called directly by
users.
scarabee.check.reserved(names = NULL, covnames = NULL)scarabee.check.reserved(names = NULL, covnames = NULL)
names |
A vector of parameter names, typically extracted from the file of parameter definition. |
covnames |
A vector of covariate names, typically extracted from the data file. |
If one or more user-defined parameters are found to use reserved names, the run is stopped and the user is ask to update the name(s) of this(ese) parameter(s).
Sebastien Bihorel ([email protected])
scarabee.clean is a secondary function called at each scaRabee
run. It cleans the run directory from unwanted files. scarabee.clean
is typically not called directly by users.
scarabee.clean(files = NULL, analysis = NULL)scarabee.clean(files = NULL, analysis = NULL)
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
analysis |
A character string directly following the $ANALYSIS tag in the model file. |
Sebastien Bihorel ([email protected])
scarabee.directory is a secondary function called at each
scaRabee run. It creates a directory to store the results of the run and
a sub-directory to backup all files used for the run. This directory is
referred to as the 'run directory' in all scaRabee documentation and
help. scarabee.directory is typically not called directly by users.
scarabee.directory(curwd = getwd(), files = NULL, runtype = NULL, analysis = NULL)scarabee.directory(curwd = getwd(), files = NULL, runtype = NULL, analysis = NULL)
curwd |
The current working directory. |
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
runtype |
A character string, indicating the type of analysis. Should be 'simulation', 'estimation', or 'gridsearch'. |
analysis |
A character string directly following the $ANALYSIS tag in the model file. |
When scarabee.directory is called, a new folder is created in the
working directory. The name of the new folder is a combination of the string
directly following the $ANALYSIS tag in the model file, an abbreviation of the
type of run ('est' for estimation, 'sim' for simulation, or 'grid' for grid
search) and an incremental integer, e.g. 'test.est.01'. This directory
contains the text and graph outputs of the run.
Additionally, a sub-directory called run.config.files is created into
the new folder and all the files defining the run, i.e. the dataset, the file
of initial model parameters, the model file and the master R script), are
stored.
Sebastien Bihorel ([email protected])
scarabee.gridsearch is a secondary function called during direct grid
search runs. It creates a matrix made of unique vectors of parameter
estimates set around the vector of initial estimates and evaluates the
objective function (i.e. minus twice the log of the exact likelihood of the
observed data, given the structural model, the model of residual variability,
and the vector of parameter estimates) at each of those vectors at the
population level. The grid of objective function values is then sorted and the
best vector is used to simulate the model at the population level.
scarabee.gridsearch is typically not called directly by users.
scarabee.gridsearch(problem = NULL, npts = NULL, alpha = NULL, files = NULL)scarabee.gridsearch(problem = NULL, npts = NULL, alpha = NULL, files = NULL)
problem |
A list containing the following levels:
|
npts |
An integer greater than 2, defining the number of points that the grid should contain per dimension (i.e variable model parameter). |
alpha |
A vector of numbers greater than 1, which give the factor(s) used
to calculate the evaluation range of each dimension of the search grid (see
Details). If |
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
The actual creation of the grid and the evaluation of the objective function
is delegated by scarabee.gridsearch to the fmin.gridsearch
function of the neldermead package.
This function evaluates the cost function - that is, in the present case, the
objective function - at each point of a grid of npts^length(x0) points,
where x0 is the vector of model parameters set as variable. If
alpha is NULL, the range of the evaluation points is limited by the
lower and upper bounds of each parameter of x0 provided in the
parameter file. If alpha is not NULL, the range of the evaluation
points is defined as [x0/alpha,x0*alpha].
Because fmin.gridsearch can be applied to the evaluation of constrained
systems, it also assesses the feasibility of the cost function at each point
of the grid (i.e. whether or not the points satisfy the defined constraints).
In the context of scaRabee, the objective function is always feasible.
Return a data.frame with pe+2 columns. The last 2 columns report the value and the feasibility of the objective function at each specific vector of parameter estimates which is documented in the first pe columns. This data.frame is ordered by feasibility and increasing value of the objective function.
Sebastien Bihorel ([email protected])
scarabee.new creates a new scaRabee analysis folder.
scarabee.new(name = 'myanalysis', path = NULL, type = 'simulation', method = 'population', template = 'ode')scarabee.new(name = 'myanalysis', path = NULL, type = 'simulation', method = 'population', template = 'ode')
name |
A string of characters defining the name of the master analysis
script; |
path |
A path where the analysis files must be created. The path must not yet exist. |
type |
A string of characters, either 'simulation', 'estimation', or 'gridsearch'. Default is 'simulation'. |
method |
A string of characters, either 'population' or 'subject'. Default is 'population'. |
template |
A string of characters, either 'explicit', 'ode' or 'dde'. Default is 'ode'. |
The content of new scaRabee analysis folder path/
is:
name.RThe template-based scaRabee analysis script.
A template-based txt file for the definition of the
structural model. Depending on template, this text file contains
various tags which delimit blocks of R code needed when models are defined
with closed form solution ('explicit'), ordinary differential equations
('ode') or delay differential equations ('dde').
(optional) An empty comma-separated file for dosing, observations, and covariate information; contains the following default headers: OMIT, TRT, ID, TIME, AMT, RATE, CMT, EVID, DV, DVID, and MDV.
(optional) An empty comma-separated file for initial guesses of model parameter estimates; contains the following default headers: Parameter, Type, Value, Fixed, Lower bound, Upper bound.
If the path argument is NULL, then it is coerced to name, thus
creating a new folder in the current working directory.
See vignette('scaRabee',package='scaRabee') to learn about how to
specify your model based on those template files.
Sebastien Bihorel ([email protected])
scarabee.read.data is a secondary function called at each
scaRabee run. It reads and processes the data contained in the specified
data file.scarabee.read.data is typically not called directly by users.
scarabee.read.data(files = NULL, method = NULL)scarabee.read.data(files = NULL, method = NULL)
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
method |
A character string, indicating the scale of the analysis. Should be 'population' or 'subject'. |
Return a list with 2 levels:
A list which content depends on the scope of the analysis. If
the analysis was run at the level of the subject, data contains as
many levels as the number of subjects in the dataset, plus the ids
level containing the vector of identification numbers of all subjects
included in the analysis population. If the analysis was run at the level
of the population, data contains only one level of data and
ids is set to 1.
Each subject-specific level contains as many levels as there are treatment
levels for this subject, plus the trts level listing all treatments
for this subject, and the id level giving the identification number
of the subject.
Each treatment-specific levels is a list containing the following levels:
mij x 3 data.frame containing the times of observations of the dependent variables (extracted from the TIME variable), the indicators of the type of dependent variables (extracted from the CMT variable), and the actual dependent variable observations (extracted from the DV variable) for this particular treatment and this particular subject.
mij x c data.frame containing the times of observations of the dependent variables (extracted from the TIME variable) and all the covariates identified for this particular treatment and this particular subject.
bij x 4 data.frame providing the instantaneous inputs for a treatment and individual.
fij x (4+c) data.frame providing the zero-order inputs for a treatment and individual.
the particular treatment identifier.
A logical indicator defining whether or not a modified data file has been created based upon the original file. This is the case if and if only the time of first data record for one or more individuals in the original data file is not 0. The new data file is created such as the TIME variable is modified so that time of the first data record for all individuals is 0; the time of later records is modified accordingly.
Sebastien Bihorel ([email protected])
scarabee.read.model is a secondary function called at each
scaRabee run. It reads and processes the data contained in the specified
model file. This function performs numerous checks to ensure that the model
file contains the expected information. scarabee.read.model is
typically not be called directly by users.
scarabee.read.model(files = NULL, runtype = NULL)scarabee.read.model(files = NULL, runtype = NULL)
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
runtype |
A single character string, indicating the type of run; either 'estimation', 'simulation', or 'gridsearch'. |
Return a list with various levels, depending on the content of the model file and the type of run:
The character string which follows the $ANALYSIS tag.
A character string, indicating which scaRabee function needs to be called to evaluate the model. This level is set to 'ode.model' if the $ODE tag is detected, to 'dde.model' if the $DDE tag is detected, and to 'explicit.model' otherwise.
A character string containing the R code provided within the $DERIVED block. (Only for models defined with $ODE or $DDE).
A character string containing the R code provided within the $IC block. (Only for models defined with $ODE or $DDE).
A character string containing the R code provided within the $SCALE block. (Only for models defined with $ODE or $DDE).
A character string containing the R code provided within the $ODE or $DDE block. (Only for models defined with $ODE or $DDE).
A character string containing the R code provided within the $LAGS block. (Only for models defined with $DDE).
A character string containing the R code provided within the $OUTPUT block.
A character string containing the R code provided within the $VARIANCE block.
A character string containing the R code provided within the $SECONDARY block.
Sebastien Bihorel ([email protected])
scarabee.read.parms is a secondary function called at each
scaRabee run. It reads and checks the information contained in the
specified parameter file.scarabee.read.parms is typically not called
directly by users.
scarabee.read.parms(files = NULL)scarabee.read.parms(files = NULL)
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
If the content of the parameter file is valid, scarabee.read.parms
returns a data.frame with the same content. The names of the data.frame
columns are: names, type, value, isfix, lb, and ub.
Sebastien Bihorel ([email protected])
simulation.plot is a secondary function called at the end of the
simulation runs. It generates overlay plots of model predictions and
observations for all the output system states and for each subject in the
analysis. If the analysis is run at the population level, only one set of
plots is generated. See vignette('scaRabee',package='scaRabee') for
more details. simulation.plot is typically not called directly by
users.
simulation.plot(problem = NULL, simdf = NULL, files = NULL)simulation.plot(problem = NULL, simdf = NULL, files = NULL)
problem |
A list containing the following levels:
|
simdf |
A data.frame of simulated and observed data typically created
by
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Sebastien Bihorel ([email protected])
simulation.report is a secondary function called to initiate a
simulation run in scaRabee. It evaluates the structural model using the
initial estimates of model parameters and outputs the results to a report file
stored in the run directory. See vignette('scaRabee',package='scaRabee')
for more details. simulation.report is typically not called directly
by users.
simulation.report(problem = NULL, files = NULL)simulation.report(problem = NULL, files = NULL)
problem |
A list containing the following levels:
|
files |
A list of input used for the analysis. The following elements are expected and none of them could be null:
|
Creates a simulation report and returns a data.frame of simulated and observed data containing the following columns:
Subject Identifier. If the analysis is run at the population level and if the original dataset contained multiple subjects distinguished by a different ID number, please note that the original ID is lost and replaced by 1 so that all available data is considered to come from the same subject.
Indicator of treatment level (defining the sub-problems).
Indicator of system state to which the simulated or observed value is associated.
Time of the observation or model prediction.
Value of the simulated state. NA if DV is not NA.
Value of the observed state. NA if SIM is not NA.
Sebstien Bihorel ([email protected])
weighting is a secondary function called during estimation run to
evaluate the model(s) of residual variability specified by the code provided
in the $VARIANCE block. weighting is typically not called directly by
users.
weighting(parms = NULL, derparms = NULL, codevar=NULL, y=NULL, xdata=NULL, check=FALSE)weighting(parms = NULL, derparms = NULL, codevar=NULL, y=NULL, xdata=NULL, check=FALSE)
parms |
A vector of primary parameters. |
derparms |
A list of derived parameters, specified in the $DERIVED block of code. |
codevar |
The content of the R code specified within the $VARIANCE block in the model file. |
y |
The matrix of structural model predictions. |
xdata |
A vector of times at which the system is being evaluated. |
check |
An indicator whether checks should be performed to validate function inputs |
Return a matrix of numeric values of the same dimension as f.
Sebastien Bihorel ([email protected])