Package "mlxDesignEval"

Introduction

The mlxDesignEval package offers design evaluation based on nonlinear mixed-effect models. The main goal of mlxDesignEval is to return the expected uncertainty on the parameters (as relative standard errors, RSEs), for a given model (model equations and parameter values) and design (dosing regimen, observation times, number of individuals, etc). Note that design optimization and shrinkage calculation are not included yet.

Compared to other R packages such as popED or PFIM, mlxDesignEval can use a Monolix or Simulx project as input, which avoids error-prone model conversions and streamlines the workflow.

The uncertainty estimation is based on the calculation of the Fisher Information Matrix (FIM) using a first-order approximation around the typical population parameters. To learn more about the theory behind, we invite you to read Nyberg, J. et al. Methods and software tools for design evaluation in population pharmacokinetics-pharmacodynamics studies. Br. J. Clin. Pharmacol. 79, 6–17 (2015).

The results of mlxDesignEval have been validated with respect to popED, see our comparison page.

Licensing

mlxDesignEval requires a dedicated paid license. Contact us for more information.

In addition, in order to call the MonolixSuite in the background, mlxDesignEval requires both a Monolix and a Simulx license.

Requirements

mlxDesignEval makes use of MonolixSuite in the background and thus requires to have MonolixSuite (2023 or 2024) and the R package lixoftConnectors (2023 or 2024) installed.

Installation and setup

Install mlxDesignEval using the .zip or tar.gz (adjust the path to the location of the zip or tar.gz):

#Windows
install.packages("Path/to/mlxDesignEval_0.3.0.zip", repos = NULL, type = "win.binary")

#Linux
install.packages("Path/to/mlxDesignEval_0.3.0_R_x86_64-pc-linux-gnu.tar.gz", repos = NULL, type = "source")

To start using mlxDesignEval, first load the library. mlxDesignEval then needs to load some libraries located in the MonolixSuite installation folder. The link to the MonolixSuite installation is done by calling initMlxDesignEval(). Without input argument, the MonolixSuite installation directory will be read from the file "home folder"/lixoft/lixoft.ini. Alternatively, it is possible to specify another location by adding a path argument (e.g initMlxDesignEval(path="C:/ProgramData/Lixoft/MonolixSuite2023R1")).

library(mlxDesignEval)
initMlxDesignEval()
#> [INFO] The directory specified in the initialization file of the Lixoft Suite (located at "C:\Users\celliere\lixoft\lixoft.ini") will be used by default: "C:/Program Files/Lixoft/MonolixSuite2024R1"

If you have received an mlxDesignEval activation key, you can generate the license file using activateMlxDesignEval(). This step needs to be done only once. If you already have an mlxDesignEval license, this step can be skipped.

activateMlxDesignEval(activationKey="1111-1111-1111-1111") # replace the key by the one provided to you

Getting started

To write you first call to mlxDesignEval, see our examples pages.

Overview of features

The table below shows an overview of the features of mlxDesignEval compared to popED and PFIM.

ChangeLog

Version 0.3.0 (new features)

• support of version 2024 of lixoftConnectors (mostly for the function plot_prediction)

• when FIM contains NaNs, RSE are returned for parameters which are not NaN

• possibility to give as only input a Monolix project to perform a parameter identifiability analysis

• new function inlineModel() to create a model text file from a string

• in plot_prediction(), possibility to choose the output variable to plot

• in plot_prediction(), possibility to set y axis in log-scale

• new argument "use_jacobian": If true (default), the covariance matrix in gaussian space (for the normally-distributed transformed parameters, e.g log(V_pop)) are transformed into the non-gaussian space using the Jacobian matrix, which is a first order approximation. Otherwise, an exact formula is used. When using the 2023 version of MonolixSuite, only the jacobien method is available. With version 2024, to obtain the same results as popED, use use_jacobian=T (which is the default).

• documentation as vignettes

Version 0.3.1 (bug fixes)

• fixed bug when underscore in present in indiv param name (e.g V_nocov), due to wrong parsing of corresponding population parameter name (having two underscores)
  Error: in if(logNormal) expect a TRUE/FALSE value

• fixed bug when several outputs are present in Monolix project but only one is used as output in evaluate_design(), due to the "c" parameters of the error model being not properly handled in the "fixed_parameters" element
  Error: In the argument 'fixed_parameters' the following parameter are provided but not existing in the model: c1