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.





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

  • 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

Description of the functions concerning the results

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

name

(character) Element name.

element

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

  • file (character) Path to the population file.

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

Details

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

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

In any case, it can contain columns occasions (optional), and it should contain one column per covariate (mandatory). Covariate names and categorical covariate values must correspond to covariates and categories defined in the model (block [COVARIATE]). The occasion headers must correspond to the occasion names defined in the occasion element.

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

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

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

See Also

getCovariateElements

Click here to see examples

#

  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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

name

(character) (required) Endpoint name.

element

(list) (required) List with the endpoint settings:

  • outcome (character or list) (required) – Outcome on which the endpoint is based on. If one outcome, use a string containing its name. Use list to combine outcomes with:

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

    • groupName (character) – Name you want to give to 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) (optional) – Calculation method for the endpoint. One of "arithmeticMean" (default), "geometricMean" or "median" if value-based outcome. In case of event-based outcomes, "kaplanMeier" (median survival) will be used and in case of boolean outcomes, "percentTrue" will be used by default.

  • groupComparison (optional) (list) – Group comparison settings. List of:

    • type (character) (optional) – one of "directComparison", "statisticalTest" (default).

    • h1 (list) (optional) – a list containing hypothesis information:

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

      • threshold (double) – a real number indicating the threshold for difference/oddsRatio (0 by default)

      • pvalue (double) – a real number indicating the p-value (if type is "statisticalTest", 0.05 by default)

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

name

(character) Element name.

element

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

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

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

Details

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

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

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

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

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

See Also

getIndividualElements

Click here to see examples

#

  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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Define occasion element

Description

Define the occasion structure of the project.

Usage

defineOccasionElement(element)

Arguments

element

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

  • file (character) Path to the occasion file.

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

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

name

(character) Outcome name.

element

(list) List with the outcome settings:

output (character) Name of the output element on which the outcome is based.
perOccasion (logical) (optional) If occasions are present in the simulation, it indicates if the outcome is calculated for each id or each occasion of each id. TRUE by default.

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

relativeTo (list) (optional) List of elements that define reference settings:

  • reference – one of "baseline", "min", "max", "minCurrentTime", "maxCurrentTime" or "customValue",

  • type – "ratio" or "difference",

  • value – if reference is "customValue".

processing (list) (required) List of elements that define how the output will be processed:

  • operator (required) – one of "avg", "min", "max", "first", "last", "durationBelow", "durationAbove", "durationBetween", "timePoint", or "none" (if the output has a single time point and does not require processing).

  • type (optional)

    • if operator is "min" or "max", one of "value" (default), "timeContinuous" or "timeEvent",

    • if operator is "durationBelow", "durationAbove" or "durationBetween", one of "cumulativeTime" (default), "percentTime", "nbObs", "firstOccurenceContinuous" or "firstOccurenceEvent",

  • value (optional) – vector of boundaries if operator is "durationBelow", "durationAbove" or "durationBetween", or time point if operator is "timePoint" (0 by default).

applyThreshold (list) (optional) List of elements:

  • operator – one of "==", "!=", ">=", ">", "<=" or "<",

  • value – a real number indicating the threshold value.

Or if the outcome is based on a TTE output:

event (list) (required) List of arguments that define event settings:

  • type (required) – one of "timeOfEvents" (in case of single and repeated TTE), "hasAnEvent", "hasNoEvent" (in case of single TTE) or "numberOf" (in case of repeated TTE),

  • rank (optional) – rank of the event of which time is the outcome (if type is "timeOfEvents" and repeated TTE).

See Also

getOutcomes

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Define output element

Description

Define or edit an output element.

Usage

defineOutputElement(name, element)

Arguments

name

(character) Element name.

element

List with:

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

    • file (character) Path to the output file.

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

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

Details

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

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

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

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

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

Data frames can be used only to define output elements of type ‘common’, i.e the same for all individuals (potentially occasion-wise). If you want to define subject-specific output elements, you have to use an external file with an "id" column.

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

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

See Also

getOutputElements

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

name

(character) Element name.

element

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

  • file (character) Path to the population file.

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

Details

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

name

(character) Element name.

element

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

  • file (character) Path to the regressors file.

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

Details

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

