R functions to run Monolix

On the use of the R-functions

We now propose to use Monolix 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.

Notes

  • Due to possible conflicts, the package mlxR, whose function simulx can be used to perform simulations with Monolix, should not be loaded at the same time as lixoftConnectors.
  • Running the plots task with the API saves the charts data in the result folder, if “Export charts data” is selected in Monolix’s preferences. The plots can only be generated with the Monolix GUI.

 

Description of the functions concerning the covariate model

Description of the functions concerning the individual model

Description of the functions concerning the observation model

  • getContinuousObservationModel: Get a summary of the information concerning the continuous observation models in the project.
  • getObservationInformation: Get the name, the type and the values of the observations present in the project.
  • setAutocorrelation: Add or remove auto-correlation from the error model used on some of the observation models.
  • setErrorModel: Set the error model type to be used with some of the observation models.
  • setObservationDistribution: Set the distribution in the Gaussian space of some of the observation models.
  • setObservationLimits: Set the minimum and the maximum values between which some of the observations can be found.

Description of the functions concerning the population parameters

  • getPopulationParameterInformation: Get the name, the initial value, the estimation method and, if relevant, MAP parameters value of the population parameters present in the project.
  • setInitialEstimatesToLastEstimates: Set the initial value of all the population parameters present within the current project (fixed effects + individual variances + error model parameters) to the ones previously estimated.
  • setPopulationParameterInformation: Set the initial value, the estimation method and, if relevant, the MAP parameters of one or several of the population parameters present within the current project (fixed effects + individual variances + error model parameters).

Description of the functions concerning the project management

  • getData: Get a description of the data used in the current project.
  • getStructuralModel: Get the model file for the structural model used in the current project.
  • loadProject: Load a project by parsing the mlxtran-formated file whose path has been given as an input.
  • newProject: Create a new empty project providing model and data specification.
  • saveProject: Save the current project as an Mlxtran-formated file.
  • setData: Set project data giving a data file and specifying headers and observations types.
  • setStructuralModel: Set the structural model.

Description of the functions concerning the results

  • getCorrelationOfEstimates: Get the inverse of the last estimated Fisher matrix computed either by all the Fisher methods used during the last scenario run or by the specific one passed in argument.
  • getEstimatedIndividualParameters: Get the last estimated values for each subject of some of the individual parameters present within the current project.
  • getEstimatedLogLikelihood: Get the values computed by using a log-likelihood algorithm during the last scenario run, with or without a method-based filter.
  • getEstimatedPopulationParameters: Get the last estimated value of some of the population parameters present within the current project (fixed effects + individual variances + correlations + latent probabilities + error model parameters).
  • getEstimatedRandomEffects: Get the random effects for each subject of some of the individual parameters present within the current project.
  • getEstimatedStandardErrors: Get the last estimated standard errors of population parameters computed either by all the Fisher methods used during the last scenario run or by the specific one passed in argument.
  • getLaunchedTasks: Get a list of the tasks which have results to provide.
  • getSAEMiterations: Retrieve the successive values of some of the population parameters present within the current project (fixed effects + individual variances + correlations + latent probabilities + error model parameters) during the previous run of the SAEM algorithm.
  • getSimulatedIndividualParameters: Get the simulated values for each replicate of each subject of some of the individual parameters present within the current project.
  • getSimulatedRandomEffects: Get the simulated values for each replicate of each subject of some of the individual random effects present within the current project.

Description of the functions concerning the scenario

Description of the functions concerning model building tasks

Description of the functions concerning the settings

 

Examples

  • Simple example to load an existing project, run SAEM and print the number of iterations used in the exploratory and smoothing phases:
# load and initialize the API
library(lixoftConnectors) 
initializeLixoftConnectors(software="monolix")

demoPath = 'C:/Users/username/lixoft/monolix/monolix2019R1/demos/1.creating_and_using_models/1.1.libraries_of_models/'
project <- paste0(demoPath, "theophylline_project.mlxtran"
loadProject(projectFile = project)

runPopulationParameterEstimation()
iter <- getSAEMiterations()
print(paste0("Iterations in exploratory phase: ",iter$iterationNumbers[1]))
print(paste0("Iterations in smoothing phase: ",iter$iterationNumbers[2]))

 

  • Example of the functions to call to build a project from scratch using one of the demo data sets and a model from the libraries, and run a convergence assessment to evaluate the robustness of the convergence:
# load and initialize the API
library(lixoftConnectors)
initializeLixoftConnectors(software="monolix")

# create a new project by setting a data set and a structural model
# replace <userFolder> by the path to your home directory
demoPath = 'C:/Users/username/lixoft/monolix/monolix2019R1/demos/1.creating_and_using_models/1.1.libraries_of_models/'
librariesPath = 'C:/ProgramData/Lixoft/MonolixSuite2019R1/factory/library/pk'
newProject(data = list(dataFile = paste0(demoPath,'data/warfarin_data.txt'),
                       headerTypes =c("id", "time", "amount", "observation", "obsid", "contcov", "catcov", "ignore"),
                       observationTypes = list(y1 = "continuous", y2 = "continuous" ),
                       mapping = list("1" = "y1")),
           modelFile = paste0(librariesPath,'/oral1_1cpt_TlagkaVCl.txt'))

# set tasks in scenario
scenario <- getScenario()
scenario$tasks = c(populationParameterEstimation = T, 
                   conditionalModeEstimation = T, 
                   conditionalDistributionSampling = T, 
                   standardErrorEstimation=T, 
                   logLikelihoodEstimation=T)
scenario$linearization = TRUE
setScenario(scenario)

# --------------------------------------------------------------------------
# convergence assessment: run 5 estimations with different initial estimates
# store the results in tabestimates
# --------------------------------------------------------------------------
popparams <- getPopulationParameterInformation()
tabestimates <- NULL; tabse <- NULL
for(i in 1:5){
   # sample new initial estimates
   popini <- sapply(1:nrow(popparams), function(j){runif(n=1, min=popparams$initialValue[j]/2, max=popparams$initialValue[j]*2)})

   # set sampled values as new initial estimates
   newpopparams <- popparams
   newpopparams$initialValue <- popini
   setPopulationParameterInformation(newpopparams)

   # run the estimation
   runScenario()

   # store the estimates and s.e. in table
   tabestimates <- cbind(tabestimates, getEstimatedPopulationParameters())
   tabse <- cbind(tabse, getEstimatedStandardErrors()$stochasticApproximation)
}

 

The table of estimates can then be further analyzed using typical R functions, and printed or plotted.

 

Handling of warning/error/info messages

Error, warning and info messages from Monolix are displayed in the R console when performing actions on a monolix project. They can be hidden via the R options. Set lixoft_notificationOptions$errors, lixoft_notificationOptions$warnings and lixoft_notificationOptions$info to 1 or 0 to respectively hide or show the messages.

 

Example

op = options()
op$lixoft_notificationOptions$warnings = 1   #hide the warning messages
options(op)