Simulx API

On the use of the R-functions

We now propose to use Simulx via R-functions. The package lixoftConnectors provides access to the project exactly in the same way as you would do with the interface. All the installation guidelines and initialization procedure can be found here. All the functions are described below.

• Installation guidelines and initialization procedure
• Page with typical examples
  • Load a project and run the simulation
  • Import a Monolix project and simulate a new output variable with the EBEs
  • Create a Simulx project from scratch and simulate covariate-dependent treatments
  • Import a Monolix project and simulate with new output times
  • Run a simulation with different sample sizes and plot the power of the study based on an endpoint
  • Handling of warning/error/info messages

Minimal examples based on demo projects are also included in the documentation of the functions below.

• List of the R functions
  • Description of the functions concerning the element definition
  • Description of the functions concerning the group comparison
  • Description of the functions concerning the initialization and path to demo projects
  • Description of the functions concerning the model extension
  • Description of the functions concerning the project management
  • Description of the functions concerning the project settings and preferences
  • Description of the functions concerning the results
  • Description of the functions concerning the scenario

List of the R functions

Description of the functions concerning the element definition

• defineCovariateElement: Define or edit a covariate element.
• defineEndpoint: Define or edit an endpoint.
• defineIndividualElement: Define or edit an element of individual parameters.
• defineOccasionElement: Define the occasion structure of the project.
• defineOutcome: Define or edit an outcome.
• defineOutputElement: Define or edit an output element.
• definePopulationElement: Define or edit an element of population parameters.
• defineRegressorElement: Define or edit a regressor element.
• defineTreatmentElement: Define or edit a treatment element.
• deleteElement: Delete an element of any type.
• deleteEndpoint: Delete an endpoint.
• deleteOccasionElement: Delete the occasion element.
• deleteOutcome: Delete an outcome.
• getCovariateElements: Get the list of all available covariate elements in the loaded project.
• getEndpoints: Get the list of all endpoints.
• getIndividualElements: Get the list of all available individual parameters elements for the simulation.
• getOccasionElements: Get the content of the occasion element that will be used for the simulation.
• getOutcomes: Get the list of all available outcomes.
• getOutputElements: Get the list of all available output elements for simulation.
• getPopulationElements: Get the list of all available population parameters elements for the simulation.
• getRegressorElements: Get the list of all available regressor elements for simulation.
• getRegressorsSettings: Get the regressors global settings.
• getTreatmentElements: Get the list of all available treatments elements for the simulation.
• setRegressorsSettings: Edit the regressors global settings.

Description of the functions concerning the group comparison

• getGroupComparisonSettings: Set settings related to the comparison of endpoints across groups.
• setGroupComparisonSettings: Set settings related to the comparison of endpoints across groups.

Description of the functions concerning the initialization and path to demo projects

• initializeLixoftConnectors: Initialize lixoftConnectors API for a given software.
• addIndividualBlock: Add an INDIVIDUAL block to a structural model.
• getDemoPath: Get the path to the demo projects.

Description of the functions concerning the model extension

• getAddLines: Get the lines that were added to a model with setAddLines (or in the GUI).
• setAddLines: Add equations to the structural model.

Description of the functions concerning the project management

• exportProject: Export the current project to another application of the MonolixSuite, and load the exported project.
• getLibraryModelContent: Get the content of a library model.
• getLibraryModelName: Get the name of a library model given a list of library filters.
• getStructuralModel: Get the model file for the structural model used in the current project.
• importProject: Import a Monolix or a PKanalix project into the currently running application initialized in the connectors.
• isProjectLoaded: Get a logical saying if a project is currently loaded.
• loadProject: Load a project in the currently running application initialized in the connectors.
• newProject: Create a new project.
• saveProject: Save the current project as a file that can be reloaded in the connectors or in the GUI.
• shareProject: Create a zip archive file from current project and its results.

Description of the functions concerning the project settings and preferences

• getConsoleMode: Get console mode, ie volume of output after running estimation tasks.
• getPreferences: Get a summary of the project preferences.
• getProjectSettings: Get a summary of the project settings.
• setConsoleMode: Set console mode, ie volume of output after running estimation tasks.
• setPreferences: Set the value of one or several of the project preferences.
• setProjectSettings: Set the value of one or several of the settings of the project.

Description of the functions concerning the results

• exportSimulatedData: Export the simulated dataset into a MonolixSuite compatible format.
• getEndpointsResults: Get the results of the outcomes & endpoints task.
• getSimulationResults: Get the results of the simulation.

Description of the functions concerning the scenario

• computeChartsData: Compute (if needed) and export the charts data of a given plot or, if not specified, all the available project plots.
• getScenario: Get the list of tasks that will be run at the next call to runScenario.
• runScenario: Run the scenario that has been set with setScenario.
• setScenario: Clear the current scenario and build a new one from a given list of tasks.
• addGroup: Add a new simulation group.
• getGroupRemaining: Get the values of the remaining parameters (typically the error model parameters) for a group.
• getGroups: Get the list of simulation groups and elements in each group.
• getNbReplicates: Get the number of replicates of the simulation.
• getSameIndividualsAmongGroups: Get the information if the same individuals are simulated among all groups.
• getSamplingMethod: Get which sampling method is used for the simulation.
• getSharedIds: Get the element types that will share the same individuals in the simulation.
• removeGroup: Remove a simulation group.
• removeGroupElement: Remove an element from a simulation group.
• renameGroup: Rename a simulation group.
• runEndpoints: Run the endpoints task.
• runSimulation: Run the simulation task.
• setGroupElement: Set the new element of a specific group.
• setGroupRemaining: Set the values of the remaining parameters (typically the error model parameters) for a group.
• setGroupSize: Define the size of a simulation group.
• setNbReplicates: Define the number of replicates of the simulation.
• setSameIndividualsAmongGroups: Define if the same individuals will be simulated among all groups.
• setSamplingMethod: Define which sampling method is used for the simulation.
• setSharedIds: Select the element types that will share the same individuals in the simulation.
• printOutcomesEndpoints: Get all the outcomes and endpoints defined in the Simulx project.
• printSimulationSetup: Get all the elements used in simulation setup: content of simulation groups and simulation settings.

[Simulx] Define covariate element

Description

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

Usage

defineCovariateElement(name, element)

Arguments

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

getCovariateElements

#

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

## End(Not run)

  # 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)

[Simulx] Define endpoint element

Description

Define or edit an endpoint. Endpoints summarize the outcome values over all individuals, for each simulation group and each replicate. Endpoints are defined as in Simulx GUI.

Usage

defineEndpoint(name, element)

Arguments

Details

To compute the defined endpoints, use runEndpoints and get the results with getEndpointsResults.

To specify if endpoints should be compared across simulation groups, use setGroupComparisonSettings. If group comparison is relevant, the way the comparison will be done for each endpoint (eg if statistical test and which p-value) should be defined in the endpoint element.

See Also

getEndpoints

#

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PKPD_changeFromBaseline.smlx")

loadProject(project_name)

defineEndpoint(name = "comparison", element = list(outcome = "changeFromBaseline", metric = "geometricMean", groupComparison = list(type = "statisticalTest", operator = "!=", threshold = "0", pvalue = 0.05)))

# Combine multiple outcomes

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

defineEndpoint(name = "combined_endpoint", element = list(outcome = list(names = c("Survival", "TimeToNADIR_AsEvent"), groupName = "combined", operator = "min")))

[Simulx] Define individual parameters element

Description

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

Usage

defineIndividualElement(name, element)

Arguments

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

getIndividualElements

#

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

## End(Not run)

  # 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)

[Simulx] Define occasion element

Description

Define the occasion structure of the project.

Usage

defineOccasionElement(element)

Arguments

Details

The occasion structure of a project is defined and used for simulation as in Simulx GUI.
The occasion element impacts the definition of other elements and the simulation. As for other elements, the occasion element can be defined or imported, and it is saved with the Simulx project if calling saveProject.

If can be defined as an external file (csv, xlsx, xlsx, sas7bdat, xpt or txt) or as a data.frame.

In any case, it should contain a column time and one column per occasion level. The header names for these occasion levels are free and used by Simulx.

A data frame can be used only to define a common structure of occasions applied to all simulated subjects.

An external file can be used in all cases (common or subject-specific structure). It can contain a column id (optional) in addition to other columns. When the id column is not present, the occasion structure is considered common.

After defining a subject-specific occasion structure, other elements (parameters, covariates, treatments, outputs and regressors) 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

getOccasionElements

#

defineOccasionElement(element = "file/path")

defineOccasionElement(element = list(file = "file/path", sheet = "sheet_name"))

defineOccasionElement(element = data.frame(time = c(0, 0.5, 2), occ1 = c(1, 1, 2), occ2 = c(1, 2, 3)))

## End(Not run)

  # Example: define subject-specific occasions through external file

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "5.simulation", "replicates.smlx")

  loadProject(project_name)

  occasions <- data.frame(id = c(1, 1, 2, 2), time = c(0, 24, 0, 36), occ = c(1, 2, 1, 2))

  file_name <- tempfile("cov", fileext = ".csv")

  write.csv(occasions, file_name, row.names = FALSE)

  defineOccasionElement(element = file_name)

  # Example: define common occasions through data.frame

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "5.simulation", "replicates.smlx")

  loadProject(project_name)

  defineOccasionElement(element = data.frame(time = c(0, 0.5, 2), occ1 = c(1, 1, 2), occ2 = c(1, 2, 3)))

[Simulx] Define outcome element

Description

Define or edit an outcome. Outcomes represent a post-processing of the simulation outputs done for each individual.
Outcomes are defined as in Simulx GUI.
Outcomes can only be defined by the user (no outcome is imported), and they are saved with the Simulx project if calling saveProject.
Contrary to the GUI, defining an outcome with the connectors does not automatically generate an endpoint.
To compute the defined outcomes, use them in endpoints with defineEndpoint, run runEndpoints and get the results with getEndpointsResults.

Usage

defineOutcome(name, element)

Arguments

See Also

getOutcomes

#

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PKPD_Cmax_targetInhibition.smlx")

loadProject(project_name)

defineOutcome(name = "Cmax_outcome", element = list(output = "Plasma_concentration", processing = list(operator = "max", type = "value")))

# Define time above MIC as percentage

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomesEndpoints_antibiotics_TaboveMIC.smlx")

loadProject(project_name)

defineOutcome(name = "TimeAboveMIC", element = list(output = "mlx_Cc", processing = list(operator = "durationAbove", type = "percentTime", value = 0.5)))

# Relative outcome with threshold per individual and occasion

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PKPD_LastPerOccasion.smlx")

loadProject(project_name)

defineOutcome(name = "custom_outcome", element = list(output = "prediction_Cc_per_id", perOccasion = TRUE, relativeTo = list(reference = "customValue", type = "difference", "value" = 2), processing = list(operator = "avg"), applyThreshold = list(operator = "<=", threshold = 2)))

# Event based outcome

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

defineOutcome(name = "survival_outcome", element = list(output = "Death", event = list(type = "timeOfEvents")))

[Simulx] Define output element

Description

Define or edit an output element.

Usage

defineOutputElement(name, element)

Arguments

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

getOutputElements

#

  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"))

## End(Not run)

  # 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"))

[Simulx] Define population element

Description

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

Usage

definePopulationElement(name, element)

Arguments

Details

Definition of population parameters as simulation elements allows to simulate individual parameters from probability distributions. It is possible only if the model includes a block [INDIVIDUAL] to consider the inter-individual variability.

A population 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 should contain one column per population parameter (mandatory).

To check exactly which column names to use, you can use getPopulationElements and view the population parameters element that was automatically created after defining the model (if the model has an [INDIVIDUAL] block).

