defineOutputElement

Usage

defineOutputElement(name, element)

Arguments

name

(character) Element name.

element

List with:

• data (character or dataFrame or list): data frame or path to external file (csv, xlsx, xlsx, sas7bdat, xpt or txt), or list to select the sheet of an excel file:

  • file (character) Path to the output file.

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

• output (character): name of any variable from the [LONGITUDINAL] block of the model (variable in EQUATION, smooth prediction listed under OUTPUT or noisy observation listed under DEFINITION).

Details

Output elements are defined and used for simulation as in Simulx GUI. As for other elements, the output elements can be defined or imported, and they are saved with the Simulx project if calling saveProject. Once an output element is defined, it needs to be added to a simulation group with setGroupElement to be used in simulation.

To define an output element, in addition to the element name, you need to provide the time grid for simulation and the output to simulate.

The field data can be specified with a data frame or an external file (csv, xlsx, xlsx, sas7bdat, xpt or txt).

To define a regular output, common to all individuals, you can use a data frame, with column headers start, interval and final. All time points from "start" to "final" by steps of "interval" will be used for simulation. If the project has a common occasion structure, this data frame can contain a column occasion and several lines to define the regular treatment occasion-wise.

To define an output by giving a specific list of times, both data frames and external files (csv, xlsx, xlsx, sas7bdat, xpt or txt) can be used, with a column time. They can contain columns occasions (optional). The occasion headers must correspond to the occasion names defined in the occasion element.

Data frames can be used only to define output elements of type 'common', i.e the same for all individuals (potentially occasion-wise). If you want to define subject-specific output elements, you have to 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 time (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. Output 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) {
  defineOutputElement(name = "name", element = list(data ="file/path"))
  defineOutputElement(name = "name", element = list(data = list(file = "file/path", sheet = "sheet_name")))
  defineOutputElement(name = "name", element = list(data = data.frame(time = 24), output = "AUC"))
  }
  
  # Define subject-specific outputs using an external file (saved in tmp directory)
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "5.simulation", "replicates.smlx")
  loadProject(project_name)
  samplings <- data.frame(id = c(1, 1, 2, 2, 3, 3), time = c(0, 24, 0, 48, 0, 72))
  file_name <- tempfile("cov", fileext = ".csv")
  write.csv(samplings, file_name, row.names = FALSE)
  defineOutputElement(name = "external_output", element = list(data = file_name, output = "Cc"))

  # Define manual and regular output
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")
  loadProject(project_name)
  defineOutputElement(name = "AUC_0_24", element = list(data = data.frame(time = 24), output = "AUC"))
  defineOutputElement(name = "Cc_7days", element = list(data = data.frame(start = 0, interval = 1, final = 168), output = "Cc"))

  # Define manual and regular occasion-wise output
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_two_levels.smlx")
  loadProject(project_name)
  defineOutputElement(name = "manualOcc", element = list(data = data.frame(time = c(0, 2, 24, 4, 36), occ1 = c(1, 1, 1, 2, 2), occ2 = c(1, 1, 2, 1, 2)),  output = "Y"))
  defineOutputElement(name = "regularOcc", element = list(data = data.frame(start = c(0, 0, 24, 24), interval = c(1, 2, 1, 2), final = c(24, 48, 48, 72), occ1 = c(1, 2, 1, 2), occ2 = c(1, 1, 2, 2)), output = "Cc"))