RsSimulx is a R package which offers two main functionalities:
- ensure the retrocompatibility of existing mlxR scripts with the MonolixSuite version 2020R1, in particular via the function
- provide functions to complement the use of Simulx 2020R1 (used via the GUI or the lixoftConnectors), in particular:
RsSimulx is available on CRAN but it requires the lixoftConnectors package which is provided within the MonolixSuite installation. In addition RJSONIO (available on CRAN) is required.
Installation of RJSONIO (from CRAN)
Installation of the lixoftConnectors
The lixoftConnectors are not available on CRAN. The installation package is located in the MonolixSuite installation directory. The default path to the installation directory differs between operating systems. You may have to adapt the path if you have chosen another installation directory.
# for Windows install.packages("C:/ProgramData/Lixoft/MonolixSuite2020R1/connectors/lixoftConnectors.tar.gz", repos = NULL, type="source
# for MAC OS install.packages("/Applications/MonolixSuite2020R1.app/Contents/Resources/monolixSuite/connectors/lixoftConnectors.tar.gz", repos = NULL, type="source", INSTALL_opts ="--no-multiarch") # for Linux install.packages("/home/<your username>/Lixoft/MonolixSuite2020R1/connectors/lixoftConnectors.tar.gz", repos = NULL, type="source", INSTALL_opts ="--no-multiarch")
Installation of RsSimulx
install.packages("RsSimulx", INSTALL_opts ="--no-multiarch")
Version 1.0.0 (released on CRAN on January 21st 2021)
RsSimulx is compatible with the MonolixSuite version 2020R1.
Version 1.0.1 (coming soon)
- The initialization of the lixoftConnectors (i.e linking to the MonolixSuite installation folder) is now done on the first call to simulx() instead of the loading of the RsSimulx package.
- The new function initRsSimulx(path=…) allows to indicate a path to the MonolixSuite installation folder when the <home>/lixoft/lixoft.ini file is missing or needs to be bypassed.
- Messages, warnings and errors raised by the lixoftConnectors are now propagated to RsSimulx such that the user can see them.
- Columns “type” or “adm” for treatments defined as data.frames are now properly recognized (they where previously ignored).
- When both population parameters and covariates are given in the “parameter=” argument of simulx(), the covariates are now properly taken into account (they were previously ignored).
- The seed given to simulx() now propagates to simpopmlx, which is sampling the population parameters when using the argument “npop” (previously the reproducibility was not ensured when using npop).
- The use of a named vector with only characters (typically in the case of categorical-only covariates defined as strings) does not generate an error any more.
When population parameters are defined as a data.frame with a column “pop”, the dataframe is now used with the correct number of rows (it was previously cut or replicated to match the npop argument).
- When npop is used but no treatment is present, no error is raised anymore.
- When the “parameter” argument is defined as a named vector with both characters (for categorical covariates for instance) and numerical values, no error is raised anymore.
RsSimulx for retrocompatibility of mlxR scripts
RsSimulx contains a function simulx() which works in the same way as the simulx() function of the mlxR package. To use your scripts initially developped with mlxR with MonolixSuite 2020R1, you need to replace library(mlxR) by library(RsSimulx) and run the rest of your script as before.
A few functions and features which were available in the mlxR package are not available in the RsSimulx package anymore, due to technical constrains. They are listed below.
- the following functions have been removed:
- the following arguments have been removed from the simulx() function
- in “treatment=”, the “target” field is not accepted anymore. Use “adm” instead.
- in “group=”, the “level” field is not accepted anymore, unless it is equal to “individual”. With RsSimulx, the variability is always at the individual level.
- The following outputs have been removed:
- originalID data frame
Modifications requiring small code adaptations
- the individual parameters are covariates are now outputted by default in the ‘parameter’ argument. It is not necessary to request them explicitly.
- the writeDataMlx() function has been replaced by the function writeData() which is called without R object as input. When called just after a simulx() call, it will use the simulx project in memory to write the data set. Note that the ‘loq’ will not be taken into account.
- overlapping occasions are now supported but when the occasion element has an id column, all elements must follow this occasions structure. See the occasion definition in Simulx-GUI for more details.
- for time-to-event outputs, it is now required to give a vector of two times (start and end of the observation period) instead of only the start time:
out <- list(name="Event", time=c(0, 400))
- Negative amount with positive infusion rates are not possible anymore. Use the reset or empty macros instead.
- it is not possible to define distributions in the [COVARIATE] or [POPULATION] block anymore. Instead, sample the covariates or population parameters in the R script and provide them as a data frame.
- in the model, to properly identify covariates, individual parametes and population parameters, they must be declared in the corresponding block. The model structure is detailed on the mlxtran page.
Known issues (will be corrected in MonolixSuite 2020R2)
- regressor values are not outputted from simulx()
- when just resimulating a Monolix project, in case of both continuous and non-continuous outputs, only the continuous outputs are outputted.
- when just resimulating a Monolix project, the individuals having no observations for some obs ids (in case of several observation identifiers) or no dose will be missing from the simulation.
Running the same script with RsSimulx or mlxR will lead to different simulated values because the seed is read in a different way by the two packages. When running the same script several times with RsSimulx, the simulated values will be the same.
RsSimulx to complement Simulx 2020R1
When Simulx is used via the GUI (or the lixoftConnectors), three functions of the RsSimulx package can be useful:
- writeData() to write the simulation results to a MonolixSuite compatible format
- simpopmlx() to generate sets of population parameters from their uncertainty distribution caracterized by the Fisher Information Matrix estimated by Monolix
- prctilemlx() to replot prediction intervals with overlay of the groups on a single plot
writeData(): write simulations to MonolixSuite data set format
Format outputs of simulx simulations and write datasets in monolix and pkanalix project format.
writeData( project = NULL, filename = "simulated_dataset.csv", sep = ",", ext = "csv", nbdigits = 5 )
||(string) a simulx project with extension .smlx.
If no project is specified, the function will run on the project that is already loaded.
||(string) (optional) file path to dataset.
In case of multiple replicates, the function creates one dataset per replicate with name $filename_repi
If filename contains an extension, it must be “csv” or “txt”. If it does not, extension is defined by
||(string) (optional) Separator used to write dataset file. (default “,”)
It must be one of “\t”, ” “, “;”, “,”
||(bool) (optional) Extension used to write dataset file. (default “csv”)
It must be one of “csv”, “txt”
To defined only if filename with no extension
||(integer) (optional) number of decimal digits in output file.
(default = 5)
The generated data set has the following headers: id, occ (if occasions have been used), time, amt, adm, rate, y (observations), ytype (observation id), evid (if a washout was defined), and the covariates names.
writeData function is not implemented for simulx project with regressors in MonolixSuite version 2020R1. When a loq is defined in the simulx() function, it is not taken into account when writing the data set.
a dataframe if one single simulation, a list of dataframes if multiple replicates.
The Simulx-GUI demo simulates a PK/PD data set. The saved data set has the standard format to be loaded in Monolix or Simulx.
project.file <- "~/../lixoft/simulx/simulx2020R1/demos/1.overview/importFromMonolix_resimulateProject.smlx" writeData(project=project.file, filename = "simdata.csv")
simpopmlx(): sample sets of population parameters from they uncertainty distribution
Draw population parameters using the covariance matrix of the estimates (which is related to the Fisher Information Matrix) calculated by Monolix (argument
project) or a user-defined covariance matrix (argument
simpopmlx( n = 1, project = NULL, fim = NULL, parameter = NULL, corr = NULL, kw.max = 100, outputFilename = NULL, sep = "," )
||(integer) the number of sets of population parameters to sample (default = 1),|
||(string) a Monolix project, for which the Fisher information Matrix has been estimated by Monolix.|
||(string) the way the Fisher Information Matrix was estimated by Monolix. fim=”sa” (stochastic approximation), “lin” (linearization) (default=”sa”)|
||(data.frame) a data frame with the following columns
Only when project is not used.
||(matrix) correlation matrix of the population parameters (default = identity). Only when project is not used.|
||(integer) maximum number of trials for generating a positive definite covariance matrix of the random effects (default = 100)|
||(string) when defined, path where the population parameters dataframe will be saved
It must be a file with csv or txt extension.
If no extension is specified, file will be saved by default in csv format
||(string) file separator when outputFilename is defined (default = “,”)|
The population parameters are sampled from a multivariate normal distribution. Sampled population parameters are ensured to stay within the bounds allowed by the parameter distribution (e.g F_pop must be between 0 and 1 if it is the typical value of a logitnormal distribution for the individual parameters) using a transformation to the gaussian space. The sampled covariance matrix of the random effects (i.e the omegas and correlations) is checked for being definite positive. If it is not, a new sampling is done.
To use the sets of population parameters in simulx-GUI, use the
outputFilename argument to save the values to a file. Then define a population parameter element by giving the path to the saved external file. When using replicates in the Simulation tab, each replicate will use a different set of the population parameters (i.e a different line of the file) to generate the individual parameters.
Note that the R object returned by simpopmlx has a pop ‘column’ (as required by the simulx() function) but not the file saved (as required by Simulx-GUI).
> project.file <- '~/../lixoft/monolix/monolix2020R1/demos/1.creating_and_using_models/1.1.libraries_of_models/theophylline_project.mlxtran' > pop <- simpopmlx(n=5, project=project.file, outputFilename='popparam_uncer.csv') > pop pop ka_pop V_pop Cl_pop omega_Cl omega_V omega_ka a b 1 1 1.537752 0.4566696 0.04405029 0.2971363 0.12558324 0.5342196 0.3775997 0.05894591 2 2 1.794874 0.5057457 0.03892316 0.1804022 0.09681600 0.7630075 0.3937946 0.04925683 3 3 1.598526 0.4906900 0.03728234 0.1838602 0.16150951 0.7025514 0.4556238 0.03165585 4 4 1.147968 0.4493084 0.04647695 0.1627066 0.07099752 0.4875590 0.3339817 0.07405008 5 5 1.791529 0.4441465 0.04344060 0.2556494 0.10102919 0.8387902 0.3731779 0.05698360
For more examples using simpopmlx with arguments
corr, see http://simulx.webpopix.org/mlxr/simpopmlx/
prctilemlx(): prediction interval plots
Compute and plot percentiles of the empiricial distribution of longitudinal data. When several groups are present, the groups can be plotted as subplots or as different colors on one plot. The input can be a R object (parameter
r) or a monolix project and a variable name (arguments
prctilemlx( r = NULL, col = NULL, project = NULL, outputVariableName = NULL, number = 8, level = 80, plot = TRUE, color = NULL, group = NULL, facet = TRUE, labels = NULL, band = NULL )
||a data frame with a column id, a column time and a column with values.
The times should be the same for all individuals.
||a vector with the three column indexes for id, time and y. Default = c(1,2,3).|
||simulx project filename (with extension “.smlx”)|
||name of the output to consider. By default the first output will be consider.
You must define either a ‘r’ dataframe (and the associated ‘col’ argument) or a simulx project and the name of the output ‘outputVariableName”
||the number of intervals (i.e. the number of percentiles minus 1).|
||the largest interval (i.e. the difference between the lowest and the highest percentile).|
||colors to be used for the plots
In case of one group or facet = TRUE, only the first color will be used
||variable to be used for defining groups (by default, ‘group’ is used when it exists)|
||makes subplots for different groups if
||vector of strings|
||is deprecated (use number and level instead) ; a list with two fields
You must define either a dataframe
r (and if needed the associated
col argument) or a simulx
project and the name of the output
outputVariableName. The outputVariableName corresponds to the name of the model variable, not to the output element name.
a ggplot object if
plot=TRUE ; otherwise, a list with fields:
- proba: a vector of probabilities of length
- color: a vector of colors used for the plot of length
- y: a data frame with the values of the empirical percentiles computed at each time point
This simulx-GUI demo project contains 3 simulation groups, with a low, medium or high dose. In the Simulation tab, the output element ‘regularCc’ is selected, to output the variable ‘Cc’ on a regular time grid.
facet=T (default), each group is displayed on a separate subplot with the different shades representing different percentiles. The largest band represents the 90% prediction interval.
project.file <- "~/../lixoft/simulx/simulx2020R1/demos/5.simulation/simulationGroups_treatment.smlx" prctilemlx(project=project.file, outputVariableName = "Cc")
level=95, we can select to display only the median and the 95% prediction interval.
project.file <- "~/../lixoft/simulx/simulx2020R1/demos/5.simulation/simulationGroups_treatment.smlx" prctilemlx(project=project.file, outputVariableName = "Cc", number=2, level=95)
To display the prediction intervals on top of each other, use
facet=F. As a ggplot object is returned, additional ggplot functions can be used to overlay additional features or modify the legend, etc.
prctilemlx(project=project.file, outputVariableName = "Cc", facet=F, number=2, level=95) + ylab("Concentration (ug/mL)") + xlab("Time (hr)") + geom_hline(yintercept = 0.25)
See also http://simulx.webpopix.org/mlxr/prctilemlx/ for more examples.