To define a population parameters element with several lines, with several sets to be used in different replicate simulations, an external file is required. In this case, you should also set the number of replicates for your simulation with setNbReplicates, otherwise only the first set of population parameters will be taken into account. Each replicate uses one set of population parameters with the order of the appearance in the table.

Note: It is not possible to define population 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 last example below.

See Also

getPopulationElements, setNbReplicates

#

  definePopulationElement(name = "name", element = "file/path")

  definePopulationElement(name = "name", element = list(file = "file/path", sheet = "sheet_name"))

  definePopulationElement(name = "name", element = data.frame(Cl_pop = 1, V_pop = 2.5))

## End(Not run)

# Define a pop param element with a data frame 

  loadProject(file.path(getDemoPath(),"3.definition","3.3.population_parameters","pop_parameters_manual.smlx"))

  # get the existing pop param element as an example

  ExamplePopParamData = getPopulationElements()$manual_parameters$data

  ExamplePopParamData[] = rep(1,11) #set the desired values, for simplicity we use all param =1

  definePopulationElement(name = "PopParam", element = ExamplePopParamData)

# Check impact of varying ka with replicates (external file required)

  loadProject(file.path(getDemoPath(),"3.definition","3.3.population_parameters","pop_parameters_manual.smlx"))

  # get the existing pop param element as an example:

  ExamplePopParamData = getPopulationElements()$manual_parameters$data

  # add lines to the data frame to have different values for ka:

  PopParamReplicates = ExamplePopParamData[rep(1,10),]

  PopParamReplicates$ka_pop = rnorm(10,mean = 0.8, sd = 0.1)

  # write the table to an external file (required because it has several lines):

  file_name = tempfile("PopParamReplicates.csv")

  write.csv(PopParamReplicates, file_name, row.names = FALSE)

  # define the new element and use it in simulation:

  definePopulationElement(name = "PopParamReplicates", element = file_name)

  setGroupElement(group = "simulationGroup1", elements = "PopParamReplicates")

  setNbReplicates(nb = 10) # to simulate the project 10x, each time with a different population parameter element

  runSimulation()

 ## Not run: getSimulationResults()

[Simulx] Define regressor element

Description

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

defineRegressorElement(name, element)

Arguments

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.

See Also

getRegressorElements

#

## Not run: 

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

## End(Not run)

  # 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)))

[Simulx] Define treatment element

Description

Define or edit a treatment element.

Usage

defineTreatmentElement(name, element)

Arguments

Details

Treatment elements are defined and used for simulation as in Simulx GUI. As for other elements, the treatment elements can be defined or created at import, 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. Several treatment elements can be added to the same simulation group and they will be both administered to every individual in the group.

To define a treatment element, in addition to the element name, you need to provide a list with at list one field "data" containing the dose information. 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 treatment, common to all individuals, you can use a data frame, with column headers start, interval, nbDoses and amount. You can include an optional column tInf or rate to define an infusion. If the project has a common occasion structure (i.e. same occasions for all individuals), this data frame can contain a column occasion to define the regular treatment occasion-wise. The occasion headers must correspond to the occasion names defined in the occasion element.

To define a treatment by giving a specific list of times and amounts, both data frames and external files (csv, xlsx, xlsx, sas7bdat, xpt or txt) can be used, with a column time. They can contain columns id and 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 treatment 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) and one column amount (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.

Note

To define a regular schedule, it is advised to use a regular treatment without repeats, rather than a manual treatment with repeats. Repeats are useful to create more complex schedules in addition to a manual or regular definition, such as dosing regimen 3 weeks ON, 1 week OFF.

To see the impact of a treatment until the end of a dosing regimen, you should set an output element that spans the duration of the treatment to the same simulation group.

See Also

getTreatmentElements

#

  defineTreatmentElement(name = "name", element = list(data = "file/path"))

  defineTreatmentElement(name = "name", element = list(data = list(file = "file/path", sheet = "sheetname")))

  defineTreatmentElement(name = "name", element = list(probaMissDose=0, admID=1, repeats=c(cycleDuration = 1, NumberOfRepetitions=12), data=data.frame(time=c(1,2), amount=c(1,2), tInf=c(0, 1), washout=c(TRUE, FALSE))))

  defineTreatmentElement(name = "name", element = list(probaMissDose=0, admID=1, repeats=c(cycleDuration = 1, NumberOfRepetitions=12), data=data.frame(time=c(10,10,10,10), amount=c(10,20,30,40), occ1=c(1,1,2,2), occ2=c(1,2,1,2))))

  defineTreatmentElement(name = "name", element = list(probaMissDose=0, admID=1, repeats=c(cycleDuration = 1, NumberOfRepetitions=12), data=data.frame(start=1, interval=2, nbDoses=10, amount=1)))

  defineTreatmentElement(name = "name", element = list(admID=1, scale=list(covariate="age", intercept=12), data=data.frame(start=1, interval=2, nbDoses=10, amount=1)))

  defineTreatmentElement(name = "name", element = list(admID=1, scale=list(covariate="sex", modalities=list(list(name="0", factor=1, intercept=10), list(name="1", factor=1.5, intercept=10))), data=data.frame(start=1, interval=2, nbDoses=10, amount=1)))

## End(Not run) 

##### Working example with treatment combinations #####

# In this demo, the first group receives only the chemotherapy, while the second group receives both the chemotherapy and the anti-angiogenic therapy. 

# Note that the chemotherapy treatment uses adm=1 to be applied to compartment 1 via the macro iv(adm=1, cmt=1) in the model representing the concentration of the chemo drug. 

# The anti-angiogenic treatment is defined with adm=2 which is applied via the macro iv(adm=2, cmt=2) to compartment 2 representing the concentration of anti-angiogenic drug.

initializeLixoftConnectors("simulx")

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_combinations.smlx"))

# to see how the structural model is defined:

file.show(getStructuralModel())

defineTreatmentElement(name = "Chemotherapy", element = list(data=data.frame(start=10, interval=14, nbDoses=10, amount=1)))

defineTreatmentElement(name = "AntiAngionenic_treatment", element = list(admID = 2, data=data.frame(start=10, interval=7, nbDoses=20, amount=1)))

setGroupElement("simulationGroup1","Chemotherapy")

setGroupElement("simulationGroup2",c("Chemotherapy","AntiAngionenic_treatment"))

runSimulation()

# use ggplot or export to Monolix/PKanalix to plot trajectories 

exportProject(settings = list(targetSoftware = "monolix"),force = TRUE)

## Not run: 

plotObservedData( settings = list(dots = FALSE,  ylab = "Target Occupancy", legend = TRUE), stratify = list(colorGroup = list(name = "group")), preferences = list(obs = list(lineWidth = 0.5)))

## End(Not run)

##### Working example with a treatment scaled by weight and based on genotype #####

#  In this demo, a weight-based dose is defined by indicating the dose per unit weight in the amount box (14 nmol/kg) and using the "Scale amount by a covariate" option with "Weight" selected as covariate. 

# The "intercept" could be used to define a offset common to all weights (e.g 14nmol/kg + 10nmol). 

# When an infusion duration or rate has been defined, the user can choose if the infusion duration or the infusion rate is scaled by the covariate. 

# For categorical covariates, such as the genotype, a scaling factor and an intercept can be defined for each category. 

# In this demo, the scaling for Homozygous is 1 meaning that they receive the dose defined in the amount box. 

# For heterozygous, the scaling is 0.8, meaning that they receive 0.8 times the amount in the amount box. 

initializeLixoftConnectors("simulx")

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_weight_and_genotype_based.smlx"))

defineTreatmentElement(name = "14nmolPerKg", element = list(data=data.frame(start=0, interval=21, nbDoses=5, amount=14, tInf = 0.208), scale=list(covariate="Weight", intercept = 0, scaleDuration = FALSE)))

defineTreatmentElement(name = "1000nmol", element = list(data=data.frame(start=0, interval=21, nbDoses=5, amount=1000, tInf = 0.208)))

defineTreatmentElement(name = "1000nmolHomo_800nmolHetero", element = list(data=data.frame(start=0, interval=21, nbDoses=5, amount=1000, tInf = 0.208), scale=list(covariate="Genotype", modalities=list(list(name="Homozygous", factor=1, intercept=0), list(name="Heterozygous", factor=0.8, intercept=0)), scaleDuration = FALSE)))

setGroupElement("Weight_based","14nmolPerKg")

setGroupSize("Weight_based",20)

setGroupElement("Flat_dose","1000nmol")

setGroupSize("Flat_dose",20)

setGroupElement("Genotype_based","1000nmolHomo_800nmolHetero")

setGroupSize("Genotype_based",20)

runSimulation()

# use ggplot or export to Monolix/PKanalix to plot trajectories 

exportProject(settings = list(targetSoftware = "monolix"),force = TRUE)

plotObservedData(obsName = "yTO", settings = list(dots = FALSE,  ylab = "Target Occupancy"), stratify = list(splitGroup = list(name = "group")), preferences = list(obs = list(lineWidth = 0.5)))

##### Working example with a probability to miss a dose #####

# In this demo, the second treatment is defined with a probability to miss a dose of 0.1, meaning that on average 10% of the doses will not be taken. The missed doses are random.

initializeLixoftConnectors("simulx")

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_non_adherence.smlx"))

defineTreatmentElement(name = "OncePerDay_full_compliance", element = list(data=data.frame(start=0, interval=1, nbDoses=112, amount=100)))

defineTreatmentElement(name = "OncePerDay_partial_compliance", element = list(data=data.frame(start=0, interval=1, nbDoses=112, amount=100),probaMissDose = 0.1))

setGroupElement("simulationGroup1","OncePerDay_full_compliance")

renameGroup("simulationGroup1","FullCompliance")

setGroupElement("simulationGroup2","OncePerDay_partial_compliance")

renameGroup("simulationGroup2","NonAdherence")

setGroupSize("FullCompliance",20)

setGroupSize("NonAdherence",20)

runSimulation()

# use ggplot or export to Monolix/PKanalix to plot trajectories 

exportProject(settings = list(targetSoftware = "monolix"),force = TRUE)

plotObservedData( settings = list(dots = FALSE,  ylab = "Target Occupancy"), stratify = list(splitGroup = list(name = "group")), preferences = list(obs = list(lineWidth = 0.5)))

##### Working example with an external file #####

# Demo: use an external file to define a dose by age group: 1-2 years 12.5 mg, 3-6 years 18.75 mg and 7-15 years 25 mg. 

# The age also appears as covariate in the model and the covariate element is defined via an external file. 

# To make sure the covariates are sampled from the covariate external file and the doses sampled from the treatment external file are consistent (i.e correspond to the same id and thus the same age), the option "shared id" is selected between covariate and treatment elements.

initializeLixoftConnectors("simulx")

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_external_byAgeGroup.smlx"))

tableAge = getCovariateElements()$External_AGE_values$data

AmtByAgeGroups = (tableAge$AGE < 3)*12.5 + ((tableAge$AGE >=3) & (tableAge$AGE < 7))*18.75 + (tableAge$AGE >= 7)*25

Nid = length(AmtByAgeGroups)

dataAmtByAgeGroups = data.frame(id = tableAge$ID, time = rep(0,Nid), amount = AmtByAgeGroups)

file_name <- tempfile("trt", fileext = ".csv")

write.csv(dataAmtByAgeGroups, file_name, row.names = FALSE)

defineTreatmentElement(name = "doseByAgeGroup", element = list(data = file_name))

setGroupElement("simulationGroup1",c("doseByAgeGroup","External_AGE_values","regularCc"))

setSharedIds(c("covariate", "treatment"))

runSimulation()

# use ggplot or export to Monolix/PKanalix to plot trajectories 

exportProject(settings = list(targetSoftware = "monolix"),force = TRUE)

plotObservedData(settings = list(dots = FALSE, ylab = "Cc",legend = TRUE, ylim = c(0,13)), stratify = list(splitGroup = list(name = "AGE", breaks = c(2,7)), colorGroup = list(name = "ID")), preferences = list(obs = list(lineWidth = 0.5)))

##### Working example with washout #####

# In this demo, two different formulations are given. 

# The reference formulation is given at time zero. 

# The test formulation is given after a long washout period. 

# In order not to simulate this washout period, the test dose is defined at time 48 and a washout is applied just before the test dose to reset the model to its initial state. 

initializeLixoftConnectors("simulx")

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_washout.smlx"))

defineTreatmentElement(name = "ReferenceFormulation_atTime0", element = list(data=data.frame(time=0, amount=600)))

defineTreatmentElement(name = "TestFormulation_atTime48", element = list(admID = 2, data=data.frame(time=0, amount=600, washout = TRUE)))    

setGroupElement("simulationGroup1",c("ReferenceFormulation_atTime0","ReferenceFormulation_atTime0"))

##### Working example with a regular treatment and repeats #####

# The "repeat" option allows to repeat a base pattern several times with a defined periodicity. 

# In this demo, the first treatment is defined as one dose per day during 112 days. 

# The second treatment is defined as one dose per day during 14 days and this is repeated every 28 days leading to a 2 weeks on / 2 weeks off pattern.

initializeLixoftConnectors("simulx")

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_regular_cycles.smlx"))

defineTreatmentElement(name = "OncePerDay_4weeksOn", element = list(data=data.frame(start=0, interval=1, nbDoses=112, amount=100)))

defineTreatmentElement(name = "OncePerDay_2weeksOn2weeksOff", element = list(repeats=c(cycleDuration = 28, NumberOfRepetitions=4), data=data.frame(start=0, interval=1, nbDoses=14, amount=100)))

setGroupElement("simulationGroup1","OncePerDay_4weeksOn")

renameGroup("simulationGroup1","4weeksOn")

setGroupElement("simulationGroup2","OncePerDay_2weeksOn2weeksOff")

renameGroup("simulationGroup2","2weeksOn2weeksOff")

runSimulation()

# use ggplot or export to Monolix/PKanalix to plot trajectories 

exportProject(settings = list(targetSoftware = "monolix"),force = TRUE)

plotObservedData(settings = list(dots = FALSE, ylab = "Cc",legend = TRUE), stratify = list(color = list(name = "group")), preferences = list(obs = list(lineWidth = 0.5)))

[Simulx] Delete element

Description

Delete an element of any type.

Usage

deleteElement(name)

Arguments

Details

Elements defined are created in the background and saved with the Simulx project if calling saveProject.

To check which elements of a certain type have been defined so far, please use one of the "get..Elements" connectors: getCovariateElements, getPopulationElements, getIndividualElements, getTreatmentElements, getOccasionElements, getRegressorElements.

Elements cannot be deleted if they are used for the simulation. To remove an element from the simulation, use removeGroupElement.

#

  project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")

  loadProject(project_name)

  deleteElement(name = "mlx_CovDist")

[Simulx] Delete an endpoint

Description

Delete an endpoint.

Usage

deleteEndpoint(name)

Arguments

Details

Endopints defined are created in the background and saved with the Simulx project if calling saveProject.

To check which endpoints have been defined, please use getEndpoints.

See Also

deleteOutcome

#

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

deleteEndpoint("mean_NADIR")

[Simulx] Delete occasion element

Description

Delete the occasion element.

Usage

deleteOccasionElement()

Details

The occasion element impacts the definition of other elements and the simulation. As for other elements, the occasion element can be defined or imported, and it is saved with the Simulx project if calling saveProject.
To check if an occasion element has been defined, please use getOccasionElements.
The occasion element may impact the definition of other elements. When deleting the occasion element, all other elements that depend on occasions are also deleted.

#

  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_common.smlx")

  loadProject(project_name)

  deleteOccasionElement()

[Simulx] Delete an outcome

Description

Delete an outcome.

Usage

deleteOutcome(name)

Arguments

Details

Outcomes defined are created in the background and saved with the Simulx project if calling saveProject.

To check which outcomes have been defined, please use getOutcomes.

An outcome used in an endpoint cannot be deleted. The related endpoint must be deleted first with deleteEndpoint.

See Also

deleteEndpoint

#

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

deleteEndpoint("mean_NADIR")

deleteOutcome("NADIR")

[Simulx] Get covariate elements

Description

Get the list of all available covariate elements in the loaded project.
To use one of these elements in simulation, please add it to a simulation group with setGroupElement.

Usage

getCovariateElements()

Details

Covariate elements can be defined with defineCovariateElement, or created by importing a Monolix project with importProject. Elements defined are created in the background and saved with the Simulx project if calling saveProject. They can be deleted with deleteElement.

Each element is a list of

Note that:
– if the project was created from a model file, a covariate element Covariates is created with all values equal 1.
– if the project was created by importing a Monolix project,

• a covariate element mlx_Cov is created with the values corresponding to the covariates values from the dataset of the Monolix project.

• a covariate element mlx_CovDist is created with the values corresponding to the estimation of the distribution of covariates in the dataset of the Monolix project.

The "distribution" type of covariate elements can only be created in the GUI. The "manual" type corresponds to elements created manually in the GUI, or with a data frame in connectors. The external type corresponds to elements created from an external file in the GUI or with the connectors.

See Also

defineCovariateElement

#

getCovariateElements()

$mlx_Cov

#'$mlx_Cov$inputType

[1] "external"

$mlx_Cov$file

[1] path/to/file

$mlx_Cov$data

   id WEIGHT

1   1   79.6

2   2   72.4

3   3   70.5

4   4   72.7

5   5   54.6

...

$covMan

$covMan$inputType

[1] "manual"

$covMan$file

NULL

$covMan$data

      id WEIGHT

1 common      75

## End(Not run)

# Get covariate elements in projects in which they were defined differently

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "3.definition", "3.2.covariates", "covariates_distribution.smlx")

