Creating an IQRnlmeEst object
This function creates an IQRnlmeEst object that subsequently can be used to export this object as a NONMEM or MONOLIX IQRnlmeProject.
IQRnlmeEst(model, dosing, data, modelSpec = NULL, FLAGqsp = FALSE)
An IQRmodel or a path to an IQRmodel
A list with one field per input in the model. Fields need to be named according to the input names in the model. Each field is a named vector with the required name "type" and the optional names "Tlag" and "Tk0". "type" can be "BOLUS", "INFUSION", or "ABSORPTION0". Only difference between INFUSION and ABSORPTION0 is that in the first case the infusion RATE is provided and in the second the absorption time is estimated. Lag times can be added to each dosing input by defining "Tlag" as vector element. The value of this element needs to be the parameter named for this lag time. For INPUT1 this is "Tlag1" and for INPUT2 this is "Tlag2", etc. If type="ABSORPTION0" then also "Tk0" needs to be present as element in the vector. The value is a parameter name that also needs to appear in the model. For examples see
A list with the following required field: "datafile". "datafile" needs to be the path to the dataset. Can be absolute or relative (from current working directory). Optional fields are: "
covNames": vector with names of continuous candidate covariates in the dataset. "
catNames": vector with names of catgegorical candidate covariates in the dataset. "
regressorNames": vector with names of regressors in the dataset. Regressor names can be provided in any desired order. It will be checked if ordering in dataset and model is the same. If ordering is not the same an error will be shown. For flexibility, instead of a path to the "datafile" also a data.frame can be provided. In this case this dataset will always be stored inside the IQRnlmeProject.
A list with several entries, defining information what to estimate in the model.
If TRUE then it is assumed that SysFit is used ... which allows to relax some of the checks that are needed for NONMEM. Do not use if you do not know exactly what you are doing!
Entry Doc =============== =================================================== POPestimate A named vector. Names are names of the parameters set to "estimate" in the model. A value of 0 indicates that the fixed effect of this parameter is fixed on its initial guess. A value of 1 indicates that this parameter is estimated. POPvalues0 A named vector. Names are names of the parameters set to "estimate" in the model. Values are the initial guesses for the fixed effects. This is a required entry, as the function needs to know at least which parameters are in scope for the estimation! IIVdistribution A named vector. Names are names of the parameters set to "estimate" in the model. Elements can be "N", "L", and "G". "N" indicates a normal distribution of the corresponding individual parameters. "L": logNormal, and "G": logitNormal. If IOV is estimated, the same distribution is used. IIVestimate A named vector. Names are names of the parameters set to "estimate" in the model. A value of 0 indicates that the random effect of this parameter is fixed to 0. A value of 1 indicates that the random effect is estimated. A value of 2 indicates that this random effect is fixed to its initial guess and not estimated. IIVvalues0 A named vector. Names are names of the parameters set to "estimate" in the model. Values are the initial guesses for the random effects. IOVestimate A named vector. Names are names of the parameters set to "estimate" in the model. A value of 0 indicates that the IOV of this parameter is fixed to 0. A value of 1 indicates that the IOV is estimated. A value of 2 indicates that this IOV is fixed to its initial guess and not estimated. IOVvalues0 A named vector. Names are names of the parameters set to "estimate" in the model. Values are the initial guesses for the IOV. Same distribution as for IIV is assumed. errorModel A list with as many fields as OUTPUT* definitions in the model. Names of these fields need to be the names of the OUTPUT* definitions. Each field is defined by a vector with the following elements: First element: "type" and "guess". "type" can be "abs" for absolute/additive error model, "rel" for relative/proportional error model, and "absrel" for absolute/additive : relative/proportional error model. Following elements (optional): initial guesses for error parameters. For "abs" and "rel" only one additional element needs to be present. For "absrel" two, whereby the first element is the initial guess for the absolute error and the second for the relative error. In addition it is possible to choose "event" for the error model type. This allows Joint Modeling with a TTE outcome. In this case no initial guess needs to be provided but the name of the variable in the model that describes the hazard function value. covarianceModel Vector with definitions of blocks. Syntax is as follows:
covarianceModel = c("ka,CL,Vc","Q1,Q2"). If covarianceModel=NULL or
covarianceModel = "diagonal"then no off diagonal elements will be estimated. IMPORTANT: If NONMEM BAYES algorithm is planned to be used then covariance model needs to be full! This means that if any of the prior information is provided, the covarianceModel setting will be disregarded and et to full. The user is warned about that.
covariateModel List with definition of covariate model. Elements are named with the names of the parameters on which to add a covariate. Values are vectors with names of covariates to add. By default continuous covariates will be added as *(COV/REF)^THETA and categorical covariates multiplicative as well. Reference values are medians of continuous and smallest categories of categorical covariates. More details on the exact equations used for the different scales N,L,G can be found in the book, section 18.104.22.168. More complex desired covariate models can be coded in the model itself - then covariates become "regression" parameters. Example:
covariateModel = list( CL = c("WT0","SEX"), ka = c("SEX"), Vc = c("WT0") )
covariateModelValues List with definition of covariate model initial guesses. Elements are named with the names of the parameters on which to add a covariate. Values are named vectors with names of covariates and values as the initial guesses. For categorical covariates the same initial guess is used for all categories.
covariateModelValues = list( CL = c(WT0=0.75, SEX=0.3), ka = c(SEX=0.5), Vc = c(WT0=1) )
COVestimate List with definition of covariate model estimation settings. Elements are named with the names of the parameters on which to add a covariate. Values are 1 for estimation and 0 for fixing the covariate coefficient. For categorical covariates only all category coefficients or none can be estimated or fixed. Example:
COVestimate = list( CL = c(WT0=0, SEX=1), ka = c(SEX=1), Vc = c(WT0=0) )
COVcentering Named vector, defining the centering/reference values for covariates. Example:
COVcentering = c(WT0=70, SEX=2)
Priors for fixed effects, covariate coefficients, random effect, and error model parameters can be provided for use with the BAYES algorithm in NONMEM (MONOLIX is currently not supported for BAYES). Important: priors for fixed effects are defined by the initial guesses, provided in
POPvalues0. Priors for covariate coefficients are provided by the initial guesses in
covariateModelValues. Priors for error model parameters are provided as the inital guesses in
errorModel. The definition of prior variances and priors for random effects are documented below:
Entry Doc ============================ =================================================== PriorVarPOP An unnamed vector (same order as in POPvalues0), defining the variances of the priors for the fixed effects. If this argument is not provided, non-informative priors will be used with variance 100*trans(POPvalues0). Where trans() depends on the individual distribution "L": log, "N": none, "G": logit. Please avoid starting guesses that lead to 0 transformed values! PriorVarCovariateModelValues A list with the same struture as covariateModelValues, defining the variances for the priors of the covariate coefficients. If undefined 1000 times covariateModelValues will be used (non-informative). Example:
PriorVarCovariateModelValues = list( CL = c(WT0=0.1, SEX=10), ka = c(SEX=1000), Vc = c(WT0=0.1) )
PriorDFerrorModel Degrees of freedom of SIGMA Prior. Scalar value for vector (integers). If scalar then same value is used for all sigmas. If vector then the length of the vector needs to match the number of error model parameters. Only used currently for NONMEM BAYES estimation. Default scalar value: 4 (arbitrarily chosen). PriorIIV An unnamed matrix of dimension NxN where N is the number of fixed effects in the model. Standard deviation priors for random effects in the diagonal. And priors for correlations in the off-diagonal elements. ONLY WORKS CORRECTLY FROM NONMEM 7.4 on! Do NOT use with NONMEM <7.4! Full matrix of dimension NxN needs to be provided, where N is the number of fixed effects in the model. Only lower triangular matrix will be used. If not provided, a diagonal matrix with initial guesses for standard devitation of the random effects will be used. The order of the matrix can not be selected but is the same as the ordering of the named elements in POPvalues0. Internally, the matrix will be split according to the provided covariance model into block diagonal elements. PriorDFIIV Degrees of freedom of OMEGA Prior. Scalar value for vector (integers). If scalar then same value is used for all omega blocks. If vector then the length of the vector needs to match the number of omega blocks. One important thing here is that the all omega blocks (even if of dimension 1) need to be defined in the covarianceModel argument (parameters for which no IIV is estimated should not appear in the covarianceModel argument). Only used currently for NONMEM BAYES estimation. Default scalar value: 4 (arbitrarily chosen). You could set it according to the formula that was proposed by D. Mats Karlsson:
2*[(Omega estimate of previous analysis)/(SE of omega of previous analysis)]^2or
2*[(Omega estimate of previous analysis)/(SE of omega of previous analysis)]^2+1
A local model specification can be provided for
IQRsysEstto define condition-specif parameters:
Entry Doc ============================ =================================================== LOCmodel A list with names corresponding to model parameters. Each entry of the list specifies the condition names for which this parameter has a specific value. Example:
LOCmodel = list( CL = c("Low", "High"), ka = c("Low") )
LOCvalues0 A list with names corresponding to model parameters. Each entry of the list specifies the parameter value for a specific condition. Example:
LOCvalues0 = list( CL = c(Low = 0.01, High = 10), ka = c(Low = 1.6) )
LOCestimate A list with names corresponding to model parameters. Each entry of the list specifies if the parameter should be estimated. Example:
LOCvalues0 = list( CL = c(Low = 1, High = 1), ka = c(Low = 0) )
An IQRnlmeEst object