defineIndividualElement

Usage

defineIndividualElement(name, element)

Arguments

name

(character) Element name.

element

(character or dataFrame or list) Element definition from external file path or data frame with individual parameters as columns, or list to select the sheet of an excel file:

• file (character) Path to the individual parameters file.

• sheet (character) Name of the sheet in xlsx/xls file.

Details

Individual parameters to be defined depend on the model of the simulx project. If only the [LONGITUDINAL] block is present in the model: all parameters of the input list, except those defined as regressors. If both the [LONGITUDINAL] and [INDIVIDUAL] blocks are present: parameters defined in the DEFINITION section of the [INDIVIDUAL] block.

An individual parameters element can be defined as an external file (csv, xlsx, xlsx, sas7bdat, xpt or txt) or as a data frame. In any case, it can contain columns occasions (optional), and it should contain one column per individual parameter (mandatory). The parameter headers must correspond to the parameter names used in the model. The occasion headers must correspond to the occasion names defined in the occasion element.

A data frame can be used only to define individual parameter elements of type 'common', i.e the same for all individuals (but potentially occasion-wise). If you want to define subject-specific individual parameters, use an external file with an "id" column.

An external file can be used in all cases (common or subject-specific). It can contain a column id (optional) in addition to occasions (optional), and should contain one column per parameter (mandatory). When id and occasion columns are present, then they must be the first columns. When the id column is not present, the parameter element is considered common.

If the project has a subject-specific occasion structure (defined with an external file with an ID column (see defineOccasionElement)), occasion-wise common elements are not allowed. In this case, individual parameters elements have to be be either common over all subjects and all occasions, or can be defined with subject-specific occasion-wise values as an external table, with the same occasion structure.

See also

Examples

if (FALSE) {
  defineIndividualElement(name = "name", element = "file/path")
  defineIndividualElement(name = "name", element = list(file = "file/path", sheet = "sheet_name"))
  defineIndividualElement(name = "name", element = data.frame(Tlag = 0.5, ka = 0.25, V = 70, Cl = 12, F = 0.7))
  }
  
  # Defining elements with one and multiple sets of indiv params
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "2.models", "longitudinal_individual.smlx")
  loadProject(project_name)
  defineIndividualElement(name = "custom_params", element = data.frame(Tlag = 0.5, ka = 0.25, V = 70, Cl = 12, F = 0.7)) # one set
  params <- data.frame(id = c(1, 2, 3), Tlag = 0.5, ka = 0.25, V = 70, Cl = 12, F = c(0.6, 0.7, 0.8))
  file_name <- tempfile("cov", fileext = ".csv")
  write.csv(params, file_name, row.names = FALSE)
  defineIndividualElement(name = "different_F", element = file_name) # multiple sets

  # Common occasions
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_common.smlx")
  loadProject(project_name)
  defineIndividualElement(name = "params_per_occ", element = data.frame(occ = c(1, 2), ka = c(0.2, 0.4), V = 10, Cl = 5))

  # Subject-specific occasions
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_external.smlx")
  loadProject(project_name)
  occasions <- getOccasionElements()
  params <- data.frame(ID = occasions$id, occ = unlist(occasions$occasions))
  params$ka <- rlnorm(27, log(0.2), 0.1 + 0.1)
  params$V <- rlnorm(27, log(5), 0.2)
  params$Cl <- rlnorm(27, log(0.3), 0.15)
  file_name <- tempfile("cov", fileext = ".csv")
  write.csv(params, file_name, row.names = FALSE)
  defineIndividualElement(name = "params_external", element = file_name)