loadProject(project_name)

getCovariateElements()

project_name <- file.path(getDemoPath(), "3.definition", "3.2.covariates", "covariates_external.smlx")

loadProject(project_name)

getCovariateElements()

project_name <- file.path(getDemoPath(), "3.definition", "3.2.covariates", "covariates_manual.smlx")

loadProject(project_name)

getCovariateElements()

[Simulx] Get endpoint elements

Description

Get the list of all endpoints.

Usage

getEndpoints()

Details

Endpoints summarize the outcome values over all individuals, for each simulation group and each replicate. Endpoints are defined and calculated as in Simulx GUI.

To compute the defined endpoints, use runEndpoints and get the results with getEndpointsResults.

To check if endpoints will be compared across simulation groups, use getGroupComparisonSettings. If group comparison is relevant, the way the comparison will be done for each endpoint (eg if statistical test and which p-value) should be defined in the endpoint element.

Each element is a list of

• outcome (character or list) – Outcome on which the endpoint is based on. If one outcome, a string containing its name. If combined outcomes were used, a list with:

  • names (vector of character) – Vector of outcome names

  • groupName (character) – Name of the outcome combination

  • operator (character) – Way in which output should be combined. One of "and"/"or" (in case of boolean outcomes) or "min"/"max" (in other cases)

• metric (character) – Calculation method for the endpoint. One of "arithmeticMean", "geometricMean" or "median" if value-based outcome. In case of event-based outcomes, "kaplanMeier" (median survival) and in case of boolean outcomes, "percentTrue".

• groupComparison (list) – Group comparison settings containing:

  • type (character) – One of "directComparison", "statisticalTest"

  • operator (character) – One of "!=", ">" or "<",

  • threshold (double) – A real number indicating the threshold for difference/oddsRatio

  • pvalue (double) – A real number indicating the p-value (if type is "statisticalTest")

See Also

defineEndpoint

#

## Not run: 

$median_average

$median_average$outcome

[1] "regularCc_average_id"

$median_average$metric

[1] "arithmeticMean"

$median_average$groupComparison

$median_average$groupComparison$type

[1] "statisticalTest"

$median_average$groupComparison$operator

[1] ">"

$median_average$groupComparison$threshold

[1] 0

$median_average$groupComparison$pvalue

[1] 0.05

$regular_between_003_005

$regular_between_003_005$metric

[1] "percentTrue"

$regular_between_003_005$outcome

$regular_between_003_005$outcome$groupName

[1] "regular_between_003_005_outcome"

$regular_between_003_005$outcome$names

[1] "regularCc_avg_idOcc_lower06"   "regularCc_avg_idOcc_greater03"

$regular_between_003_005$outcome$operator

[1] "and"

...

## End(Not run)

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

getEndpoints()

}

[Simulx] Get individual parameters elements

Description

Get the list of all available individual parameters elements for the simulation. To use one of these elements in simulation, please add it to a simulation group with setGroupElement.

Usage

getIndividualElements()

Details

Individual parameters elements can be defined with defineIndividualElement, or created by importing a Monolix or PKanalix project. Elements defined are created in the background and saved with the Simulx project if calling saveProject. They can be deleted with deleteElement.

Each element is a list of

If the Simulx project was created from a model file, an individual element IndivParameters is created with all values equal 1.

If the Simulx project was created by importing or exporting a Monolix project, the following individual elements are created:

• mlx_IndivInit is created with a vector of initial population parameters if the population parameters were not estimated.

• mlx_PopIndiv is created with a vector of estimated population parameters (without the covariate(s) impact(s)) if the population parameters were estimated.

• mlx_PopIndivCov is created with a table of estimated population parameters with covariate impact if the population parameters were estimated.

• mlx_EBEs is created with a table of estimated EBEs if the EBEs were estimated.

• mlx_CondMean is created with a table of estimated conditional mean for each individual if the conditional distribution task was run.

• mlx_CondDistSample is created with a table including the first sample from the conditional distribution for each individual if the conditional distribution task was run.

If the Simulx project was created by importing or exporting a PKanalix project, the following individual elements are created:

• an individual element pkx_IndivInit is created with a vector of initial parameters if the CA task has not run.

• an individual element pkx_Indiv is created with a table of individual parameters estimated in PKanalix if the CA task has run with the method "individual fit".

• an individual element pkx_IndivPooled is created with a vector of parameters estimated in PKanalix if the CA task has run with the method "pooled fit".

• an individual element pkx_IndivGeoMean is created with a vector of individual parameters corresponding to the geometric mean of individual parameters estimated in PKanalix if the CA task has run with the method "individual fit".

See Also

defineIndividualElement

#

getIndividualElements()

$mlx_PopIndiv

$mlx_PopIndiv$inputType

[1] "manual"

$mlx_PopIndiv$file

NULL

$mlx_PopIndiv$data

      id       Cl       V1        Q2       V2      Q3       V3

1 common 2.462069 4.557752 0.1151846 4.355022 1.70242 8.229753

$mlx_EBEs

$mlx_EBEs$inputType

[1] "external"

$mlx_EBEs$file

[1] file/to/path

$mlx_EBEs$data

   id       Cl       V1         Q2        V2        Q3        V3

1   1 2.870556 5.801418 2.12758339  5.963084 0.6649303 13.069996

2   2 2.899189 4.443222 0.31646327  5.226719 2.3678264  9.182623

...

## End(Not run)

# Get individual elements in projects in which they were defined differently

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "3.definition", "3.4.individual_parameters", "indivparam_external.smlx")

loadProject(project_name)