The field data can be specified with a data frame or an external file (csv, xlsx, xlsx, sas7bdat, xpt or txt). They should contain a column time and a column for each regressor variable. They can contain columns occasions (optional). The occasion headers must correspond to the occasion names defined in the occasion element.

Data frames can be used only to define regressor elements of type ‘common’, i.e the same for all individuals (potentially occasion-wise). If you want to define subject-specific regressor elements, you have to use an external file with an additional "id" column.

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

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

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

See Also

getRegressorElements

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Define treatment element

Description

Define or edit a treatment element.

Usage

defineTreatmentElement(name, element)

Arguments

name

(character) Element name.

element

(list) List with the treatment settings:

data (mandatory) (data frame OR path to external file (csv, xlsx, xlsx, sas7bdat, xpt or txt) OR list to select the sheet of an excel file: list( file = path_to_excel, sheet = sheet_name )
Column headers:
  • [only data frame] for a regular treatment common to all ids:occ (optional, if common occasion structure, same header as in the occasion element), start, interval, nbDoses, amount

  • [only data frame] for a manual treatment common to all ids: occ (optional, if common occasion structure, same header as in the occasion element), time, amount, washout (optional, to add a washout just before the dose, otherwise washout = FALSE by default)

  • [only external file] for a manual treatment common or specific to each id: id (optional), occ (optional), time, amount, washout (optional)

  • [data frame or external] in case of infusion: tInf (duration) OR rate (mutually exclusive).

admID (optional) (integer) same as integer in the model as administration type
probaMissDose (optional) (double) probability to miss a dose (number in [0 1])
repeats (optional) (vector) to repeat the specified treatment after a specific duration.
Elements:
cycleDuration

duration after which the treatment will be repeated (can be longer than the treatment duration)

NumberOfRepetitions

number of times the treatment will be repeated

scale (optional) (list) to scale the dose amount by a covariate. The scaled amount will be administered instead of amount.
covariate

(character) covariate to use for scaling (same name as in the [COVARIATE] block of the model)

intercept

(double, required for continuous covariate): intercept to use in the scaling formula: scaledAmount = amount*cov + intercept

modalities

(list, required for categorical covariate): list of lists with, for each modality, the name of the modality (eg "male"), the factor, and the intercept to use in the scaling formula: scaledAmount = [cov = modality]*factor*amt + intercept (no scaling if factor =1 and intercept = 0)

scaleDuration

(optional, logical) if TRUE (default), infusion duration will be scaled, otherwise it will be rate

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Delete element

Description

Delete an element of any type.

Usage

deleteElement(name)

Arguments

name

(character) Element name.

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.

Click here to see examples

#

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

  loadProject(project_name)

  deleteElement(name = "mlx_CovDist")


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Delete an endpoint

Description

Delete an endpoint.

Usage

deleteEndpoint(name)

Arguments

name

(character) Endpoint name

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

Click here to see examples

#

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

loadProject(project_name)

deleteEndpoint("mean_NADIR")


Back to the list, PKanalix API, Monolix API, Simulx API.


[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.

Click here to see examples

#

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

  loadProject(project_name)

  deleteOccasionElement()


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Delete an outcome

Description

Delete an outcome.

Usage

deleteOutcome(name)

Arguments

name

(character) Outcome name

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“inputType” (character) Type of input definition: can be “manual”, “distribution” or “external”.
“file” (list) if the inputType is external, list with path to the file and sheet in the excel (if relevant) . NULL else wise.
“data” (data.frame) Values of the element.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

}


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“inputType” (character) Type of input definition: can be “manual” or “external”.
“file” (list) if the inputType is external, list with path to the file and sheet in the excel (if relevant) . NULL else wise.
“data” (data.frame) Values of the element.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“id” (character) Ids of the occasions
“names” (character) Name of the occasions. If empty, no occasions will be used in the project.
“times” (data.frame) Times of the occasions.
“occasions” (data.frame) Values of the element. If empty, no occasions will be used in the project.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Get outcome elements

Description

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

output (character) Name of the output element on which the outcome is based.
perOccasion (logical) If occasions are present in the simulation, it indicates if the outcome is calculated for each id or each occasion of each id.

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

relativeTo (list) List of elements that define reference settings:

  • reference – one of "baseline", "min", "max", "minCurrentTime", "maxCurrentTime" or "customValue",

  • type – "ratio" or "difference",

  • value – if reference is "customValue".

processing (list) List of elements that define how the output will be processed:

  • operator – one of "avg", "min", "max", "first", "last", "durationBelow", "durationAbove", "durationBetween" or "timePoint",

  • type

    • if operator is "min" or "max", one of "value", "timeContinuous" or "timeEvent",

    • if operator is "durationBelow", "durationAbove" or "durationBetween", one of "cumulativeTime", "percentTime", "nbObs", "firstOccurenceContinuous" or "firstOccurenceEvent",

  • value – vector of boundaries if operator is "durationBelow", "durationAbove" or "durationBetween", or time point if operator is "timePoint".

applyThreshold (list) List of elements:

  • operator – one of "==", "!=", ">=", ">", "<=" or "<",

  • value – a real number indicating the threshold value.

Or if the outcome is based on a TTE output:

event (list) List of arguments that define event settings:

  • type – one of "timeOfEvents" (in case of repeated TTE), "hasAnEvent", "hasNoEvent" (in case of single TTE) or "numberOf" (in case of repeated TTE),

  • rank – rank of the event of which time is the outcome (if type is "timeOfEvents").

Usage

getOutcomes()

See Also

defineOutcome

Click here to see examples

#

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

}


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“output” (character) Output name.
“inputType” (character) Type of input definition: can be “manual” or “external”.
“file” (list) if the inputType is external, list with path to the file and sheet in the excel (if relevant) . NULL else wise.
“data” (data.frame) Values of the element.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“inputType” (character) Type of input definition: can be “manual”, “distribution” or “external”.
“file” (list) if the inputType is external, list with path to the file and sheet in the excel (if relevant) . NULL else wise.
“data” (data.frame) Values of the element.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“inputType” (character) Type of input definition: can be “manual” or “external”.
“file” (list) if the inputType is external, list with path to the file and sheet in the excel (if relevant) . NULL else wise.
“data” (data.frame) Values of the element.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

