Create parameters based on a multivariate normal distribution

Creates parameter variables by sampling from a multivariate normal distribution. Parameter values can vary between simulation replicates, but also between subjects within each simulation replicate (between subject variability).

Usage

createNormalParameters(
  subjects,
  names,
  mean,
  covariance = 0,
  range,
  betNames,
  betMean = 0,
  betCov = 0,
  errStruc = c("None", "Proportional", "Additive", "Log-Normal"),
  suffix = ".Between",
  idCol = getEctdColName("Subject"),
  maxDraws = 10,
  seed = .deriveFromMasterSeed(),
  flagName = getEctdColName("ParOmit"),
  digits = 3,
  parRangeTolerance = 0.5
)

Arguments

subjects: (Required) Subjects for which to create parameters
names: (Required) Names of parameters to generate
mean: (Required) Means for fixed parameters
covariance: (Optional) Covariance matrix for fixed parameters. By default, this is a matrix of zeros, representing no error to be included
range: (Optional) Range of acceptable values. Missing by default, resulting in no "range" of values is applied to the data
betNames: (Optional) Between subject effects to create. Default is to not create between subject data
betMean: (Optional) Means for the between subject effects. Default is to not create between subject data
betCov: (Optional) Covariance matrix for the between subject effects. Default is to not create between subject data
errStruc: (Optional) (None) Function to map between subject effects: Additive, Proportional, Log-Normal or None
suffix: (Optional) Suffix to use for retain between subject effects (default is ".Between")
idCol: (Optional) Subject variable name for return data ("SUBJ" by default)
maxDraws: (Optional) Maximum number of iterations for valid parameters (10 by default)
seed: (Optional) Random number generation seed. By default, this is dervied from the current random seed
flagName: (Optional) Flag name for parameters out of bounds ("PAROMIT" by default)
digits: (Optional) Number of digits to which to round generated continuous parameters. Can be an atomic integer, in which case all variables are rounded according to it. Can be a numeric vector of the same length of the number of fixed parameters, in which case each parameter is rounded according to its value. The default is 3
parRangeTolerance: (Optional, default .9) Proportion of subjects with parameters in specified range that is acceptable for us to continue

Value

A data frame containing parameter data

Details

The function first samples a new value for the parameter. This parameter value is used for each subject within the trial replicate. These values are generated from a multivariate normal distribution with mean and covariance matrix specified within the function arguments. These can be viewed as the "fixed effects" for the trial replicate.

If "betNames" argument has been supplied ("betNames" must be a subset of the parameter names supplied in the "names" argument) then another sample will be taken to generate subject-specific parameter values. If the "betMean" input has not been supplied, the mean of the between effects distribution will be 0. Samples for each subject will be taken from a multivariate normal distribution with mean "betMean" and covariate matrix "betCov". "betCov" specifies between subject variability in the parameters.

If fixed and between subject effects have been generated, the "errStruc" input will specify how the between subject effects are to be applied:

None = Keep between subject effect separate (and use the "suffix" supplied to name the variables)
Additive = Add each between subject effect to the corresponding fixed effect
Proportional = Multiply the fixed effect by the exponentiated between subject effect
Log-Normal = Add "1 + each between subject effect" to the corresponding fixed effect

If the "range" argument is provided, the output from the above algorithm (fixed + between) is checked against the acceptance range. If the data is not within range, the function will take "maxDraws" more attempts at the above algorithm to try and generate "in range" data. If that is not possible, the function will stop and return an error.

Note

If earlier versions of MSToolkit, the "Proportional" error structure was implemented as exp(fixed + between subject)

Author

Rich Pugh

Examples


createNormalParameters(5, "E0,ED50,EMAX",
                       mean = c(0, 50, 100),
                       covariance = diag(c(1, 5, 10)))
#>   SUBJ    E0   ED50    EMAX PAROMIT
#> 1    1 1.849 46.618 102.745       0
#> 2    2 1.849 46.618 102.745       0
#> 3    3 1.849 46.618 102.745       0
#> 4    4 1.849 46.618 102.745       0
#> 5    5 1.849 46.618 102.745       0
#  SUBJ       E0     ED50     EMAX   PAROMIT
#1    1 -0.8356286 50.41064 98.01898       0
#2    2 -0.8356286 50.41064 98.01898       0
#3    3 -0.8356286 50.41064 98.01898       0
#4    4 -0.8356286 50.41064 98.01898       0
#5    5 -0.8356286 50.41064 98.01898       0

createNormalParameters(5, "E0,ED50,EMAX",
                       mean = c(0, 50, 100),
                       covariance = diag(c(1, 5, 10)),
                       betNames = c("E0", "EMAX"),
                       betCov = diag(2),
                       errStruc = "Additive")
#>   SUBJ     E0   ED50   EMAX PAROMIT
#> 1    1 -0.085 47.633 96.318       0
#> 2    2  0.039 47.633 97.672       0
#> 3    3 -0.462 47.633 97.402       0
#> 4    4 -2.106 47.633 96.946       0
#> 5    5  0.150 47.633 97.188       0
#  SUBJ       E0     ED50     EMAX   PAROMIT
#1    1  0.7596522 50.41064 98.59476       0
#2    2 -0.5061208 50.41064 97.71359       0
#3    3 -1.6560970 50.41064 99.53076       0
#4    4 -0.3481996 50.41064 98.40882       0
#5    5 -0.0973039 50.41064 97.39774       0

# no covariance by default
createNormalParameters(5, "E0,ED50,EMAX", mean = c(0, 50, 100) )
#>   SUBJ E0 ED50 EMAX PAROMIT
#> 1    1  0   50  100       0
#> 2    2  0   50  100       0
#> 3    3  0   50  100       0
#> 4    4  0   50  100       0
#> 5    5  0   50  100       0
#  SUBJ E0 ED50 EMAX PAROMIT
#1    1  0   50  100       0
#2    2  0   50  100       0
#3    3  0   50  100       0
#4    4  0   50  100       0
#5    5  0   50  100       0