R: Direct Grid Search Utility

scarabee.gridsearch {scaRabee}

R Documentation

Direct Grid Search Utility

Description

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.

Usage

  scarabee.gridsearch(problem = NULL,
                      npts = NULL,
                      alpha = NULL,
                      files = NULL)

Arguments

`problem`	A list containing the following levels: data 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: cov 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. cov 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. 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. trt the particular treatment identifier. method A character string, indicating the scale of the analysis. Should be 'population' or 'subject'. init A data.frame of parameter data with the following columns: 'names', 'type', 'value', 'isfix', 'lb', and 'ub'. debugmode Logical indicator of debugging mode. modfun Model function.
`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 `alpha` length is lower than the number of variable parameters, elements of `alpha` are recycled. If its length is higher than number of variable parameters, `alpha` is truncated.
`files`	A list of input used for the analysis. The following elements are expected and none of them could be null: data A .csv file located in the working directory, which contains the dosing information, the observations of the dependent variable(s) to be modeled, and possibly covariate information. The expected format of this file is described in details in `vignette('scaRabee', package='scaRabee')`. param A .csv file located in the working directory, which contains the initial guess(es) for the model parameter(s) to be optimized or used for model simulation. The expected format of this file is described in details in `vignette('scaRabee',package='scaRabee')`. model A text file located in the working directory, which defines the model. Models specified with explicit, ordinary or delay differential equations are expected to respect a certain syntax and organization detailed in `vignette('scaRabee',package='scaRabee')`. iter A .csv file reporting the values of the objective function and estimates of model parameters at each iteration. (Not used for direct grid search runs). report A text file reporting the summary tables of ordered objective function values for the various tested vectors of model parameters. pred A .csv file reporting the predictions and calculated residuals for each individual in the dataset. (Not used for direct grid search runs). est A .csv file reporting the final parameter estimates for each individual in the dataset. (Not used for direct grid search runs). sim A .csv file reporting the simulated model predictions for each individual in the dataset. (Not used for direct grid search runs).

Details

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.

Value

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.

Author(s)

Sebastien Bihorel (sb.pmlab@gmail.com)