“inputType” (character) Type of input definition: can be “manual” or “external”.
“file” (list) if the inputType is external, list with path to the file and sheet in the excel (if relevant) . NULL else wise.
“data” (data.frame) Values of the element as defined in defineTreatmentElement.
“admID” (integer) Administration id as defined in defineTreatmentElement.
“scale” (integer) information on scaling by covariates if defined in defineTreatmentElement.

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

Click here to see examples

#

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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Edit regressors settings

Description

Edit the regressors global settings.

Usage

setRegressorsSettings(method)

Arguments

method

(character): interpolation method for the regressors. Possible values: "lastCarriedForward" (default), "linearInterpolation".


[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

Click here to see examples

#

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

loadProject(project_name)

getGroupComparisonSettings()


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Set group comparison settings

Description

Set settings related to the comparison of endpoints across groups.

Usage

setGroupComparisonSettings(referenceGroup = NULL, enable = TRUE)

Arguments

referenceGroup

(character) (optional) Group to use as reference.

enable

(logical) (optional) Enable group comparison, TRUE by default.

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

Click here to see examples

#

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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Monolix – PKanalix – Simulx] Initialize lixoftConnectors API

Description

Initialize lixoftConnectors API for a given software.

Usage

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

Arguments

software

(character) [optional] Name of the software to be loaded. By default, "monolix" software is used.

path

(character) [optional] Path to installation directory of the Lixoft suite.
If lixoftConnectors library is not already loaded and no path is given, the directory written in the lixoft.ini file is used for initialization.

force

(logical) [optional] Should software switch security be overpassed or not. Equals FALSE by default.

Value

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

Click here to see examples

#

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

sourceModelFile

(character) Path to the model file. Can be absolute or relative.
Alternatively, the name of a library model (starting with "lib:"); see getLibraryModelName for a list of available models.

targetModelFile

(character) Path to the resulting file. Can be absolute or relative.

force

(logical) [optional] Should the resulting file be overwritten if already existing? Default: FALSE.

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.

Click here to see examples

#

   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.


Back to the list, PKanalix API, Monolix API, Simulx API.