getIndividualElements()

project_name <- file.path(getDemoPath(), "3.definition", "3.4.individual_parameters", "indivparam_manual.smlx")

loadProject(project_name)

getIndividualElements()

[Simulx] Get occasion elements

Description

Get the content of the occasion element that will be used for the simulation. The element will be automatically used for simulation and does not need to be added to a simulation group.

Usage

getOccasionElements()

Details

The occasion element can be defined with defineOccasionElement, or created during the import of a Monolix or PKanalix project with importProject. It can be deleted with deleteOccasionElement.

The element is a list of

The structure of the occasion elements impacts the definition of all other elements in the Simulx project. If the occasion element is subject-specific, other elements (parameters, covariates, treatments, outputs and regressors) must be either common over all subjects and all occasions, or they must be defined with subject-specific occasion-wise values as an external table (with id and occ columns), with the same occasion structure.

See Also

defineOccasionElement

#

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_common.smlx")

  loadProject(project_name)

  getOccasionElements()

  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_common_washout.smlx")

  loadProject(project_name)

  getOccasionElements()

  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_external.smlx")

  loadProject(project_name)

  getOccasionElements()

  project_name <- file.path(getDemoPath(), "3.definition", "3.7.occasions", "occasions_two_levels.smlx")

  loadProject(project_name)

  getOccasionElements()

[Simulx] Get outcome elements

Description

Get the list of all available outcomes.
The function returns a list containing the following elements:

Then, if the outcome is based on a continuous or categorical output:

Or if the outcome is based on a TTE output:

Usage

getOutcomes()

See Also

defineOutcome

#

## Not run: 

$outcome_per_id

$outcome_per_id$perOccasion

[1] FALSE

$outcome_per_id$output

[1] "regularCc"

$outcome_per_id$processing

$outcome_per_id$processing$operator

[1] "avg"

$hemorrhaging_id_timeOf_2nd

$hemorrhaging_id_timeOf_2nd$perOccasion

[1] FALSE

$hemorrhaging_id_timeOf_2nd$output

[1] "Hemorrhaging_until_150"

$hemorrhaging_id_timeOf_2nd$event

$hemorrhaging_id_timeOf_2nd$event$type

[1] "timeOfEvents"

$hemorrhaging_id_timeOf_2nd$event$rank

[1] 2

...

## End(Not run)

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

getOutcomes()

}

[Simulx] Get output elements

Description

Get the list of all available output elements for simulation.

Usage

getOutputElements()

Details

Output elements can be defined with defineOutputElement, or created by importing a Monolix or a PKanalix project. Elements defined are created in the background and saved with the Simulx project if calling saveProject. They can be deleted with deleteElement.

Each element is a list of

Importantly, all the variables in the model file can be used as an output. The user is not constrained to the ones defined in the OUTPUT section of the model.

If the project was created from a model file, an output element is created for each output of the section OUTPUT of the model, with regular grid from 0 to 100 by steps of 1.

If the project was created by importing a Monolix project, with for example Cc as a prediction and y as measurement,

• an output element mlx_y1 is created as an external file with the times of the output for each id in the original dataset of the Monolix project.

• an output element mlx_Cc is created with a regular grid starting from the first time to the final time measured in the original dataset.

If the project was created by importing a PKanalix project, with for example Cc as a prediction,
#’

• an output element pkx_Cc_OriginalTimes is created as an external file with the times of the output for each id in the original dataset of the Monolix project.

• an output element pkx_Cc_FineGrid is created with a regular grid starting from the first time to the final time measured in the original dataset.

See Also

defineOutputElement

#

$output

[1] "y1"

$inputType

[1] "manual"

$file

NULL

$data

        id time

1   common    0

2   common    1

3   common    2

...

## End(Not run)

  # Get output elements in projects in which they were defined differently

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "3.definition", "3.5.outputs", "output_addLines.smlx")

  loadProject(project_name)

  getOutputElements()

  project_name <- file.path(getDemoPath(), "3.definition", "3.5.outputs", "output_intermOutputs.smlx")

  loadProject(project_name)

  getOutputElements()

  project_name <- file.path(getDemoPath(), "3.definition", "3.5.outputs", "output_mainOutputs.smlx")

  loadProject(project_name)

  getOutputElements()

[Simulx] Get population parameters elements

Description

Get the list of all available population parameters elements for the simulation. To use one of these elements in simulation, please add it to a simulation group with setGroupElement.

Usage

getPopulationElements()

Details

Population parameters elements can be defined with definePopulationElement, or created at the import of a Monolix project with importProject. Elements defined are created in the background and saved with the Simulx project if calling saveProject. They can be deleted with deleteElement.

Each element is a list of

Notice that:
– if the project was created from a model file, a population element PopParameters is created with all values equal 1.
– if the project was created using by importing a Monolix project (with importProject),

• a population element mlx_Pop is created with the population parameters estimated in the Monolix project.

• if the parameters were not estimated in the Monolix project, a population element mlx_PopInit is created instead of mlx_Pop, with the initial values of the population parameters.

• a population element mlx_PopUncertainSA (resp. mlx_PopUncertainLin) is created which enables to sample population parameters using the covariance matrix of the estimates computed by Monolix if the Standard Error task (Estimation of the Fisher Information matrix) was performed by stochastic approximation (resp. by linearization). To sample several population parameter sets, this element needs to be used with replicates (usesetNbReplicates.

• a population element mlx_Typical is created with the population parameters estimated in the Monolix projects and all omega parameters set to zero. It is useful to simulate a typical individual with different covariate values than the reference in the model.

• a population element mlx_TypicalUncertainSA (resp. mlx_TypicalUncertainLin) is created which is the same as mlx_PopUncertain but with all omegas set to zero to remove the inter-individual variability. It is useful to propagate the uncertainty of population parameters to the prediction of a typical individual.

See Also

definePopulationElement

#

getPopulationElements()

$mlx_Pop

$mlx_Pop$inputType

[1] "manual"

$mlx_Pop$file

NULL

$mlx_Pop$data

      id   Cl_pop   V1_pop    Q2_pop   V2_pop  Q3_pop   V3_pop  omega_Cl omega_Q2  omega_Q3  omega_V1  omega_V2  omega_V3         b

1 common 2.462069 4.557752 0.1151846 4.355022 1.70242 8.229753 0.2272315  0.92641 0.5745623 0.4080015 0.8127517 0.4464604 0.1106325

#' 

## End(Not run)

# Get population elements in projects in which they were defined differently

initializeLixoftConnectors("simulx")

project_name <-

  file.path(

    getDemoPath(),

    "3.definition",

    "3.3.population_parameters",

    "pop_parameters_distribution.smlx"

  )

loadProject(project_name)

getPopulationElements()

project_name <-

  file.path(

    getDemoPath(),

    "3.definition",

    "3.3.population_parameters",

    "pop_parameters_external.smlx"

  )

loadProject(project_name)

getPopulationElements()

project_name <-

  file.path(

    getDemoPath(),

    "3.definition",

    "3.3.population_parameters",

    "pop_parameters_manual.smlx"

  )

loadProject(project_name)

getPopulationElements()

[Simulx] Get regressor elements

Description

Get the list of all available regressor elements for simulation. To use one of these elements in simulation, please add it to a simulation group with setGroupElement. To simulate the model for times outside of the specified grid, last value carried forward interpolation is used.

Usage

getRegressorElements()

Details

Regressor elements can be defined with defineRegressorElement, or created by importing a Monolix or a PKanalix project with importProject. Elements defined are created in the background and saved with the Simulx project if calling saveProject. They can be deleted with deleteElement.

Each element is a list of

Note that:

• if the project was created from a model file with regressors, a regressor element Regressors is created with one time point at 0 and all regressors equal 1.

• if the project was created by importing a Monolix or a PKanalix project with regressors, a regressor element mlx_Reg is created based on an external file with ids, times and regressor values and names read from the dataset of the Monolix project.

See Also

defineRegressorElement

#

$inputType

[1] "manual"

$file

NULL

$data

        id time

1   common    0

2   common    1

3   common    2

...

## End(Not run)

  # Get regressor elements in projects in which they were defined differently

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "3.definition", "3.6.regressors", "regressor_external_PKPD.smlx")

  loadProject(project_name)

  getRegressorElements()

  project_name <- file.path(getDemoPath(), "3.definition", "3.6.regressors", "regressor_manual_paramCovRelationship.smlx")

  loadProject(project_name)

  getRegressorElements()

[Simulx] Get regressors settings

Description

Get the regressors global settings.

• interpolation method: either "lastCarriedForward" or "linearInterpolation".

Usage

getRegressorsSettings()

[Simulx] Get treatment elements

Description

Get the list of all available treatments elements for the simulation. To use one or several of these elements in simulation, please add it to a simulation group with setGroupElement.

Usage

getTreatmentElements()

Details

Treatment elements can be defined with defineTreatmentElement, or created by importing a Monolix or a PKanalix project with importProject. Elements defined are created in the background and saved with the Simulx project if calling saveProject. They can be deleted with deleteElement.

Each element is a list of

If the project was created from a model file, no treatment element is added.

If the project was created by importing a Monolix or a PKanalix project, for each administration type present in the original project (dataset column tagged as administration id), an individual element mlx_adm is created as an external file with the dosing times and amounts from the original dataset in the Monolix or PKanalix project.

See Also

defineTreatmentElement

#

initializeLixoftConnectors("simulx", force = TRUE)

loadProject(paste0(getDemoPath(), "/3.definition/3.1.treatments/treatment_weight_and_genotype_based.smlx"))

getTreatmentElements()

## Not run: 

$`14nmolPerKg`

$`14nmolPerKg`$inputType

[1] "manual"

$`14nmolPerKg`$file

NULL

$`14nmolPerKg`$admID

[1] 1

$`14nmolPerKg`$scale

$`14nmolPerKg`$scale$covariate

[1] "Weight"

$`14nmolPerKg`$scale$intercept

[1] 0

$`14nmolPerKg`$scale$scaleDuration

[1] FALSE

$`14nmolPerKg`$data

time amount  tInf washout

1    0     14 0.208   FALSE

2   21     14 0.208   FALSE

3   42     14 0.208   FALSE

4   63     14 0.208   FALSE

5   84     14 0.208   FALSE

## End(Not run)

[Simulx] Edit regressors settings

Description

Edit the regressors global settings.

Usage

setRegressorsSettings(method)

Arguments

[Simulx] Get group comparison settings

Description

Set settings related to the comparison of endpoints across groups.

Usage

getGroupComparisonSettings()

Details

Endpoints summarize the outcome values over all individuals, for each simulation group and each replicate. Endpoints are defined with defineEndpoint and can be compared across groups as in Simulx GUI.

getGroupComparisonSettings enables to check if endpoints will be compared across simulation groups and which group will be used as a reference. Group comparison is performed during the Endpoints task.

See Also

setGroupComparisonSettings

#

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.2.group_comparison", "groupComp_PDTTE_medianSurvival.smlx")

loadProject(project_name)

getGroupComparisonSettings()

[Simulx] Set group comparison settings

Description

Set settings related to the comparison of endpoints across groups.

Usage

setGroupComparisonSettings(referenceGroup = NULL, enable = TRUE)

Arguments

Details

Endpoints summarize the outcome values over all individuals, for each simulation group and each replicate. Endpoints are defined with defineEndpoint and can be compared across groups as in Simulx GUI.

setGroupComparisonSettings enables to specify if endpoints should be compared across simulation groups and which group to use as a reference. Group comparison is performed during the Endpoints task.

See Also

getGroupComparisonSettings

#

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.2.group_comparison", "groupComp_PKPD_medianInhibition_percentEfficacy.smlx")

