R functions to run Monolix

• On the use of the R functions
  • Description of the functions concerning the covariate model
  • Description of the functions concerning the individual model
  • Description of the functions concerning the observation model
  • Description of the functions concerning the population parameters
  • Description of the functions concerning the project management
  • Description of the functions concerning the results
  • Description of the functions concerning the plots
  • Description of the functions concerning the scenario
  • Description of the functions concerning model building tasks
  • Description of the functions concerning the settings
• Examples using R functions
• Handling of warning/error/info messages

 

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 of lixoftConnectors are described below. To go beyond what the interface allows, the Rsmlx package provides additional functions for automatic PK model building, bootstrap simulation and likelihood profiling, among others.

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

• addCategoricalTransformedCovariate: Create a new categorical covariate by transforming an existing one.
• addContinuousTransformedCovariate: Create a new continuous covariate by transforming an existing one.
• addMixture: Add a new latent covariate to the current model giving its name and its modality number.
• removeCovariate: Remove some of the transformed covariates (discrete and continuous) and/or latent covariates.

Description of the functions concerning the individual model

• getIndividualParameterModel: Get a summary of the information concerning the individual parameter model.
• getVariabilityLevels: Get a summary of the variability levels (inter-individual and/or intra-individual variability) present in the current project.
• setCorrelationBlocks: Define the correlation block structure associated to some of the variability levels of the current project.
• setCovariateModel: Set which are the covariates influencing individual parameters present in the project.
• setIndividualLogitLimits: Set the minimum and the maximum values between the individual parameter can be used.
• setIndividualParameterDistribution: Set the distribution of the estimated parameters.
• setIndividualParameterModel: Set the information concerning the individual parameter model.
• setIndividualParameterVariability: Add or remove inter-individual and/or intra-individual variability from some of the individual parameters present in the project.

Description of the functions concerning the observation model

• getContinuousObservationModel: Get a summary of the information concerning the continuous observation models 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

• getFixedEffectsByAutoInit: Compute optimized values for initial 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 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.
• getInterpretedData: Get the data interpreted by Monolix.
• getStructuralModel: Get the model file for the structural model used in the current project.
• isProjectLoaded: Check if the project is loaded.
• 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.
• getTests: Get the results of performed statistical tests.

Description of the functions concerning the plots

• getChartsData: Get the charts data.
• plotBivariateDataViewer: Plot the bivariate viewer.
• plotCovariates: Plot the covariates.
• plotObservedData: Plot the observed data.
• plotIndividualFits: Plot the individual fits.
• plotObservationsVsPredictions: Plot the observations versus prediction.
• plotResidualsDistribution: Plot the residual distribution.
• plotResidualsScatterPlot: Plot the scatter plot of the residuals.
• plotParametersDistribution: Plot the parameter distribution.
• plotParametersVsCovariates: Plot the parameters vs covariates.
• plotRandomEffectsCorrelation: Plot the random effects correlation.
• plotStandardizedRandomEffectsDistribution: Plot the standardized random effect distribution.
• plotBlqPredictiveCheck: Plot the predictive BLQ check.
• plotNpc: Plot the NPC.
• plotPredictionDistribution: Plot the prediction distribution.
• plotVpc: Plot the VPC.
• plotImportanceSampling: Plot the Importance Sampling task results.
• plotMCMC: Plot the MCMC task results.
• plotSaem: Plot the SAEM task results.
• getPlotPreferences: Get the Plot prerefences.
• resetPlotPreferences: Reset the plot preferences.
• setPlotPreferences: Set the plot preferences.

Description of the functions concerning the scenario

• runConditionalDistributionSampling: Estimate the individual parameters using conditional distribution sampling algorithm.
• runConditionalModeEstimation: Estimate the individual parameters using the conditional mode estimation algorithm (EBEs).
• runLogLikelihoodEstimation: Run the log-Likelihood estimation algorithm.
• runPopulationParameterEstimation: Estimate the population parameters with the SAEM method.
• runStandardErrorEstimation: Estimate the Fisher Information Matrix and the standard errors of the population parameters.
• computeChartsData: Compute and export the charts data of scenario.
• getLastRunStatus: Return an execution report about the last run with a summary of the error which could have occurred.
• getScenario: For Monolix, get the list of tasks that will be run at the next call to runScenario, the associated method (linearization true or false), and the associated list of plots.
• runScenario: For Monolix, run the current scenario.
• setScenario: For Monolix, clear the current scenario and build a new one from a given list of tasks, the linearization option and the list of plots.

Description of the functions concerning model building tasks

• runModelBuilding: Run the model building task
• getModelBuildingSettings: Get the settings that will be used during the run of model building
• getModelBuildingResults: Get the results (detailed models) of the model building

Description of the functions concerning the settings

• getConditionalDistributionSamplingSettings: Get the conditional distribution sampling settings.
• getConditionalModeEstimationSettings: Get the conditional mode estimation settings.
• getConsoleMode: .
• getGeneralSettings: Get a summary of the common settings for Monolix algorithms.
• getLogLikelihoodEstimationSettings: Get the loglikelihood estimation settings.
• getMCMCSettings: Get the MCMC algorithm settings of the current project.
• getPopulationParameterEstimationSettings: Get the population parameter estimation settings.
• getStandardErrorEstimationSettings: Get the standard error estimation settings.
• setConditionalDistributionSamplingSettings: Set the value of one or several of the conditional distribution sampling settings.
• setConditionalModeEstimationSettings: Set the value of one or several of the conditional mode estimation settings.
• setConsoleMode: .
• setGeneralSettings: Set the value of one or several of the common settings for Monolix algorithms.
• setLogLikelihoodEstimationSettings: Set the value of the loglikelihood estimation settings.
• setMCMCSettings: Set the value of one or several of the MCMC algorithm specific settings of the current project.
• setPopulationParameterEstimationSettings: Set the value of one or several of the population parameter estimation settings.
• setStandardErrorEstimationSettings: Set the value of one or several of the standard error estimation settings.
• getPreferences: Get a summary of the project preferences.
• getProjectSettings: Get a summary of the project settings.
• setPreferences: Set the value of one or several of the project preferences.
• setProjectSettings: Set the value of one or several of the settings of the project.

 

Examples using R functions

• Page with all examples
  • Load and run a project
  • Convergence assessment
  • Profile likelihood
  • Bayesian individual dynamic predictions
  • Covariate search
  • Generate plots in R

 

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)