defineCovariateElement

Usage

defineCovariateElement(name, element)

Arguments

name

(character) Element name.

element

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

• file (character) Path to the population file.

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

Details

Covariate elements can be defined only if the model used in the Simulx project contains a block [COVARIATE].

A covariate 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 covariate (mandatory). Covariate names and categorical covariate values must correspond to covariates and categories defined in the model (block [COVARIATE]). The occasion headers must correspond to the occasion names defined in the occasion element.

A data frame can be used only to define covariate elements of type 'common', i.e the same for all individuals (potentially occasion-wise). If you want to define subject-specific covariates, use an external file with an "id" column. Covariate definition with distributions is only possible in the GUI (in R, please sample from the desired distribution to generate an external file).

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 covariate (mandatory). When id and occasion columns are present, then they must be the first columns. When the id column is not present, the covariate 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. Covariate elements must 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) {
  defineCovariateElement(name = "name", element = "file/path")
  defineCovariateElement(name = "name", element = list(file = "file/path", sheet = "sheet_name"))
  defineCovariateElement(name = "name", element = data.frame(wt = 70, sex = 1, age = 35))
  }
  
  # Create a manual and a subject-specific element
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")
  loadProject(project_name)
  defineCovariateElement(name = "wt_typical", element = data.frame(wt = 70, sex = 1, age = 35)) # manual
  samples <- data.frame(id = 1:10, sex = sample(0:1, 10, replace = TRUE), age = rnorm(10, 30, 10))
  samples$wt <- rnorm(10, mean = ifelse(samples$sex == 0, 62, 75), sd = 10) # mean weight dependent on sex
  file_name <- tempfile("cov", fileext = ".csv")
  write.csv(samples, file_name, row.names = FALSE)
  defineCovariateElement(name = "wt_distribution", element = file_name) # subject-specific

  # Create an element with common occasions
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_common.smlx")
  loadProject(project_name)
  defineCovariateElement(name = "Fasted_Fed", element = data.frame(occ = c(1, 2), FOOD = c("Fasted", "Fed")))

  # Create an element with subject-specific occasions
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_external.smlx")
  loadProject(project_name)
  occasions <- getOccasionElements()
  covariates <- data.frame(id = occasions$id, occ = unlist(occasions$occasions), FOOD = rep(c("Fasted", "Fed", "Fasted"), 9))
  file_name <- tempfile("cov", fileext = ".csv")
  write.csv(covariates, file_name, row.names = FALSE)
  defineCovariateElement(name = "cov_external", element = file_name)