loadProject(project_name)

# Change the reference group

setGroupComparisonSettings(referenceGroup = "OD_300mgPerDay_", enable = TRUE)

# Turn off group comparison

setGroupComparisonSettings(enable = FALSE)

[Monolix – PKanalix – Simulx] Initialize lixoftConnectors API

Description

Initialize lixoftConnectors API for a given software.

Usage

initializeLixoftConnectors(software = "monolix", path = "", force = FALSE)

Arguments

Value

A logical equaling TRUE if the initialization has been successful and FALSE if not.

#

initializeLixoftConnectors(software = "monolix", path = "/path/to/lixoftRuntime/")

## End(Not run)

[Simulx] Add an INDIVIDUAL block to a structural model

Description

Add an INDIVIDUAL block to a structural model.
The structural model can be either a txt file or a library model, and the resulting model is written to another a file.

Usage

addIndividualBlock(sourceModelFile, targetModelFile, force = FALSE)

Arguments

Details

Adding an INDIVIDUAL block enables to add inter-individual variability to all parameters of a structural model.
For every parameter theta available in the structural model file, population parameters theta_pop (typical value) and omega_theta (standard deviation of random effects) are added to the model, and lognormal distributions are used by default.
If the structural model is a library model, the distributions are set to normal, lognormal or logitnormal depending on the meaning of the parameter.

The resulting file can then be used as a starting point to remove IIV from some parameters, change parameter distributions, or add correlations if needed, and the final model can then be used to create a new Simulx project with newProject.

More details on the syntax of the INDIVIDUAL block can be found here.

#

   addIndividualBlock("lib:bolus_1cpt_VCl.txt", "example_output_bolus_1cpt_VCl_with_individual_block.txt")

## End(Not run)

# Working example: create project from a library model with IIV on all parameters. 

  targetModelFile = tempfile("example_output_bolus_1cpt_VCl_with_individual_block",fileext = ".txt")

  addIndividualBlock("lib:bolus_1cpt_VCl.txt", targetModelFile) # we add an IIV block to a library model which has parameters V and Cl.

  file.show(targetModelFile) # to look at the created file with a text editor

  newProject(targetModelFile) # create a new Simulx project with this model

  getPopulationElements() # a population parameters element was automatically created with V_pop, omega_V, Cl_pop, omega_Cl.

[Monolix – PKanalix – Simulx] Get Lixoft demos path

Description

Get the path to the demo projects. The path depends on the software used to initialize the connectors with initializeLixoftConnectors.

Usage

getDemoPath()

Value

The Lixoft demos path corresponding to the currently active software.

#

  getDemoPath()

## End(Not run)

[Simulx] Get lines added to the model.

Description

Get the lines that were added to a model with setAddLines (or in the GUI).

Usage

getAddLines()

Details

Additional equations can be added to the model file as in Simulx GUI.
It is useful in case of import from Monolix or PKanalix, in order to add equations to the model, eg to compute an additional variable, without modifying the model file used for estimation and without impacting elements already defined.

See Also

setAddLines

#

  file_name <- file.path(getDemoPath(), "3.definition", "3.5.outputs", "output_addLines.smlx")

  loadProject(file_name)

  getAddLines()

[Simulx] Add lines to the model.

Description

Add equations to the structural model.

Usage

setAddLines(lines)

Arguments

Details

Additional equations can be added to the model file as in Simulx GUI.
It is useful in case of import from Monolix or PKanalix, in order to add equations to the model, eg to compute an additional variable, without modifying the model file used for estimation.

All variables defined in the add lines will be available as an output.

See Also

getAddLines

#

  initializeLixoftConnectors("monolix")

  monolix_project <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "theophylline_project.mlxtran")

  initializeLixoftConnectors("simulx")

  importProject(monolix_project)

  setAddLines("ddt_AUC = Cc")

  # Calculate partial AUC

  initializeLixoftConnectors("monolix")

  monolix_project <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

  initializeLixoftConnectors("simulx")

  importProject(monolix_project)

  setAddLines(c("if t<24", "deriv = Cc", "else", "deriv = 0", "end", "ddt_AUC = deriv"))

[Monolix – PKanalix – Simulx] Export current project to Monolix, PKanalix or Simulx

Description

Export the current project to another application of the MonolixSuite, and load the exported project.
NOTE: This action switches the current session to the target software. Current unsaved modifications will be lost.
The extensions are .mlxtran for Monolix, .pkx for PKanalix, .smlx for Simulx and .dxp for Datxplore.
WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.

Usage

exportProject(settings, force = F)

Arguments

Details

At export, a new project is created in a temporary folder. By default, the file is created with a project setting filesNextToProject = TRUE, which means that file dependencies such as data and model files are copied and kept next to the new project (or in the result folder for Simulx). This new project can be saved to the desired location withsaveProject.

Exporting a Monolix or a PKanalix project to Simulx automatically creates elements that can be used for simulation, exactly as in the GUI.

To see which elements of some type have been created in the new project, you can use the get..Element functions: getOccasionElements, getPopulationElements, getPopulationElements, getIndividualElements, getCovariateElements, getTreatmentElements, getOutputElements, getRegressorElements.

See Also

newProject, loadProject, importProject

#

[PKanalix only]

exportProject(settings = list(targetSoftware = "monolix", filesNextToProject = F))

exportProject(settings = list(targetSoftware = "monolix", filesNextToProject = F, exportedUnusedCovariates = list(all = FALSE, name = c("sex", "weight"))))

[Monolix only]

exportProject(settings = list(targetSoftware = "simulx", filesNextToProject = T, dataFilePath = "data.txt", dataFileType = "vpc"))

exportProject(settings = list(targetSoftware = "simulx", filesNextToProject = F, dataFilePath = "/path/to/data/data.txt"))

[Simulx only]

exportProject(settings = list(targetSoftware = "pkanalix", dataFilePath = "data.txt", modelFileName = "model.txt"))

exportProject(settings = list(targetSoftware = "pkanalix", dataFilePath = "/path/to/data/data.txt"))

## End(Not run)

# Working example to export a Monolix project to Simulx. The resulting .smlx file can be opened from Simulx GUI.

initializeLixoftConnectors(software = "monolix", force = TRUE)

loadProject(file.path(getDemoPath(),"1.creating_and_using_models","1.1.libraries_of_models","warfarinPK_project.mlxtran"))

runScenario()

exportProject(settings = list(targetSoftware = "simulx"), force = TRUE)

saveProject("importFromMonolix.smlx")

[Monolix – PKanalix – Simulx] Get a library model’s content.

Description

Get the content of a library model.

Usage

getLibraryModelContent(filename, print = TRUE)

Arguments

Value

The model’s content as a single string.

#

getLibraryModelContent("oral1_1cpt_kaVCl")

model <- getLibraryModelContent(filename = "lib:oral1_1cpt_kaVCl.txt", print = FALSE)

## End(Not run)

[Monolix – PKanalix – Simulx] Get the name of a library model given a list of library filters.

Description

Get the name of a library model given a list of library filters.

Usage

getLibraryModelName(library, filters = list())

Arguments

Details

Models can be loaded from a library based on a selection of filters as in PKanalix, Monolix and Simulx GUI. For a complete description of each model library, and guidelines on how to select models, please visit https://mlxtran.lixoft.com/model-libraries/.

getLibraryModelName enables to get the name of the model to be loaded. You can then use it in setStructuralModel or newProject to load the model in an existing or in a new project.

All possible keys and values for each of the libraries are listed below.

PK library

PD library

PKPD library

PK double absorption library

Parent-metabolite library

TMDD library

TTE library

Count library

TGI library

Value

Name of the filtered model, or vector of names of the available models if not all filters were selected. Names start with "lib:".

#

getLibraryModelName(library = "pk", filters = list(administration = "oral", delay = "lagTime", absorption = "firstOrder", distribution = "1compartment", elimination = "linear", parametrization = "clearance"))

# returns "lib:oral1_1cpt_TlagkaVCl.txt"

getLibraryModelName("pd", list(response = "turnover", drugAction = "productionStimulation"))

# returns c("lib:turn_input_Emax.txt", "lib:turn_input_gammaEmax.txt")

## End(Not run)

[Monolix – PKanalix – Simulx] Get structural model file

Description

Get the model file for the structural model used in the current project.

Usage

getStructuralModel()

Details

For Simulx, this function will return the path to the structural model only if the project was imported from Monolix, and the path to the full custom model otherwise.
Note that a custom model in Simulx may include also a statistical part.
For Simulx, there is no associated function getStructuralModel() because setting a new model is equivalent to creating a new project. Use newProject instead.

If a model was loaded from the libraries, the returned character is not a path,
but the name of the library model, such as "lib:model_name.txt". To see the content of a library model, use getLibraryModelContent.

Value

The path to the structural model file.

See Also

For Monolix and PKanalix only: setStructuralModel

#

getStructuralModel() => "/path/to/model/inclusion/modelFile.txt"

## End(Not run)

# Get the name and see the content of the model used in warfarin demo project

initializeLixoftConnectors("monolix", force = TRUE)

loadProject(file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran"))

libModelName <- getStructuralModel()

getLibraryModelContent(libModelName)

# Get the name of the model file used in Simulx

initializeLixoftConnectors("simulx", force = TRUE)

project_name <- file.path(getDemoPath(), "1.overview", "newProject_TMDDmodel.smlx")

loadProject(project_name)

getStructuralModel()

# Get the name of the model file imported to Simulx

initializeLixoftConnectors("monolix", force = TRUE)

project_name <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

loadProject(project_name)

getStructuralModel()

initializeLixoftConnectors("simulx", force = TRUE)

importProject(project_name)

getStructuralModel()

[Monolix – PKanalix – Simulx] Import project from Datxplore, Monolix or PKanalix

Description

Import a Monolix or a PKanalix project into the currently running application initialized in the connectors.
The extensions are .mlxtran for Monolix, .pkx for PKanalix, .smlx for Simulx and .dxp for Datxplore.
WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.
Allowed import sources are:

Usage

importProject(projectFile)

Arguments

Details

At import, a new project is created in a temporary folder with a project setting filesNextToProject = TRUE,
which means that file dependencies such as data and model files are copied and kept next to the new project
(or in the result folder for Simulx). This new project can be saved to the desired location withsaveProject.

Simulx projects can only be exported, not imported. To export a Simulx project to another application,
please load the Simulx project with the Simulx connectors and use exportProject.

Importing a Monolix or a PKanalix project into Simulx automatically creates elements that can be used for
simulation, exactly as in the GUI.

To see which elements of some type have been created in the new project, you can use the get..Element functions:
getOccasionElements, getPopulationElements, getPopulationElements, getIndividualElements,
getCovariateElements, getTreatmentElements, getOutputElements, getRegressorElements.

See Also

saveProject, exportProject

#

initializeLixoftConnectors(software = "simulx", force = TRUE)

importProject("/path/to/project/file.mlxtran") 

importProject("/path/to/project/file.pkx") 

initializeLixoftConnectors(software = "monolix", force = TRUE)

importProject("/path/to/project/file.pkx") 

initializeLixoftConnectors(software = "pkanalix", force = TRUE)

importProject("/path/to/project/file.mlxtran") 

## End(Not run)

# working example to import a Monolix demo project into Simulx. The resulting .smlx file can be opened from Simulx GUI.

initializeLixoftConnectors(software = "monolix", force = TRUE)

MonolixDemoPath = file.path(getDemoPath(),"1.creating_and_using_models","1.1.libraries_of_models","warfarinPK_project.mlxtran")

initializeLixoftConnectors(software = "simulx", force = TRUE)

importProject(MonolixDemoPath)

saveProject("importFromMonolix.smlx")

[Monolix – PKanalix – Simulx] Get current project load status.

Description

Get a logical saying if a project is currently loaded.

Usage

isProjectLoaded()

Value

TRUE if a project is currently loaded, FALSE otherwise

#

project_name <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

loadProject(project_name)

isProjectLoaded()

initializeLixoftConnectors("pkanalix")

isProjectLoaded()

[Monolix – PKanalix – Simulx] Load project from file

Description

Load a project in the currently running application initialized in the connectors.
The extensions are .mlxtran for Monolix, .pkx for PKanalix, and .smlx for Simulx.
WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.

Usage

loadProject(projectFile)

Arguments

See Also

saveProject, importProject, exportProject, newProject

#

loadProject("/path/to/project/file.mlxtran") for Linux platform

loadProject("C:/Users/path/to/project/file.mlxtran") for Windows platform

## End(Not run)

# Load a Monolix project

initializeLixoftConnectors("monolix")

project_name <- file.path(getDemoPath(), "8.case_studies", "hiv_project.mlxtran")

loadProject(project_name)

# Load a PKanalix project

initializeLixoftConnectors("pkanalix")

project_name <- file.path(getDemoPath(), "1.basic_examples", "project_censoring.pkx")

loadProject(project_name)

# Load a Simulx project

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "2.models", "longitudinal.smlx")