[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.

Click here to see examples

#

  getDemoPath()

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

  loadProject(file_name)

  getAddLines()


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Add lines to the model.

Description

Add equations to the structural model.

Usage

setAddLines(lines)

Arguments

lines

(character) Additional lines to define.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

settings

(character) Export settings:

  • targetSoftware (character) Target software ("monolix" | "simulx" | "pkanalix")

  • filesNextToProject (logical) [optional][Monolix – PKanalix] Save data and/or structural model file next to exported project ([TRUE] | FALSE). Forced to TRUE for Simulx.

  • dataFilePath (character) [optional][Monolix – Simulx] Path (filesNextToProject == FALSE) or name (filesNextToProject == TRUE) of the exported data file. Available only for generated datasets in Monolix (vpc, individual fits)

  • dataFileType (character) [optional][Monolix] Dataset used in the exported project (["original"] | "vpc" | "individualFits")

  • modelFileName (character) [optional][Simulx] Name of the exported model file.

  • exportedUnusedCovariates (list) [optional][Monolix – PKanalix => Simulx] Covariates not used in the individual model (if present) to be exported to Simulx. A list with:

    • all (logical) Export all unused covariates. FALSE by default.

    • name (vector<character>) List of exported unused covariate names. Required if all == FALSE, ignored if not.

force

(logical) [optional] Should software switch security be overpassed or not. Equals FALSE by default.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


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

Description

Get the content of a library model.

Usage

getLibraryModelContent(filename, print = TRUE)

Arguments

filename

(character) The filename of the requested model. Can start with "lib:", end with ".txt", but neither are mandatory.

print

(logical) If TRUE (default), model’s content is printed with human-readable line breaks (alongside regular output with "\n").

Value

The model’s content as a single string.

Click here to see examples

#

getLibraryModelContent("oral1_1cpt_kaVCl")

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

library

(character) One of the MonolixSuite library of models. Possible values are "pk", "pd", "pkpd", "pkdoubleabs", "pm", "tmdd", "tte", "count" and "tgi".

filters

(list(name = character)) Named list of filters (optional), format: list(filterKey = "filterValue", …). Default empty list. Since available filters are not in any particular order, filterKey should always be stated.

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

key values
administration bolus, infusion, oral, oralBolus
delay noDelay, lagTime, transitCompartments
absorption zeroOrder, firstOrder
distribution 1compartment, 2compartments, 3compartments
elimination linear, MichaelisMenten
parametrization rate, clearance, hybridConstants
bioavailability true, false

PD library

key values
response immediate, turnover
drugAction linear, logarithmic, quadratic, Emax, Imax, productionInhibition,
degradationInhibition, degradationStimulation, productionStimulation
baseline const, 1-exp, exp, linear, null
inhibition partialInhibition, fullInhibition
sigmoidicity true, false

PKPD library

key values
administration bolus, infusion, oral, oralBolus
delay noDelay, lagTime, transitCompartments
absorption zeroOrder, firstOrder
distribution 1compartment, 2compartments, 3compartments
elimination linear, MichaelisMenten
parametrization rate, clearance
bioavailability true, false
response direct, effectCompartment, turnover
drugAction Emax, Imax, productionInhibition, degradationInhibition,
degradationStimulation, productionStimulation
baseline const, null
inhibition partialInhibition, fullInhibition
sigmoidicity true, false

PK double absorption library

key values
firstAbsorption zeroOrder, firstOrder
firstDelay noDelay, lagTime, transitCompartments
secondAbsorption zeroOrder, firstOrder
secondDelay noDelay, lagTime, transitCompartments
absorptionOrder simultaneous, sequential
forceLongerDelay true, false
distribution 1compartment, 2compartments, 3compartments
elimination linear, MichaelisMenten
parametrization rate, clearance

Parent-metabolite library

key values
administration bolus, infusion, oral, oralBolus
firstPassEffect noFirstPassEffect, withDoseApportionment,
withoutDoseApportionment
delay noDelay, lagTime, transitCompartments
absorption zeroOrder, firstOrder
transformation unidirectional, bidirectional
parametrization rate, clearance
parentDistribution 1compartment, 2compartments, 3compartments
parentElimination linear, MichaelisMenten
metaboliteDistribution 1compartment, 2compartments, 3compartments
metaboliteElimination linear, MichaelisMenten

TMDD library

key values
administration bolus, infusion, oral, oralBolus
delay noDelay, lagTime, transitCompartments
absorption zeroOrder, firstOrder
distribution 1compartment, 2compartments, 3compartments
tmddApproximation MichaelisMenten, QE, QSS, full, Wagner,
constantRtot, constantRtotIB, irreversibleBinding
output totalLigandLtot, freeLigandL
parametrization rate, clearance

TTE library

key values
tteModel exponential, Weibull, Gompertz, loglogistic,
uniform, gamma, generalizedGamma
delay true, false
numberOfEvents singleEvent, repeatedEvents
typeOfEvent intervalCensored, exact
dummyParameter true, false

Count library

key values
countDistribution Poisson, binomial, negativeBinomial, betaBinomial,
generalizedPoisson, geometric, hypergeometric,
logarithmic, Bernoulli
zeroInflation true, false
timeEvolution constant, linear, exponential, Emax, Hill
parametrization probabilityOfSuccess, averageNumberOfCounts

TGI library

key values
shortcut ClaretExponential, Simeoni, Stein, Wang,
Bonate, Ribba, twoPopulation
initialTumorSize asParameter, asRegressor
kinetics true, false
model linear, quadratic, exponential, generalizedExponential,
exponentialLinear, Simeoni, Koch, logistic,
generalizedLogistic, SimeoniLogisticHybrid, Gompertz,
exponentialGompertz, vonBertalanffy, generalizedVonBertalanffy
additionalFeature none, angiogenesis, immuneDynamics
treatment none, pkModel, exposureAsRegressor, startAtZero,
startTimeAsRegressor, armAsRegressor
killingHypothesis logKill, NortonSimon
dynamics firstOrder, MichaelisMenten, MichaelisMentenHill,
exponentialKill, constant
resistance ClaretExponential, resistantCells, none
delay signalDistribution, cellDistribution, none
additionalTreatmentEffect none, angiogenesisInhibition, immuneEffectorDecay

Value

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

Click here to see examples

#

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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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:

CURRENT SOFTWARE ALLOWED IMPORTS
Monolix PKanalix
PKanalix Monolix, Datxplore
Simulx Monolix, PKanalix.

Usage

importProject(projectFile)

Arguments

projectFile

(character) Path to the project file. Can be absolute or relative
to the current working directory.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

projectFile

(character) Path to the project file. Can be absolute or relative to the current working directory.

See Also

saveProject, importProject, exportProject, newProject

Click here to see examples

#

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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

modelFile

(character) Path to the model file. Mandatory for Monolix and Simulx, optional for PKanalix (used only for the CA part). Can be absolute or relative to the current working directory.
To use a model from the libraries, you can find the model name with getLibraryModelName and set modelFile = "lib:modelName.txt" with the name obtained.
To simulate inter-individual variability in Simulx with a new project, the model file has to include the statistical model, contrary to Monolix and PKanalix for which the model file only contains the structural model. Check here in detail how to write such a model from scratch.

data

(list) Structure describing the data. Mandatory for Monolix and PKanalix.

  • dataFile (character): Path to the data file (csv, xlsx, xlsx, sas7bdat, xpt or txt). Can be absolute or relative to the current working directory.

  • sheet [optional] (character): Name of the sheet in xlsx/xls file. If not provided, the first sheet is used.

  • headerTypes (vector<character>): A vector of header types. The possible header types are: "ignore", "id", "time", "observation", "amount", "contcov", "catcov", "occ", "evid", "mdv", "obsid", "cens", "limit", "regressor", "nominaltime", "admid", "rate", "tinf", "ss", "ii", "addl", "date". Notice that these are not exactly the types displayed in the interface, they are shortcuts.

  • observationTypes [optional] (list): A list giving the type of each observation present in the data file. If there is only one y-type, the corresponding observation name can be omitted. The possible observation types are "continuous", "discrete", and "event".

  • nbSSDoses (integer): Number of doses (if there is a SS column for steady-state).

  • regressorsSettings [optional] (character): Regressors interpolation method. Either ‘lastCarriedForward’ (default) or ‘linearInterpolation’.

mapping

[optional](list): A list of lists representing a link between observation types and model outputs. Each list contains:

  • obsId (character) Name of observation id present in the dataset. It corresponds to the content of column tagged as "obsid" in case of several obs ids, or to the header of the column tagged as "observation" otherwise

  • observationName (character) Name of the model prediction listed in the output= line of the structural model

  • modelOutput [Monolix] (character) Name of the observation, e.g "y1" (for continuous observations only)

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

projectFile

[optional](character) Path where to save a copy of the current mlxtran model. Can be absolute or relative to the current working directory.
If no path is given, the file used to build the current configuration is updated.

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Monolix – PKanalix – Simulx] Share project.

