Sample individual parameter values, based on a NLME parameter specification
sampleIndParamValues.RdSample individual parameter values, based on a NLME parameter specification
sampleIndParamValues(
spec,
data = NULL,
Nsamples = 1,
Npop = if (FLAG_SAMPLE == 2) Nsamples else 1L,
FLAG_SAMPLE = 0
)Arguments
- spec
a filename (character string) denoting the path to a GPF excel file, or a GPF object, or an IQRnlmeParamSpec object.
- data
a data.frame describing patient or other subject covariate and regressor data. If nrow(data)==Nsamples, then all rows in data are returned (in their original order) in the resulting data.frame; if nrow(data)>Nsamples, sampling without replacement from the rows in data is done; if nrow(data)<Nsamples then sampling with replacement is done.
- Nsamples
integer denoting the number of individuals in a population. Note: in the case of
FLAG_SAMPLE=2, this value is used to specify the number of populations (seeNpop). Default:if(is_IQRnlmeParamSpec(obj)) obj$Nsamples else 1L.- Npop
integer denoting the number of populations to sample. Default:
if(is_IQRnlmeParamSpec(obj)) obj$Npop else if(FLAG_SAMPLE==2) Nsamples else 1L.- FLAG_SAMPLE
-
Flag indicating the type of sampling:
FLAG_SAMPLE Meaning =========== =================================================== 0 Use point estimates of population parameters (do not consider uncertainty) and sample Nsample individual patients based on these. Covariates considered if defined by user and used in model. Please note: population parameters do not take covariates into account! 1 Sample single set of population parameters from uncertainty distribution and sample Nsample individual patient parameters based on these. Covariates considered if defined by user and used in model. Please note: population parameters do not take covariates into account! 2 Sample Nsample sets of population parameters from uncertainty distribution. Do not sample from variability distribution and do not take into account covariates (even if user specified). 3 Use point estimates of population parameters (do not consider uncertainty) Return Nsamples sets of population parameters with covariates taken into account. 4 Sample single set of population parameters from uncertainty distribution Return Nsamples sets of population parameters with covariates taken into account. 5 Use point estimates of population parameters (do not consider uncertainty) and sample Nsample individual patients based on these. Covariates considered if defined by user and used in model. Population parameters, typical individual parameters (no IIV, but considering covariates), and individual parameters are returned. 6 Sample single set of population parameters from uncertainty distribution and sample Nsample individual patient parameters based on these. Covariates considered if defined by user and used in model. Sampled population parameters, typical individual parameters (no IIV, but considering covariates), and individual parameters are returned. 7 !Supported in sample_IQRnlmeProject(Check note at the end)! Same as FLAG_SAMPLE=0 but obtaining the empirical random effect covariance matrix from the post-hoc ETAs. Only used for IQRsysProject. If IQRnlmeProject then fallback to flag 0. Note: This option is not supported by sampleIndParamValues since post-hoc etas are not available in the GPF.8 !Supported in sample_IQRnlmeProject(Check note at the end)! Same as FLAG_SAMPLE=1 but obtaining the empirical random effect covariance matrix from the post-hoc ETAs.Only used for IQRsysProject. If IQRnlmeProject then fallback to flag 1. Note: This option is not supported by sampleIndParamValues since post-hoc etas are not available in the GPF.
Value
a named list with the following elements:
-
$popParamValues: a data.frame with a column ID.POP and columns for all population parameter values.
-
$sampledData: a data.frame having
Nsamplerows representing sampled records from the patient data.-
$typicalIndParamValues: a data.frame of
Nsample * nrow(popParamValues)rows, columnsID.POPandID, and columns corresponding to the model parameters. The parameter values represent typical individual parameter values taking into account the corresponding covariate values in$sampledData.-
$randomEffects: a data.frame of the same dimensionality as
$typicalIndParamValuescontaining the random effects sampled from the IIV distribution (in normal units).-
$indParamValues: a data.frame of the same dimensionality as
$typicalIndParamValuescontaining the (final) individual parameter values in original units.-
$FLAG_SAMPLE: same as the argument
-
$Nsamples: same as the argument
Details
If spec is an IQRnlmeParamSpec object and Npop is specified,
the specified argument Npop overwrites the spec$Npop.
See also
Random sampling of NLME model parameters
Other Parameter sampling:
calcIndParamValues(),
calcTypicalIndParamValues(),
combineGPF(),
generate_GPFFromIQRnlmeEst(),
generate_GPFFromIQRnlmeProject(),
generate_GPFFromProjectInfoList(),
generate_GPFFromProjectInfo(),
getCorMatrixUncertainty(),
getCovMatrixIIV(),
getCovMatrixUncertainty(),
getNamesAllParameters(),
getNamesCovariateParameters(),
getNamesCovariates(),
getNamesErrorParameters(),
getNamesIIVCorrParameters(),
getNamesIIVParameters(),
getNamesModelParameters(),
getParamEstimates(),
getParamTransformationTypes(),
imputeTYPEcol_GPF(),
is_GPF(),
is_IQRnlmeParamSpec(),
read_GPFFromCSV(),
read_GPFFromXLS(),
sampleIDs(),
sampleParamFromUncertainty(),
sampleRandomEffects(),
sample_GPF(),
select_FromGPF(),
specifyParamSampling(),
transformParamToNormal(),
untransformParamFromNormal()
Examples
if (FALSE) {
set.seed(1)
covrtData <- data.frame(
ID = seq_len(4),
WT0 = rlnorm(4, 3, sdlog = 0.2),
SEX = sample(c(0, 1), 4, replace = TRUE))
fileGPF <- "material/01-07-PopulationSimulation/GPF/PKparametersNewFormat.xlsx"
# Read the xls file in GPF object: we can pass this object or fileGPF
# as a spec parameter to the sample* and calc* functions.
paramGPF <- read_GPFFromXLS(fileGPF)
set.seed(1)
listResultsSampling <- sampleIndParamValues(
fileGPF,
Nsamples = 10,
FLAG_SAMPLE = 1,
data = covrtData)
# create a IQRnlmeParamSpec object for future use (not suitable for reading by humans):
spec <- specifyParamSampling(fileGPF, Nsamples = 10, FLAG_SAMPLE = 1)
is_IQRnlmeParamSpec(spec)
set.seed(1)
popParamValues<- sampleParamFromUncertainty(spec)
# should be all 0s
listResultsSampling$popParamValues - popParamValues
sampledData <- sampleIDs(covrtData, spec$Nsamples)
# should be all 0s
listResultsSampling$sampledData - sampledData
typicalIndParamValues <- calcTypicalIndParamValues(spec, popParamValues, sampledData)
# should be all 0s
listResultsSampling$typicalIndParamValues - typicalIndParamValues
randomEffects <- sampleRandomEffects(spec, popParamValues)
# should be all 0s
listResultsSampling$randomEffects - randomEffects
indParamValues <- calcIndParamValues(spec, typicalIndParamValues, randomEffects)
# should be all 0s
listResultsSampling$indParamValues - indParamValues
}