loadProject(project_name)

[Monolix – PKanalix – Simulx] Create a new project

Description

Create a new project. New projects can be created in the connectors as in PKanalix, Monolix or Simulx GUI. The creation of a new project requires a dataset in PKanalix, a dataset and a model in Monolix, and a model in Simulx.

Usage

newProject(modelFile = NULL, data = NULL, mapping = NULL)

Arguments

Details

Note: instead of creating a project from scratch, it is also possible in Monolix and PKanalix to load an existing project with loadProject or importProject and change the dataset or the model with setData or setStructuralModel.

See Also

newProject saveProject

#

initializeLixoftConnectors("monolix")

data_file <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "data", "warfarin_data.csv")

newProject(data = list(dataFile = data_file, 

                       headerTypes = c("id", "time", "amount", "observation", "obsid", "contcov", "catcov", "contcov")),

           modelFile = "lib:oral1_1cpt_IndirectModelInhibitionKin_TlagkaVClR0koutImaxIC50.txt",

           mapping = list(list(obsId = "1",

                               modelOutput = "Cc",

                               observationName = "y1"),

                          list(obsId = "2",

                               modelOutput = "R",

                               observationName = "y2")))

# Create a new PKanalix project

initializeLixoftConnectors("pkanalix")

data_file <- file.path(getDemoPath(), "1.basic_examples", "data", "data_BLQ.csv")

newProject(data = list(dataFile = data_file,

                       headerTypes = c("id", "time", "amount", "observation", "cens", "catcov")))

# Create a new Simulx project

initializeLixoftConnectors("simulx")

newProject(modelFile = "lib:oral1_1cpt_IndirectModelInhibitionKin_TlagkaVClR0koutImaxIC50.txt")

[Monolix – PKanalix – Simulx] Save current project

Description

Save the current project as a file that can be reloaded in the connectors or in the GUI.

Usage

saveProject(projectFile = "")

Arguments

Details

The extensions are .mlxtran for Monolix, .pkx for PKanalix, and .smlx for Simulx.
WARNING: R is sensitive between ‘\’ and ‘/’, only ‘/’ can be used.

If the project setting "userfilesnexttoproject" is set to TRUE with setProjectSettings, all file dependencies such as model, data or external files are saved next to the project for Monolix and PKanalix, and in the result folder for Simulx.

See Also

newProject loadProject

#

[PKanalix only]

saveProject("/path/to/project/file.pkx") # save a copy of the model

[Monolix only]

saveProject("/path/to/project/file.mlxtran") # save a copy of the model

[Simulx only]

saveProject("/path/to/project/file.smlx") # save a copy of the model

[Monolix - PKanalix - Simulx] 

saveProject() # update current model

## End(Not run)

# Load, change and save a PKanalix project under a new name

initializeLixoftConnectors("pkanalix")

project_name <- file.path(getDemoPath(), "1.basic_examples", "project_censoring.pkx")

loadProject(project_name)

setNCASettings(blqMethodAfterTmax = "missing")

saveProject("~/changed_project.pkx")

# Load, change and save a Monolix project under a new name

initializeLixoftConnectors("monolix")

project_name <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

loadProject(project_name)

addContinuousTransformedCovariate(tWt = "3*exp(wt)")

saveProject("~/changed_project.mlxtran")

# Load, change and save a Simulx project under a new name

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "2.models", "longitudinal.smlx")

loadProject(project_name)

defineTreatmentElement(name = "trt", element = list(data = data.frame(time = 0, amount = 100)))

saveProject("~/changed_project.smlx")

[Monolix – PKanalix – Simulx] Share project.

Description

Create a zip archive file from current project and its results.

Usage

shareProject(archiveFile)

Arguments

#

shareProject("/path/to/archive.zip")

## End(Not run)

[Monolix – PKanalix – Simulx] Get console mode

Description

Get console mode, ie volume of output after running estimation tasks. Possible verbosity levels are:

Usage

getConsoleMode()

Value

A string corresponding to current console mode

See Also

setConsoleMode

[Monolix – PKanalix – Simulx] Get project preferences

Description

Get a summary of the project preferences. Preferences are:

Usage

getPreferences(...)

Arguments

Value

A list with each preference name mapped to its current value.

#

getPreferences() # retrieve a list of all the general settings

getPreferences("imageFormat","exportCharts") 

# retrieve only the imageFormat and exportCharts settings values

## End(Not run)

[Monolix – PKanalix – Simulx] Get project settings

Description

Get a summary of the project settings.
Associated settings for Monolix projects are:

Associated settings for PKanalix projects are:

Associated settings for Simulx projects are:

Usage

getProjectSettings(...)

Arguments

Value

A list with each setting name mapped to its current value.

See Also

setProjectSettings

#

getProjectSettings() # retrieve a list of all the project settings

## End(Not run)

[Monolix – PKanalix – Simulx] Set console mode

Description

Set console mode, ie volume of output after running estimation tasks. Possible verbosity levels are:

Usage

setConsoleMode(mode)

Arguments

See Also

getConsoleMode

[Monolix – PKanalix – Simulx] Set preferences

Description

Set the value of one or several of the project preferences. Prefenreces are:

Usage

setPreferences(...)

Arguments

See Also

getPreferences

#

setPreferences(exportCharts = FALSE, delimiter = ",")

## End(Not run)

[Monolix – PKanalix – Simulx] Set project settings

Description

Set the value of one or several of the settings of the project.
Associated settings for Monolix projects are:

Associated settings for PKanalix projects are:

Associated settings for Simulx projects are:

Usage

setProjectSettings(...)

Arguments

See Also

getProjectSettings

#

setProjectSettings(directory = "/path/to/export/directory", seed = 12345)

## End(Not run)

[Simulx] Export simulated data

Description

Export the simulated dataset into a MonolixSuite compatible format.
It contains treatment information and simulation results and can be generated only when simulation results are available.

Usage

exportSimulatedData(filePath = "")

Arguments

Details

The generated dataset can then be loaded in Datxplore, PKanalix or Monolix.

Note: to export the simulated data and load it into another application in a single line, you can also use exportProject.

See Also

exportProject

#

 project_name <- file.path(getDemoPath(), "1.overview", "newProject_TMDDmodel.smlx")

 loadProject(project_name)

 runSimulation()

 exportSimulatedData()

[Simulx] Get endpoints results

Description

Get the results of the outcomes & endpoints task. Outcomes, endpoints and group comparisons are calculated as in Simulx GUI with the task runEndpoints.The output is a list with outcomes, endpoints and comparison results if they have been computed.

Usage

getEndpointsResults()

See Also

runEndpoints

#

 getEndpointsResults()

 $outcomes

 $outcomes$outcome_per_id

       rep                   group  ID outcome_per_id

   1     1     washout_before_occ2   1        7.30854

   2     1     washout_before_occ2   2        7.36297

   3     1     washout_before_occ2   3        6.40377

   4     1     washout_before_occ2   4        7.49762

   5     1     washout_before_occ2   5        7.55129

   ...

 $endpoints

 $endpoints$endpoint_name

    rep                   group arithmeticMean standardDeviation

  1   1     washout_before_occ2        7.32404          0.775968

  2   2     washout_before_occ2        7.47649           1.12214

  3   3     washout_before_occ2        7.14622          0.827815

  ...

 $groupComparison

 $groupComparison$endpoint1

    rep                   group difference     p-value success

  1   1 no_whashout_before_occ2    1.09646 2.75024e-06    TRUE

  2   1               bothDoses    6.95433    <2.2e-16    TRUE

  3   2 no_whashout_before_occ2   0.990928 1.29062e-05    TRUE

  ...

## End(Not run)

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "6.outcome_endpoints", "6.1.outcome_endpoints", "OutcomeEndpoint_PDTTE_survival_NADIR_timeToNADIR.smlx")

loadProject(project_name)

runScenario()

getEndpointsResults()

[Simulx] Get simulation results

Description

Get the results of the simulation.
The output is a list of four elements: res, individualParameters, populationParameters and doses, and optionally id_mapping for external id tables.

• res corresponds to the list of the output(s) of the simulation. It includes a data frame for each output with the columns id, original_id (if an external element with id column is used in the simulation), time, outputName, and group (corresponding to the group name if there are several groups).

• individualParameters corresponds to a list of data frames, one for each simulation group, with the individual parameters sampled in the group.

• populationParameters corresponds to a list of data frames, one for each simulation group, with the population parameters sampled in the group (can be several sets only in case of replicates).

• doses corresponds to a list of data frames, one for each simulation group, with the dose amounts administered to each individual in the group.

• id_mapping maps the original ids used in the external tables to the simulated ids.

Usage

getSimulationResults(id = NULL, rep = NULL)

Arguments

See Also

runSimulation

#

 initializeLixoftConnectors("simulx")

 project_file <- file.path(getDemoPath(), "1.overview", "importFromMonolix_resimulateProject.smlx")

 loadProject(project_file)

 runSimulation()

 ## Not run: 

   getSimulationResults()

   getSimulationResults()$individualParameters

   getSimulationResults()$doses

## End(Not run)

 # retrieve results of a specific individual and replicate

 initializeLixoftConnectors("simulx")

 project_file <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")

 loadProject(project_file)

 runSimulation()

 getSimulationResults(id = "1", rep = 10)

[Monolix – PKanalix – Simulx] Compute the charts data

Description

Compute (if needed) and export the charts data of a given plot or, if not specified, all the available project plots.

Usage

computeChartsData(plot = NULL, output = NULL, exportVPCSimulations = NULL)

Arguments

Details

computeChartsData can be used to compute and export the charts data for plots available in the graphical user interface as in Monolix, PKanalix or Simulx, when you export > export charts data.

The exported charts data is saved as txt files in the result folder, in the ChartsData subfolder.

Notice that it does not impact the current scenario.

To get a ggplot equivalent to the plot in the GUI, but customizable in R with the ggplot2 library, better use one of the plot… functions available in the connectors for Monolix and PKanalix (not available for Simulx). To get the charts data for one of these plot functions as a dataframe, you can use getChartsData.

See Also

getChartsData

#

computeChartsData() # Monolix - PKanalix - Simulx

computeChartsData(plot = "vpc", output = "y1") # Monolix

## End(Not run)

[Monolix – PKanalix – Simulx] Get current scenario

Description