Description

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

Usage

shareProject(archiveFile)

Arguments

archiveFile

(character) Path to the .zip archive file to create.

Click here to see examples

#

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Monolix – PKanalix – Simulx] Get console mode

Description

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

“none” no output
“basic” at the end of each algorithm, associated results are displayed
“complete” each algorithm iteration and/or status is displayed

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:

“relativepath” (logical) Use relative path for save/load operations.
“threads” (integer > 0) Number of threads.
“temporarydirectory” (character) Path to the directory used to save temporary files.
“usebinarydataset” (logical) Save dataset as binary file to speed project reload up.
“timestamping” (logical) Create an archive containing result files after each run.
“delimiter” (character) Character use as delimiter in exported result files.
“reportingrenamings” (list("label" = "alias">)) For each label, an alias to be use at report generation (using generateReport).
“exportchartsdata” (logical) Should charts data be exported.
“savebinarychartsdata” (logical) [Monolix] Save charts simulations as binray file to speed charts creation up.
“exportchartsdatasets” (logical) [Monolix] Should charts datasets be exported if possible.
“exportvpcsimulations” (logical) [Monolix] Should vpc simulations be exported if possible.
“exportsimulationfiles” (logical) [Simulx] Should simulation results files be exported.
“headeraliases” (list("header" = vector<character>)) For each header, the list of the recognized aliases.
“ncaparameters” (vector<character>) [PKanalix] Defaulty computed NCA parameters.
“units” (list("type" = character) [PKanalix] Time, amount and/or volume units.

Usage

getPreferences(...)

Arguments

...

[optional] (character) Name of the preference whose value should be displayed. If no argument is provided, all the preferences are returned.

Value

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

Click here to see examples

#

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

getPreferences("imageFormat","exportCharts") 

# retrieve only the imageFormat and exportCharts settings values

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Monolix – PKanalix – Simulx] Get project settings

