Sample individual parameter values, based on a NLME parameter specification

sampleIndParamValues.Rd

Sample 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 (see Npop). 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 Nsample rows representing sampled records from the patient data.

$typicalIndParamValues :

a data.frame of Nsample * nrow(popParamValues) rows, columns ID.POP and ID, 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 $typicalIndParamValues containing the random effects sampled from the IIV distribution (in normal units).

$indParamValues :

a data.frame of the same dimensionality as $typicalIndParamValues containing 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

General Parameter Format

Other Parameter sampling: calcIndParamValues(), calcTypicalIndParamValues(), combineGPF(), generate_GPFFromIQRnlmeEst(), generate_GPFFromIQRnlmeProject(), generate_GPFFromProjectInfo(), generate_GPFFromProjectInfoList(), 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()

Author

Venelin Mitov (IntiQuan)

Examples

if (FALSE) { # \dontrun{
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
} # }