Get the list of tasks that will be run at the next call to runScenario. For Monolix, get in addition the associated method (linearization true or false), and the associated list of plots.

Usage

getScenario()

Details

For Monolix, getScenario returns a given list of tasks, the linearization option and the list of plots.
Every task in the list is associated to a logical
NOTE: Within a MONOLIX scenario, the order according to which the different algorithms are run is fixed:

For PKanalix, getScenario returns a given list of tasks.
Every task in the list is associated to a logical
NOTE: Within a PKanalix scenario, the order according to which the different algorithms are run is fixed:

For Simulx, setScenario returns a given list of tasks.
Every task in the list is associated to a logical
NOTE: Within a Simulx scenario, the order according to which the different algorithms are run is fixed:

Note: every task can also be run separately with a specific function, such as runSimulation in Simulx, runEstimation in Monolix. The CA task in PKanalix cannot be part of a scenario, it must be run with runCAEstimation.

Value

The list of tasks that corresponds to the current scenario, indexed by task names.

See Also

setScenario

#

[MONOLIX]

scenario = getScenario()

scenario

 -> $tasks 

    populationParameterEstimation conditionalDistributionSampling conditionalModeEstimation standardErrorEstimation logLikelihoodEstimation plots

    TRUE                          TRUE							 TRUE                      FALSE                   FALSE                   FALSE 

    $linearization = T

    $plotList = "outputplot", "vpc"

[PKANALIX]

scenario = getScenario()

scenario

    nca     be 

   TRUE  FALSE

[SIMULX]

scenario = getScenario()

scenario

  simulation  endpoints 

        TRUE      FALSE

## End(Not run) 

[Monolix – PKanalix – Simulx] Run scenario

Description

Run the scenario that has been set with setScenario.

Usage

runScenario()

Details

A scenario is a list of tasks to be run. Setting the scenario is equivalent to selecting tasks in Monolix, PKanalix or Simulx GUI that will be performed when clicking on RUN.

If exportchartsdata preference is set to TRUE with setPreferences, runscenario generates the charts data in the result folder.

Every task can also be run separately with a specific function, such as runSimulation in Simulx, runEstimation in Monolix. The CA task in PKanalix cannot be part of a scenario, it must be run with runCAEstimation.

See Also

setScenario getScenario

#

runScenario()

## End(Not run)

[Monolix – PKanalix – Simulx] Set scenario

Description

Clear the current scenario and build a new one from a given list of tasks.

Usage

setScenario(...)

Arguments

Details

A scenario is a list of tasks to be run by runScenario. Setting the scenario is equivalent to selecting tasks in Monolix, PKanalix or Simulx GUI that will be performed when clicking on RUN.

For Monolix, setScenario requires a given list of tasks, the linearization option and the list of plots.
Every task in the list should be associated to a logical
NOTE: by default the logical is FALSE, thus, the user can only state what will run during the scenario.
NOTE: Within a MONOLIX scenario, the order according to which the different algorithms are run is fixed:

For PKanalix, setScenario requires a given list of tasks.
Every task in the list should be associated to a logical
NOTE: By default the logical is FALSE, thus, the user can only state what will run during the scenario.
NOTE: Within a PKanalix scenario, the order according to which the different algorithms are run is fixed:

For Simulx, setScenario requires a given list of tasks.
Every task in the list should be associated to a logical
NOTE: By default the logical is FALSE, thus, the user can only state what will run during the scenario.
NOTE: Within a Simulx scenario, the order according to which the different algorithms are run is fixed:

Note: every task can also be run separately with a specific function, such as runSimulation in Simulx, runEstimation in Monolix. The CA task in PKanalix cannot be part of a scenario, it must be run with runCAEstimation.

See Also

getScenario.

#

[MONOLIX]

scenario = getScenario()

scenario$tasks = c(populationParameterEstimation = T, conditionalModeEstimation = T, conditionalDistributionSampling = T)

setScenario(scenario)

[PKANALIX]

scenario = getScenario()

scenario = c(nca = T, be = F)

setScenario(scenario)

[SIMULX]

scenario = getScenario()

scenario = c(simulation = T, endpoints = F)

setScenario(scenario)

## End(Not run)

[Simulx] Add simulation group

Description

Add a new simulation group.

Usage

addGroup(group)

Arguments

Details

Simulation groups can be added to the simulation as in Simulx GUI. By default, the elements of the newly added group are the same as the first simulation group. To check which elements have been set for this group, please use getGroups. To change a group element, use setGroupElement.

Note: when a Simulx project is created, a first group is created by default with the name "simulationGroup1".

See Also

getGroups

#

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "4.exploration", "PKPD_exploration.smlx")

  loadProject(project_name)

  addGroup("simulationGroup2")

  setGroupElement("simulationGroup2", elements = "Dose_4000")

[Simulx] Get remaining parameters for a simulation group

Description

Get the values of the remaining parameters (typically the error model parameters) for a group.

Usage

getGroupRemaining(group)

Arguments

Details

Remaining parameters are all parameters that appear in the structural model (in the input line of [LONGITUDINAL]) and are neither individual parameters not regressors.
They are typically error model parameters.

If an individual parameters element is selected for simulation, and the model includes remaining parameters, it is possible to set their values with setGroupRemaining.

It typically enables to make a simulation with measurement noise, with an individual element.
These error model parameters will impact the simulation only if a noisy observation (from the DEFINITION section of the [LONGITUDINAL] block) is set as output element (instead of a smooth prediction in OUTPUT or variable in EQUATION).

If a population parameters element is selected, it is not possible to set remaining parameters because these parameters are already part of the population element.

See Also

setGroupRemaining

#

  initializeLixoftConnectors("monolix")

  monolix_project <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

  initializeLixoftConnectors("simulx")

  importProject(monolix_project)

  setGroupElement(group = "simulationGroup1", elements = "mlx_EBEs")

  getGroupRemaining(group = "simulationGroup1")

[Simulx] Get simulation groups

Description

Get the list of simulation groups and elements in each group.

Usage

getGroups()

Details

Simulation groups are used for simulation as in Simulx GUI.
At the creation of a Simulx project, a first group is created by default with the name "simulationGroup1".
Use getGroups to check which groups have already been defined, and which elements are set in each group.
To add a simulation group, use addGroup.
To remove a simulation group, use removeGroup. To add or change a group element, use setGroupElement.
To define new elements, use one of the define…Element functions.

See Also

addGroup

#

# Working example

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "5.simulation", "simulationGroups_ethnicGroups.smlx")

loadProject(project_name)

getGroups()

[[1]]

[[1]]$name       

[1] "g_caucasian"

[[1]]$covariate  

[1] "caucasian"  

[[1]]$parameter

[[1]]$parameter$type

[1] "population"

[[1]]$parameter$name

[1] "manual_popParam"

[[1]]$treatment

[1] "single_dose"

[[1]]$output

[1] "regularY1" "regularCc"

[[1]]$size

[1] 42

[[2]]

[[2]]$name

[1] "g_asian"

[[2]]$covariate

[1] "asian"

[[2]]$parameter

[[2]]$parameter$type

[1] "population"

[[2]]$parameter$name

[1] "manual_popParam"

[[2]]$treatment

[1] "single_dose"

[[2]]$output

[1] "regularY1" "regularCc"

[[2]]$size

[1] 42

## End(Not run)

[Simulx] Get number of replicates

Description

Get the number of replicates of the simulation.

Usage

getNbReplicates()

Details

The number of replicates is the number of times that Simulx will simulate a given study.
It should not be mixed up with the group size defined by setGroupSize.

To simulate one study, Simulx samples a number of individuals for each group, defined by setGroupSize (let’s say NidsPerGroup).
To simulate replicate studies, it will sample for each replicate NidsPerGroup other individuals for each group (it is like changing the seed).

If the parameter element is an individual element or a population parameter defined with a vector, replicates will always sample individuals using the same population parameters. In this case, they are useful to check the effect of changing the seed, to get for example the uncertainty of an endpoint due to limited sampling.

If the parameter element is a population element defined with a table containing several lines, or an imported element such as mlx_PopUncertainSA or mlx_TypicalUncertainSA, each replicate will use a different population parameter to simulate the study. In this case, it is possible to see the effect of changing the population parameters on the prediction (in addition to uncertainty due to limited sampling).

See Also

setNbReplicates

#

  project_name <- file.path(getDemoPath(), "5.simulation", "replicates.smlx")

  loadProject(project_name)

  getNbReplicates()

[Simulx] Get same individuals among groups

Description

Get the information if the same individuals are simulated among all groups.

Usage

getSameIndividualsAmongGroups()

Details

setSameIndividualsAmongGroups(value = TRUE) allows to have the same individual parameters in all groups.
It is available if the following elements (required for the sampling) are the same for all groups: size of groups, parameters (population or individual) and covariates.

The main goal is to make the comparison between groups easier.

In particular, it is used to compare different treatments on the same individuals – subjects with the same individual parameters.

Selecting same individuals among groups ensures that the differences between groups are only due to the treatment itself.
To obtain the same conclusion without this option enabled, simulation should be performed on a very large number of individuals to averaged out the individual differences.

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

setSameIndividualsAmongGroups

#

  project_name <- file.path(getDemoPath(), "5.simulation", "simulationGroups_sameIdsInGroups.smlx")

  loadProject(project_name)

  getSameIndividualsAmongGroups()

[Simulx] Get sampling method

Description

Get which sampling method is used for the simulation. The possibilities are:

• keepOrder (default): individual values are taken in the same order as they appear in a table.

• withReplacement: individual values are sampled from a table with replacement.

• withoutReplacement: individual values are sampled from a table without replacement. This option is available only if tables contain at least the same number of individual values as a group size.

All of the above sampling methods are general and apply to all tables in a simulation scenario.

Usage

getSamplingMethod()

Details

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

setSamplingMethod

#

  project_name <- file.path(getDemoPath(), "5.simulation", "samplingOptions.smlx")

  loadProject(project_name)

  getSamplingMethod()

[Simulx] Get element types sharing individuals

Description

Get the element types that will share the same individuals in the simulation.

Usage

getSharedIds()

Details

If several elements are defined with tables of individual values and set to some simulation groups, the option "shared ids" allows to create an intersection of ids present in these tables. After that, ids from this intersection are sampled to create the data for simulation.

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

setSharedIds

#

  project_name <- file.path(getDemoPath(), "5.simulation", "sharedIds.smlx")

  loadProject(project_name)

  getSharedIds()

[Simulx] Remove simulation group

Description

Remove a simulation group.

Usage

removeGroup(group)

Arguments

Details

Simulation groups are used for simulation as in Simulx GUI.
At the creation of a Simulx project, a first group is created by default with the name "simulationGroup1".
Use getGroups to check which groups have already been defined, and which elements are set in each group.
To add a simulation group, use addGroup.
To remove a simulation group, use removeGroup. To add or change a group element, use setGroupElement.
To define new elements, use one of the define…Element functions.

See Also

getGroups,addGroup

#

  project_name <- file.path(getDemoPath(), "5.simulation", "simulationGroups_treatment.smlx")

  loadProject(project_name)

  removeGroup("medium_dose")

[Simulx] Remove element from simulation group

Description

Remove an element from a simulation group.

Usage

removeGroupElement(group, element)

Arguments

Details

Simulation groups are used for simulation as in Simulx GUI.
At the creation of a Simulx project, a first group is created by default with the name "simulationGroup1".
Use getGroups to check which groups have already been defined, and which elements are set in each group.
To add a simulation group, use addGroup.
To remove a simulation group, use removeGroup. To add or change a group element, use setGroupElement.
To define new elements, use one of the define…Element functions.