Description

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

“directory” (character) Path to the folder where simulation results will be saved. It should be a writable directory.
“exportResults” (logical) Should results be exported.
“seed” (0 < integer < 2147483647) Seed used by random generators.
“grid” (integer) Number of points for the continuous simulation grid.
“nbSimulations” (integer) Number of simulations.
“dataandmodelnexttoproject” (logical) Should data and model files be saved next to project.
“project” (character) Path to the Monolix project.

Associated settings for PKanalix projects are:

“directory” (character) Path to the folder where simulation results will be saved. It should be a writable directory.
“seed” (0 < integer < 2147483647) Seed used by random generators.
“datanexttoproject” (logical) Should data and model (in case of CA) files be saved next to project.

Associated settings for Simulx projects are:

“directory” (character) Path to the folder where simulation results will be saved. It should be a writable directory.
“seed” (0 < integer < 2147483647) Seed used by random generators.
“userfilesnexttoproject” (logical) Should user files be saved next to project.

Usage

getProjectSettings(...)

Arguments

...

[optional] (character) Name of the settings whose value should be displayed. If no argument is provided, all the settings are returned.

Value

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

See Also

setProjectSettings

Click here to see examples

#

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Monolix – PKanalix – Simulx] Set console mode

Description

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

“none” no output
“basic” for each algorithm, display current iteration then associated results at algorithm end
“complete” display all iterations then associated results at algorithm end

Usage

setConsoleMode(mode)

Arguments

mode

(character) Accepted values are: "none" [default], "basic", "complete"

See Also

getConsoleMode


[Monolix – PKanalix – Simulx] Set preferences

Description

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

