tsk_estimation: Task estimation

In sebastianueckert/assemblerr: Assembly of Pharmacometric Models

Task estimation

Description

This function defines an estimation task allowing to specify the estimation algorithm, estimation options, and whether standard errors should be obtained.

Usage

tsk_estimation(algorithm = "foce", se = FALSE, target_options = list())

Arguments

algorithm	The estimation algorithm to use for the task ("foce", "foce-inter", "foce-no-inter", "fo", "imp", "saem")
se	Whether to calculate parameter uncertainties
target_options	List of additional options that should be passed to NONMEM

Details

Tasks

Tasks are building blocks that allow to specify what a model should “do”. Like other model building blocks, they can be combined using the + operator. However, they should not be added to a model but rather provided via the tasks= argument to the render function, e.g.,

render(m, tasks = tsk_estimation() +
   tsk_output_xpose4())

Estimation tasks

Estimation tasks provide details on the parameter estimation process, in terms of estimation algorithm, estimation options and whether standard errors should be obtained.

Algorithm

The algorithm argument allows to select the estimation algorithm among the following options:

foce	First-order conditional estimation with interaction detection
foce-inter	First-order conditional estimation with interaction
foce-no-inter	First-order conditional estimation without interaction
fo	First-order estimation
imp	Importance sampling
saem	Stochastic approximation expectation maximization

The default algorithm "foce" detects whether the observation model includes an epsilon-eta interaction and includes the INTERACTION option accordingly. The foce-inter option forces the use of the INTERACTION argument independent of the residual error model, foce-no-inter enforces no interaction.

Each algorithm includes a set of default options that the package authors consider sensible defaults (for example MAXEVAL=999999 for FOCE). These defaults can be overwritten using the target_options= argument which is described below.

Standard errors

The se= argument allows to request the calculation of parameter standard errors. When standard errors are requested (se=TRUE) it will results in the inclusion of the $COVARIANCE record in the generated control stream.

Target options

The target_options= argument provides a mechanism to specify additional estimation options for the selected algorithm. The options should be provided as a list, e.g.,

tsk_estimation(algorithm = "foce", target_options = list(mceta=100))

The provided options are passed verbatim to the target tool and not checked by assemblerr for correctness.

The target_options= argument

Multiple estimation tasks

A sequence of estimation tasks can be specified in assemblerr by combining multiple estimations, for example

render(m, tasks = tsk_estimation("foce") + tsk_estimation("imp"))

will create model code that contains an FOCE as well as an importance sampling estimation step.

Value

A building block of type 'estimation_task'

See Also

Other tasks: tsk_output()

Examples

m <- model() +
  input_variable("dose") +
  prm_log_normal("emax", median = 10, var_log = 0.09) +
  prm_log_normal("ed50", median = 50, var_log = 0.09) +
  algebraic(effect~emax*dose/(ed50 + dose)) +
  obs_proportional(~effect, var_prop = 1)

# add estimation task using importance sampling, covariance step
# and user-defined ISAMPLE option
render(
  model = m,
  tasks = tsk_estimation(
    algorithm = "imp",
    se = TRUE,
    target_options = list(isample=1000)
  )
)

sebastianueckert/assemblerr documentation built on Sept. 30, 2022, 9:12 a.m.