Installation and initialization

Prerequisites

R version 3.0.0 or higher is required to use lixoftConnectors.

The lixoftConnectors package depends on the RJSONIO, gridExtra and ggplot2 packages that need to be installed from CRAN first using:

R

install.packages('RJSONIO')
install.packages('ggplot2')
install.packages('gridExtra')

Installation

The R package lixoftConnectors is located in the installation directory as tar.gz archive. It can be installed directly using Rstudio (Tools > Install packages > from package archive file) or with the following R command:

R

install.packages(packagePath, repos = NULL, type="source", INSTALL_opts ="--no-multiarch")

with the packagePath = '<installDirectory>/connectors/lixoftConnectors.tar.gz' where <installDirectory> is the MonolixSuite installation directory.

With the default installation directory, the command is:

R

# for Windows OS
install.packages("C:/Program Files/Lixoft/MonolixSuite2024R1/connectors/lixoftConnectors.tar.gz", 
                 repos = NULL, type="source", INSTALL_opts ="--no-multiarch")

R

# for Mac OS
install.packages("/Applications/MonolixSuite2024R1.app/Contents/Resources/\
                  monolixSuite/connectors/lixoftConnectors.tar.gz",
                  repos = NULL, type="source", INSTALL_opts ="--no-multiarch")

Note that for MonolixSuite version 2023 and earlier, the path to use for Windows OS is different:

R

# for Windows OS (MonolixSuite version 2023)
install.packages("C:/ProgramData/Lixoft/MonolixSuite2023R1/connectors/lixoftConnectors.tar.gz", 
                 repos = NULL, type="source", INSTALL_opts ="--no-multiarch")

Note that for MonolixSuite version 2018, the R package is called MlxConnectors.

Initialization

When starting a new R session, you need to load the library and initialize the connectors with the following commands, specifying either “monolix”, “simulx”, or “pkanalix” for the software argument.

R

library(lixoftConnectors)
initializeLixoftConnectors(software = "monolix")

In some cases, it may be necessary to specify the path to the installation directory of MonolixSuite. If no path is given, the one written in the <user home>/lixoft/lixoft.ini file is used (usually "C:/Program Files/Lixoft/MonolixSuite2024R1" for Windows or "C:/ProgramData/Lixoft/MonolixSuiteXXXX" where XXXX corresponds to the version of MonolixSuite for earlier versions)

R

library(lixoftConnectors) 
initializeLixoftConnectors(software = "monolix", path = "/path/to/MonolixSuite/")

When you initialize the connectors with one application (e.g. “monolix”) and then initialize it again with another one (e.g. “simulx”), there is a security check asking you to agree with the switch. To bypass this check and avoid having to answer “yes” manually, you can specify the option “force = TRUE”:

R

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

Troubleshooting

Error “unable to load shared object”

Error in inDL(x, as.logical(local), as.logical(now), ...): unable to load shared object 'C:/Program Files/Lixoft/MonolixSuite2024R1/lib/lixoftConnectors.dll':

On Mac OS: MonolixSuite has not been compiled for M1 chips. To use the lixoftConnectors, you need to install and use the ‘x86_64’ version of R that you can install from https://cran.r-project.org/bin/macosx/

On Windows: Having R package "zip" loaded before initializing the lixoftConnectors is the most common cause of the issue. This package is imported when loading the packages "openxlsx", "officer" or "flextable" for instance, and it prevents loading the dll needed to initialize lixoftConnectors. The solution is to start from a clean R session and load and initialize the lixoftConnectors before loading any other package.

Error “computeSimulations is not an exported object from namespace::lixoftConnectors

This error can happen when the lixoftConnectors, RsSimulx and MonolixSuite versions do not match.

CODE

library(lixoftConnectors)
initializeLixoftConnectors()
packageVersion("lixoftConnectors") # gives version of the R package
getLixoftConnectorsState()$version # gives version of MonolixSuite 

# if RsSimulx is also used:
library(RsSimulx)
initRsSimulx()
packageVersion("RsSimulx")

To change the version of the lixoftConnectors R package, install it again using the .tar.gz from the installation directory of the MonolixSuite version you want to use.

To change the MonolixSuite version, initlialize by specifying the path of the version you want to use, e.g initializeLixoftConnectors(path="C:/Program Files/Lixoft/MonolixSuite2024R1").

In addition, note that mlxR is only compatible with MonolixSuite version up to 2019. Afterwards, RsSimulx should be used instead.

Verifying the installation is correct

To test if the installation is correct, you can load and run a demo project as shown:

R

demoPath <- getDemoPath()
loadProject(file.path(demoPath, "1.creating_and_using_models", "1.1.libraries_of_models", "theophylline_project.mlxtran"))
runScenario()
getEstimatedPopulationParameters()

These three commands should output the estimated population parameters (ka_pop, V_pop, Cl_pop, omega_ka, omega_V, omega_Cl, a, and b).