Note: Removing an output element used in an outcome will delete the corresponding outcome and remove the outcome from the endpoints using it.

See Also

setGroupElement

#

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "5.simulation", "simulationGroups_treatment.smlx")

  loadProject(project_name)

  removeGroupElement(group = "low_dose", element = "regularY1") 

  removeGroupElement(group = "medium_dose", element = "regularY1") 

  removeGroupElement(group = "high_dose", element = "regularY1") 

[Simulx] Rename simulation group

Description

Rename a simulation group.

Usage

renameGroup(currentGroupName, newGroupName)

Arguments

Details

Note: At the creation of a Simulx project, a first group is created by default with the name "simulationGroup1". It is possible to rename this group.

See Also

addGroup getGroups

#

  project_name <- file.path(getDemoPath(), "3.definition", "3.1.treatments", "treatment_manual.smlx")

  loadProject(project_name)

  renameGroup("simulationGroup1", "two_doses")

[Simulx] Run endpoints task

Description

Run the endpoints task.

Usage

runEndpoints()

See Also

getEndpointsResults

#

  runEndpoints()

## End(Not run)

[Simulx] Run simulation

Description

Run the simulation task.

Usage

runSimulation()

Details

As when clicking on SIMULATION in Simulx GUI, simulated values are saved as text files in a result folder which is located next to the project file when calling saveProject.

To get the sampled parameters and simulated outputs as data frames, use getSimulationResults.

To post-process the results by computing outcomes and endpoints, use runEndpoints.

To run both the simulation and endpoint tasks, use setScenario and runScenario.

To get some output in the console showing the status of the simulation, use setConsoleMode.

runSimulation does not generate charts data in the result folder even if the preference exportchartsdata is TRUE.
To generate charts data in the result folder at run, use runScenario instead.

See Also

getSimulationResults

#

  project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")

  loadProject(project_name)

  setConsoleMode("basic")

  runSimulation()

[Simulx] Set elements to a simulation group

Description

Set the new element of a specific group. If an element of the same type is already set, setGroupElement will replace it.
For treatments and outputs, it is possible to set several elements at the same time by using a vector.

Usage

setGroupElement(group, elements)

Arguments

Details

Simulation groups are used for simulation as in Simulx GUI.
The same rules apply as in the GUI to set group elements. For example, a covariate element can be set only if the parameter element is a population parameter.

At the creation of a Simulx project, a first group is created by default with the name "simulationGroup1".
Use getGroups to check which groups have already been defined, and which elements are set in each group.
To add a simulation group, use addGroup.
To remove a simulation group, use removeGroup. To add or change a group element, use setGroupElement.
To remove an element from a group, use removeGroupElement.
To define new elements, use one of the define…Element functions.

See Also

getGroups

#

  monolix_project <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

  initializeLixoftConnectors("simulx")

  importProject(monolix_project)

  setGroupElement(group = "simulationGroup1", elements = c("mlx_EBEs", "mlx_Cc"))

[Simulx] Set remaining parameters for a simulation group

Description

Set the values of the remaining parameters (typically the error model parameters) for a group.

Usage

setGroupRemaining(group, remaining)

Arguments

Details

Remaining parameters are all parameters that appear in the structural model (in the input line of [LONGITUDINAL]) and are neither individual parameters not regressors.
They are typically error model parameters.

If an individual parameters element is selected for simulation, and the model includes remaining parameters, it is possible to set their values with setGroupRemaining.

It typically enables to make a simulation with measurement noise, with an individual element.
These error model parameters will impact the simulation only if a noisy observation (from the DEFINITION section of the [LONGITUDINAL] block) is set as output element (instead of a smooth prediction in OUTPUT or variable in EQUATION).

If a population parameters element is selected, it is not possible to set remaining parameters because these parameters are already part of the population element.

See Also

getGroupRemaining

#

  monolix_project <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

  initializeLixoftConnectors("simulx")

  importProject(monolix_project)

  setGroupElement(group = "simulationGroup1", elements = "mlx_EBEs")

  setGroupRemaining(group = "simulationGroup1", remaining = list(a = 0.2, b = 0.05))

[Simulx] Set simulation group size

Description

Define the size of a simulation group.

Usage

setGroupSize(group, size)

Arguments

Details

Group size is the number of individuals (ie sets of individual parameters and covariate values) that will be sampled by Simulx for a given group.
It should not be mixed up with the number of replicates that can be set with setNbReplicates.

To get the size of a group, please use getGroups.

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

getGroups

#

  project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")

  loadProject(project_name)

  setGroupSize("gr_BID_N30", 40)

  setGroupSize("gr_OD_N30", 40)

[Simulx] Set number of replicates

Description

Define the number of replicates of the simulation.

Usage

setNbReplicates(nb)

Arguments

Details

The number of replicates is the number of times that Simulx will simulate a given study.
It should not be mixed up with the group size defined by setGroupSize.

To simulate one study, Simulx samples a number of individuals for each group, defined by setGroupSize (let’s say NidsPerGroup).
To simulate replicate studies, it will sample for each replicate NidsPerGroup other individuals for each group (it is like changing the seed).

If the parameter element is an individual element or a population parameter defined with a vector, replicates will always sample individuals using the same population parameters. In this case, they are useful to check the effect of changing the seed, to get for example the uncertainty of an endpoint due to limited sampling.

If the parameter element is a population element defined with a table containing several lines, or an imported element such as mlx_PopUncertainSA or mlx_TypicalUncertainSA, each replicate will use a different population parameter to simulate the study. In this case, it is possible to see the effect of changing the population parameters on the prediction (in addition to uncertainty due to limited sampling).

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

getNbReplicates

#

  project_name <- file.path(getDemoPath(), "5.simulation", "replicates.smlx")

  loadProject(project_name)

  setNbReplicates(nb = 20)

[Simulx] Set same individuals among groups

Description

Define if the same individuals will be simulated among all groups.

Usage

setSameIndividualsAmongGroups(value)

Arguments

Details

setSameIndividualsAmongGroups(value = TRUE) allows to have the same individual parameters in all groups.
It is available if the following elements (required for the sampling) are the same for all groups: size of groups, parameters (population or individual) and covariates.

The main goal is to make the comparison between groups easier.
In particular, it is used to compare different treatments on the same individuals – subjects with the same individual parameters.

Selecting same individuals among groups ensures that the differences between groups are only due to the treatment itself.
To obtain the same conclusion without this option enabled, simulation should be performed on a very large number of individuals to averaged out the individual differences.

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

getSameIndividualsAmongGroups

#

  initializeLixoftConnectors("simulx")

  project_name <- file.path(getDemoPath(), "4.exploration", "PKPD_exploration.smlx")

  loadProject(project_name)

  addGroup("simulationGroup2")

  setGroupElement("simulationGroup2", elements = "Dose_4000")

  setSameIndividualsAmongGroups(value = TRUE)

[Simulx] Set sampling method

Description

Define which sampling method is used for the simulation. The possibilities are:

• keepOrder (default): individual values are taken in the same order as they appear in a table.

• withReplacement: individual values are sampled from a table with replacement.

• withoutReplacement: individual values are sampled from a table without replacement. This option is available only if tables contain at least the same number of individual values as a group size.

All of the above sampling methods are general and apply to all tables in a simulation scenario.

Usage

setSamplingMethod(method)

Arguments

Details

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

getSamplingMethod

#

  project_name <- file.path(getDemoPath(), "5.simulation", "samplingOptions.smlx")

  loadProject(project_name)

  setSamplingMethod(method = "withReplacement")

[Simulx] Set element types sharing individuals

Description

Select the element types that will share the same individuals in the simulation.

Usage

setSharedIds(sharedIds)

Arguments

Details

If several elements are defined with tables of individual values and set to some simulation groups, the option "shared ids" allows to create an intersection of ids present in these tables. After that, ids from this intersection are sampled to create the data for simulation.

All options of the Simulx scenario are the same as in Simulx GUI. Check the online doc of Simulx to get more guidance on how to use them.

See Also

getSharedIds

#

  monolix_project <- file.path(getDemoPath(), "1.creating_and_using_models", "1.1.libraries_of_models", "warfarinPK_project.mlxtran")

  loadProject(monolix_project)

  runScenario()

  initializeLixoftConnectors("simulx")

  importProject(monolix_project)

  setGroupElement(group = "simulationGroup1", elements = c("mlx_EBEs", "mlx_Cc"))

  setSharedIds(sharedIds = c("individual", "treatment"))

  # to remove shared IDs

  setSharedIds(sharedIds = c())

[Simulx] Print outcomes and endpoints

Description

Get all the outcomes and endpoints defined in the Simulx project.
The output is a list of:

• outcomes is a table of all defined simulation outcomes. To define an outcome, use defineOutcome().

• endpoints is a table of all defined simulation endpoints. To define an endpoint, use defineEndpoint().

• groupComparison is a Boolean and indicates whether group comparison is enabled. To change this setting, use setGroupComparisonSettings().

• groupComparisonReferenceGroup corresponds to the reference simulation group for group comparison if enabled. To change this setting, use setGroupComparisonSettings().

#’

Usage

printOutcomesEndpoints()

See Also

printSimulationSetup

#

# Working example

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")

loadProject(project_name)

printOutcomesEndpoints()

$outcomes

output        processing applyThreshold

outcome_efficacy noisyResponse_2weeks last value per id          <= 60

outcome_safety         noisyCc_2weeks last value per id         <= 1.5

$endpoints

outcome.groupName                   outcome.names outcome.operator      metric groupComparison.type groupComparison groupComparison.pvalue

Percent_IDs_in_target      is_in_target outcome_safety,outcome_efficacy              and percentTrue      statisticalTest  oddsRatio != 1                   0.05

$groupComparison

[1] TRUE

$groupComparisonReferenceGroup

[1] "gr_BID_N30"

## End(Not run)

[Simulx] Print simulation setup

Description

Get all the elements used in simulation setup: content of simulation groups and simulation settings.
The output is a list of:

• simulationGroups is a table of the elements selected in the simulation groups, with one simulation group per column. To add a simulation group, use addGroup. To remove a simulation group, use removeGroup. To add or change a group element, use setGroupElement. To change the number of simulated individuals in a group, use setGroupSize.

• nbReplicates is the number of simulation replicates. To change the number of replicates, use setNbReplicates.

• samplingMethod is the sampling method used for the simulation (keepOrder, withReplacement or withoutReplacement). To change the sampling method, use setSamplingMethod.

• sharedIds corresponds to element types that will share the same individuals in the simulation. To change this, use setSharedIds.

• sameIndividualsAmongGroups is a Boolean. If TRUE, the same individual parameters are sampled in all groups. TO change this setting, use setSameIndividualsAmongGroups.

#’

Usage

printSimulationSetup()

See Also

printOutcomesEndpoints

#

# Working example

initializeLixoftConnectors("simulx")

project_name <- file.path(getDemoPath(), "1.overview", "importFromMonolix_clinicalTrial.smlx")

loadProject(project_name)

printSimulationSetup()

$simulationGroups

gr_BID_N30                            gr_OD_N30

size                                         30                                   30

parameters                              mlx_Pop                              mlx_Pop

treatments      loadDose_BID4mg, regDose_BID2mg        loadDose_OD8mg, regDose_OD4mg

outputs    noisyResponse_2weeks, noisyCc_2weeks noisyResponse_2weeks, noisyCc_2weeks

covariates                              mlx_Cov                              mlx_Cov

$nbReplicates

[1] 100

$samplingMethod

[1] "withReplacement"

$sharedIds

logical(0)

$sameIndividualsAmongGroups

[1] FALSE

$seed

[1] 123456

## End(Not run)