Skip to main content
Skip table of contents

defineRegressorElement

Define or edit a regressor element. Regressor elements are defined and used for simulation as in Simulx GUI. Once a regressor element is defined, it needs to be added to a simulation group with setGroupElement to be used in simulation. Regressor elements can be defined only if regressors are defined in the model loaded in the Simulx project.

Usage

R
defineRegressorElement(name, element)

Arguments

name

(character) Element name.

element

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

  • file (character) Path to the regressors file.

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

Details

To define a regressor element, in addition to the element name, you need to provide in the field data the time points and values of the regressor at each time point. To simulate the model for points outside of this grid, last value carried forward interpolation is used.

The field data can be specified with a data frame or an external file (csv, xlsx, xlsx, sas7bdat, xpt or txt). They should contain a column time and a column for each regressor variable. 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 regressor elements of type 'common', i.e the same for all individuals (potentially occasion-wise). If you want to define subject-specific regressor elements, you have to use an external file with an additional "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), time (mandatory) and one column per regressor defined in the model (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. In this case, regressors must be either common over all subjects and all occasions, or defined with subject-specific occasion-wise values as an external table, with the same occasion structure.

Note: It is not possible to define regressor elements with distributions with the connectors as in the GUI. To do this, please sample values from distributions in R and create the element with different rows as in the examples below.

Examples

R

if (FALSE) {
  defineRegressorElement(name = "name", element = "file/path")
  defineRegressorElement(name = "name", element = list(file = "file/path", sheet = "sheet_name"))
  defineRegressorElement(name = "name", element = data.frame(time = c(0, 0.5, 2), PCA = c(1, 2, 5.25)))
  }
  
  # Define subject-specific regressors using an external file (saved in tmp directory)
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.6.regressors", "regressor_manual_paramCovRelationship.smlx")
  loadProject(project_name)
  samplings <- data.frame(id = c(1, 1, 2, 2, 3, 3), time = c(0, 24, 0, 48, 0, 72), PCA = c(9, 15, 5, 20, 3, 14))
  file_name <- tempfile("cov", fileext = ".csv")
  write.csv(samplings, file_name, row.names = FALSE)
  defineRegressorElement(name = "reg_external", element = file_name)

  # Define manual regressor element
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.6.regressors", "regressor_manual_paramCovRelationship.smlx")
  loadProject(project_name)
  defineRegressorElement(name = "reg_manual", element = data.frame(time = c(0, 0.5, 2), PCA = c(1, 2, 5.25)))

  # Define manual occasion-wise regressors
  initializeLixoftConnectors("simulx")
  project_name <- file.path(getDemoPath(), "3.definition", "3.6.regressors", "regressor_manual_paramCovRelationship.smlx")
  loadProject(project_name)
  defineOccasionElement(element = data.frame(time = c(0, 0, 0, 0), occ1 = c(1, 2, 1, 2), occ2 = c(1, 1, 2, 2)))
  defineRegressorElement(name = "name", element = data.frame(time = c(0, 0.5, 2, 5, 6), PCA = c(1, 2, 5.25, 6, 7), occ1 = c(1, 1, 1, 2, 2), occ2 = c(1, 1, 2, 1, 2)))
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.