“relativepath” (logical) Use relative path for save/load operations.
“threads” (integer > 0) Number of threads.
“temporarydirectory” (character) Path to the directory used to save temporary files.
“usebinarydataset” (logical) Save dataset as binary file to speed project reload up.
“timestamping” (logical) Create an archive containing result files after each run.
“delimiter” (character) Character use as delimiter in exported result files.
“reportingrenamings” (list("label" = "alias")) For each label, an alias to be use at report generation (using generateReport).
“exportchartsdata” (logical) Should charts data be exported.
“savebinarychartsdata” (logical) [Monolix] Save charts simulations as binray file to speed charts creation up.
“exportchartsdatasets” (logical) [Monolix] Should charts datasets be exported if possible.
“exportvpcsimulations” (logical) [Monolix] Should vpc simulations be exported if possible.
“exportsimulationfiles” (logical) [Simulx] Should simulation results files be exported.
“headeraliases” (list("header" = vector<character>)) For each header, the list of the recognized aliases.
“ncaparameters” (vector<character>) [PKanalix] Defaulty computed NCA parameters.
“units” (list("type" = character) [PKanalix] Time, amount and/or volume units.

Usage

setPreferences(...)

Arguments

...

A collection of comma-separated pairs {preferenceName = settingValue}.

See Also

getPreferences

Click here to see examples

#

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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:

“directory” (character) Path to the folder where simulation results will be saved. It should be a writable directory.
“exportResults” (logical) Should results be exported.
“seed” (0 < integer < 2147483647) Seed used by random generators.
“grid” (integer) Number of points for the continuous simulation grid.
“nbSimulations” (integer) Number of simulations.
“dataandmodelnexttoproject” (logical) Should data and model files be saved next to project.

Associated settings for PKanalix projects are:

“directory” (character) Path to the folder where simulation results will be saved. It should be a writable directory.
“dataNextToProject” (logical) Should data and model (in case of CA) files be saved next to project.
“seed” (0 < integer < 2147483647) Seed used by random generators.

Associated settings for Simulx projects are:

“directory” (character) Path to the folder where simulation results will be saved. It should be a writable directory.
“seed” (0 < integer < 2147483647) Seed used by random generators.
“userfilesnexttoproject” (logical) Should user files be saved next to project.

Usage

setProjectSettings(...)

Arguments

...

A collection of comma-separated pairs {settingName = settingValue}.

See Also

getProjectSettings

Click here to see examples

#

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

filePath

[optional](character) Custom path for the exported file. By default, it is written in the results folder of the current project, next to simulation results files. The default file name is simulatedData.csv.

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

Click here to see examples

#

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

 loadProject(project_name)

 runSimulation()

 exportSimulatedData()


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

id

[optional](character) If provided, results are retrieved only for this id.

rep

[optional](integer) If provided, results are retrieved only for this replicate.

See Also

runSimulation

Click here to see examples

#

 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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

plot

(character) [optional][Monolix] Plot type. If not specified, all the available project plots will be considered. Available plots: bivariatedataviewer, covariateviewer, outputplot, indfits, obspred, residualsscatter, residualsdistribution, vpc, npc, predictiondistribution, parameterdistribution, randomeffects, covariancemodeldiagnosis, covariatemodeldiagnosis, likelihoodcontribution, fisher, saemresults, condmeanresults, likelihoodresults.

output

(character) [optional][Monolix] Plotted output (depending on the software, it can represent an observation, a simulation output, …). By default, all available outputs are considered.

exportVPCSimulations

(logical) [optional][Monolix] Should VPC simulations be exported if available. Equals FALSE by default.
NOTE: If ‘plot" argument is not provided, ‘output’ and "task’ arguments are ignored.

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

Click here to see examples

#

computeChartsData() # Monolix - PKanalix - Simulx

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

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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:

Algorithm Algorithm Keyword
Population Parameter Estimation “populationParameterEstimation”
Conditional Mode Estimation (EBEs) “conditionalModeEstimation”
Sampling from the Conditional Distribution “conditionalDistributionSampling”
Standard Error and Fisher Information Matrix Estimation “standardErrorEstimation”
LogLikelihood Estimation “logLikelihoodEstimation”
Plots “plots”

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:

Algorithm Algorithm keyword
Non Compartmental Analysis “nca”
Bioequivalence estimation “be”

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:

Algorithm Algorithm keyword
Simulation “simulation”
Outcomes and endpoints “endpoints”

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

runScenario()

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Monolix – PKanalix – Simulx] Set scenario

