createNormalParameters: Create parameters based on a multivariate normal distribution

createNormalParametersR Documentation

Create parameters based on a multivariate normal distribution

Description

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

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.

Value

A data frame containing parameter data

Note

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

Author(s)

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 -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.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


MikeKSmith/MSToolkit documentation built on Feb. 15, 2024, 5:32 p.m.