Running through command line
Command and arguments
monolixSuiteInstallationFolder/bin/Monolix.sh --no-gui -p fullPathProjectName
(replace .sh into .bat for windows operating system)
Notice that the project name should be defined using a full path and not a relative path. The program options are:
--no-gui
: run without opening a window, mandatory in no-desktop environments.-p, --project
: path to the project to run. It should be the absolute (not relative) path name of the project.--thread, --number-of-threads
: number of threads to use for the run (integer)--mode, --console-mode
: select the verbosity of the run information that will be log in console. It can be “none”, “basic” (default value), or “complete”.--nosplash
: no splash screen. Only used when opening with GUI. When the option –no-gui is used, nosplash option is not read.-o, --output-dir:
output directory-t, --tool:
tool to launch. It can be “monolix” (default value), “modelBuilding”, “convergenceAssessment” or “bootstrap”--config:
config file with additional settings for model building, convergence assessment or bootstrap
Notes for Windows:
The maximum number of arguments is 10. If more are needed, you can use the monolix.exe file in the /lib directory.
The native terminals command prompt and PowerShell will not show an output while the project runs, whereas terminals for Windows with a bash shell will. A workaround to still get an output is to write the output to a text file (use |tee console_output.txt at the end of your command).
Example
monolix.bat --no-gui --mode none --thread 4 -p "C:\Users\celliere\lixoft\monolix\monolix2021R1\demos\1.creating_and_using_models\1.1.libraries_of_models\theophylline_project.mlxtran"
Exporting charts data
If the plots task is selected in the Monolix scenario, and if “Export charts data” is selected in Monolix preferences, the charts data are saved in the result folder. Generating the interactive plots requires to open the project in the GUI.
From the 2021 version on, the plots can also be generated as ggplot object using R functions from the lixoftConnectors R package.
Outputting to the console
With versions prior to 2023R1, the output is displayed in the console.
With versions 2023R1 and 2024R1, the output is not displayed in the console by default which may give the impression that nothing happens. In order to see the progress in the system console, it is possible to add 2>>&1 | findstr /r "/c:.*"
at the end of the call, for instance:
monolix.bat --no-gui --mode complete --thread 4 -p "C:\Users\celliere\lixoft\monolix\monolix2021R1\demos\1.creating_and_using_models\1.1.libraries_of_models\theophylline_project.mlxtran" 2>>&1 | findstr /r "/c:.*"
Running the covariate search (model building), convergence assessment or bootstrap
Notes:
In Monolix versions prior to 2024R1, convergence assessment and bootstrap are not available from commandline.
See here for running the covariate search (model building) with MonolixSuite2023R1 and prior
Users can choose the tool to run with --tool
(see section above) and can provide all settings for the selected tool using --config
followed by a configuration text file (for example saved as .txt or .config).
Settings for different tools can be included in a single config file, as they are separated in different blocks: [modelBuilding]
, [assessment]
and [bootstrap]
. Below we show the config file template for the different tools.
If a setting is not specified, the default setting as in the GUI is used, unless the tool has already run in the project with custom settings: in that case the previous settings have been saved with the project and are reused.
Model building
Documentation for model building in Monolix
Template for model building settings:
[modelBuilding]
strategy=<COSSAC, SAMBA, covSAMBA, SCM>
lin=<true, false>
copyData=<true, false>
stoppingCriterion=<bicc, LRT>
LRTThreshold=<forward threshold>, <backward threshold>
correlationThreshold=<forward threshold>, <backward threshold>
locked\<parameter>\<covariate>=<out, in>
selectedParameters=<parameter>, <parameter>, ...
selectedCovariates=<covariate>, <covariate>, ...
The default settings correspond to:
[modelBuilding]
strategy=COSSAC
lin=true
copyData=false
stoppingCriterion=LRT
LRTThreshold=0.01, 0.01
correlationThreshold=0.3, 0.01
Example
Covariate search on warfarinPK_project.mlxtran using SAMBA considering only the parameters V, Cl and Tlag and the covariates sex and wt, with a locked covariate effect of sex on Cl and no possible covariate effect of sex on V, without linearization, and using the BICc as the stopping criterion to add or remove a covariate effect. The correlation p-value thresholds for forward and backward selection is 0.001.
monolix.exe --no-gui -t modelBuilding -p warfarinPK_project.mlxtran --config warfarinPK_project_config.txt
With warfarinPK_project_config.txt containing:
[modelBuilding]
strategy=covSAMBA
lin=false
copyData=true
stoppingCriterion=bicc
correlationThreshold=0.001, 0.001
locked\V\sex=out
locked\Cl\sex=in
selectedParameters=V, Cl, Tlag
selectedCovariates=sex, wt
Convergence assessment
Documentation for convergence assessment in Monolix
Template for convergence assessment settings:
[assessment]
nbruns=<number of runs>
SEandLL=<true, false>
linearization=<true, false>
parameter\<population parameter>\interval=<lower bound>, <upper bound>
The default settings correspond to:
[assessment]
nbruns=5
SEandLL=false
linearization=false
Example
Running convergence assessment on warfarinPK_project.mlxtran with 10 runs where standard errors and log-likelihood are also estimated using linearization, and where the initial values of V_pop are randomly chosen in the [3,4] interval while other parameters keep the same initial values as the original run.
monolix.exe --no-gui -t assessment -p warfarinPK_project.mlxtran --config warfarinPK_project_config.txt
With warfarinPK_project_config.txt containing:
[assessment]
nbruns=10
SEandLL=true
linearization=true
parameter\V_pop\interval=3, 4
Bootstrap
Documentation for bootstrap in Monolix
Template for bootstrap settings:
[bootstrap]
nbruns=<number of runs>
runLikelihood=<true, false>
runSE=<true, false>
lin=<true, false>
initialValues=<initial, final>
sampling=<parametric, nonparametric>
sampleSize=<number of subjects in sampled dataset>
stratifiedResampling=<covariate>, <covariate>, ...
confidenceInterval=<percentage level for confidence interval>
saveBootResults=<true, false>
saveBootData=<true, false>
replaceFailedConv=<true, false>
maxNbFailedRuns=<maximum number of runs with failed convergence that can be replaced>
cens\<Observation name>\<left, right>=<limit of quantification for parametric sampling>
cens\<Observation name>\<interval>=<first limit of quantification for parametric sampling>, <second limit of quantification for parametric sampling>
The default settings correspond to:
[bootstrap]
nbruns=200
runLikelihood=false
runSE=false
lin=false
initialValues=initial
sampling=nonparametric
sampleSize=<same number of subjects as original dataset>
confidenceInterval=95
saveBootResults=false
saveBootData=false
replaceFailedConv=false
maxNbFailedRuns=20
Examples
Running non-parametric bootstrap on warfarinPK_project.mlxtran with 500 runs, with stratified resampling by sex (ie all sampled datasets have the same proportions of subjects in sex categories as in the original dataset). Each run uses the final estimates from the original run as initial estimates for SAEM, and standard errors and log-likelihood are also estimated using linearization.
monolix.exe --no-gui -t bootstrap -p warfarinPK_project.mlxtran --config warfarinPK_project_config.txt
With warfarinPK_project_config.txt containing:
[bootstrap]
nbruns=500
sampling=parametric
runLikelihood=true
runSE=true
lin=true
initialValues=final
stratifiedResampling=sex
saveBootData=true
Running parametric bootstrap on censoring1_project.mlxtran with 1000 runs, where all simulated Y observations below 4 in the sampled datasets are set as censored with LLOQ=4, and each sampled dataset is saved with the bootstrap run.
monolix.exe --no-gui -t bootstrap-p censoring1_project.mlxtran --config censoring1_project_config.txt
With censoring1_project_config.txt containing:
[bootstrap]
nbruns=1000
sampling=parametric
cens\CONC\left=4
saveBootData=true
Running covariate search (model building) with MonolixSuite2023R1 and prior
In versions of Monolix prior to 2023R1, there is no –config option to give a config file with model building settings. Instead, the following options can be used:
-s, --strategy
: select the model building algorithm. It can be “cossac” (default value), “samba”, “covSamba” or “scm”.-c, --stoppingCriterion:
Select the stopping criterion of model building. It can be “bic” or “lrt” (default value).-a, --LRTThresholdUp
: p-value threshold for the LRT in backward (default 0.01)-r, --LRTThresholdLower
: p-value threshold for the LRT in forward (default 0.01 for cossac and 0.05 for scm)--lin, --useLinearization
: use linearization if possible. “true” (default value) or “false”.
Examples
monolix.bat --no-gui -t modelBuilding -s cossac -a 0.06 -r 0.001 --lin false -p "C:\Users\celliere\lixoft\monolix\monolix2021R1\demos\1.creating_and_using_models\1.1.libraries_of_models\theophylline_project.mlxtran"
monolix.bat --no-gui -t modelBuilding -s scm -c bic -p "C:\Users\celliere\lixoft\monolix\monolix2021R1\demos\1.creating_and_using_models\1.1.libraries_of_models\theophylline_project.mlxtran"
monolix.bat --no-gui -t modelBuilding -s covSamba -p "C:\Users\celliere\lixoft\monolix\monolix2021R1\demos\1.creating_and_using_models\1.1.libraries_of_models\theophylline_project.mlxtran"
From the 2021 version on, the settings of the model building are saved and reloaded. It is thus possible to do the following to run the model building (covariate search) with more custom settings than provided with the command line arguments, for instance regarding which parameter-covariate relationship to test:
with the GUI, setup the model building settings you need
launch the model building run and click on the “stop” button immediately. The model building setting are saved in the monolix result folder.
launch the model building in command line using:
monolix.bat --no-gui -t modelBuilding -p yourProject
Note that:
the results folder of the monolix run needs to the present for the model building setting to load and be used by the run in command line.
this method does not work with distributed calculation using openMPI.
Running distributed Monolix on a cluster
All settings described on this page can also be used for distributed calculation on a cluster with openMPI.
Monolix installation
To run MonolixSuite on a cluster, each cluster node must have access to the MonolixSuite directory and to the user home directory. Thus, there are two possibilities.
MonolixSuite is installed on each node. In that case, each node has a MonolixSuite installation.
MonolixSuite installation is shared. MonolixSuite is installed on a master server. Each cluster node accesses to MonolixSuite through a shared directory (via CIFS, Network drive, NFS, …).
License management
On a cluster, we are managing the usage of our applications with the license management system described here.
The license management server is on a physical machine and manage the application through its license file. The associated license file has to be put in the folder {MonolixSuite install path}/config/system/access (and also {MonolixSuite install path}/bin/Monolix_mcr/runtime/config/system/access for MonolixSuite2016R1). So either on all nodes in the installation case 1, or only on the master server in the configuration 2.
Running Monolix on a cluster
To run Monolix with the command line: in the lib folder (typically $HOME/Lixoft/MonolixSuite2024R1/lib/)
monolix --no-gui -p mlxtran_project_path
where mlxtran_project_path is a Monolix project with a .mlxtran extension. Notice that a typical project from the demo can be found here $HOME/Lixoft/MonolixSuite2018R1/resources/demos/monolix/1.creating_and_using_models/1.1.libraries_of_models/theophylline_project.mlxtran
Generally, a task is submitted to the cluster using a specific command, e.g. qsub in the case of Torque, PBS or GridEngine (former SGE). This command runs a script, provided as parameter, on a cluster node chosen by the cluster scheduler. To run Monolix on a cluster: in the lib folder (typically $HOME/Lixoft/MonolixSuite2024R1/lib/)
qsub qSubOptions monolix --no-gui -p mlxtran_project_path
where qSubOptions corresponds to your cluster options.
Running Monolix on a cluster using mpi
To run using mpi with the command line: in the lib folder (typically $HOME/Lixoft/MonolixSuite2024R1/lib/)
mpirun mpiOptions distMonolix -p mlxtran_project_path
MPI options and setup
mpiOptions corresponds to your mpi options. Notice that the mpirun calls another program that requires another license.
In addition, the package was done with openmpi (version 1.6 for MonolixSuite 2020R1, and 1.10 for MonolixSuite2021R1). If you have a more recent version (2.2 (ubuntu 18.04), 4.0 (ubuntu 20.04), 4.1 (centOS stream 8) for example), you just have to create a symbolic link from your installation
from your installation of libmpi.so (usually in /usr/lib64/openmi/lib/libmpi.so.XX) to libmpi.so.1 (in our lib folder).
CODEsudo ln -s your_installation_of_openmi/lib/libmpi.so.XX installation_of_MonolixSuiteXXXX/lib/libmpi.so.12
from your installation of libmpi.so (usually in /usr/lib64/openmi/lib/libmpi_cxx.so.XX ) to libmpi_cxx.so.1
(in our lib folder).CODEsudo ln -s your_installation_of_openmi/lib/libmpi_cxx.so.XX installation_of_MonolixSuiteXXXX/lib/libmpi_cxx.so.1
Monolix options and distributed calculation
Additional options for the Monolix run, in particular --tool
to select a multi-run task (model building, convergence assessment, bootstrap) and --config
to provide settings for this task, were already described on this page.
How the distribution is done:
in MCMC (SAEM, Fisher by Stochastic Approximation, Conditional Distribution): pools of ids are created and distributed by process
in Importance Sampling: same with simulation pools
in multi-run tasks (bootstrap, convergence assessment): each run is distributed over all processes.
For further assistance, contact us.