Description

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

Usage

setScenario(...)

Arguments

...

A list of tasks as previously defined

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:

Algorithm Algorithm Keyword
Population Parameter Estimation “populationParameterEstimation”
Conditional Mode Estimation (EBEs) “conditionalModeEstimation”
Sampling from the Conditional Distribution “conditionalDistributionSampling”
Standard Error and Fisher Information Matrix Estimation “standardErrorEstimation”
LogLikelihood Estimation “logLikelihoodEstimation”
Plots “plots”

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:

Algorithm Algorithm keyword
Non Compartmental Analysis “nca”
Bioequivalence estimation “be”

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:

Algorithm Algorithm keyword
Simulation “simulation”
Outcomes and endpoints “endpoints”

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.

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Add simulation group

Description

Add a new simulation group.

Usage

addGroup(group)

Arguments

group

(character) Name of the group to add.

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

Click here to see examples

#

  initializeLixoftConnectors("simulx")

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

  loadProject(project_name)

  addGroup("simulationGroup2")

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

group

(character) Group name

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

  loadProject(project_name)

  getNbReplicates()


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

  loadProject(project_name)

  getSameIndividualsAmongGroups()


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

  loadProject(project_name)

  getSamplingMethod()


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

  loadProject(project_name)

  getSharedIds()


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Remove simulation group

Description

Remove a simulation group.

Usage

removeGroup(group)

Arguments

group

(character) Name of the group to remove.

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

Click here to see examples

#

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

  loadProject(project_name)

  removeGroup("medium_dose")


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Remove element from simulation group

Description

Remove an element from a simulation group.

Usage

removeGroupElement(group, element)

Arguments

group

(character) Group name

element

(character) Element to remove

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Rename simulation group

Description

Rename a simulation group.

Usage

renameGroup(currentGroupName, newGroupName)

Arguments

currentGroupName

(character) Name of the current group name.

newGroupName

(character) Name of the new group name.

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

Click here to see examples

#

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

  loadProject(project_name)

  renameGroup("simulationGroup1", "two_doses")


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Run endpoints task

Description

Run the endpoints task.

Usage

runEndpoints()

See Also

getEndpointsResults

Click here to see examples

#

  runEndpoints()

## End(Not run)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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

  loadProject(project_name)

  setConsoleMode("basic")

  runSimulation()


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

group

(character) Group name (when creating a new Simulx project, the default group name is "simulationGroup1").

elements

(character) Vector of elements that are already defined

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

group

(character) Group name

remaining

(vector) list of the remaining variables

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Set simulation group size

Description

Define the size of a simulation group.

Usage

setGroupSize(group, size)

Arguments

group

(character) Name of the group where the size will be changed.

size

(integer) Size of the new group.

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

Click here to see examples

#

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

  loadProject(project_name)

  setGroupSize("gr_BID_N30", 40)

  setGroupSize("gr_OD_N30", 40)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Set number of replicates

Description

Define the number of replicates of the simulation.

Usage

setNbReplicates(nb)

Arguments

nb

(integer) Number of replicates.

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

Click here to see examples

#

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

  loadProject(project_name)

  setNbReplicates(nb = 20)


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Set same individuals among groups

Description

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

Usage

setSameIndividualsAmongGroups(value)

Arguments

value

(logical) logical to define if the same individuals will be the same for all groups.

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

Click here to see examples

#

  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)


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

method

(character) keepOrder, withReplacement, withoutReplacement

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

Click here to see examples

#

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

  loadProject(project_name)

  setSamplingMethod(method = "withReplacement")


Back to the list, PKanalix API, Monolix API, Simulx API.


[Simulx] Set element types sharing individuals

Description

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

Usage

setSharedIds(sharedIds)

Arguments

sharedIds

(vector<character>) List of element types. The available types are: covariate, output, treatment, regressor, population, individual

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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.


[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

Click here to see examples

#

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


Back to the list, PKanalix API, Monolix API, Simulx API.

modal close image