Select Page

Running Monolix using the 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 consolde

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:

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.

Documentation page explaining how to run MonolixSuite on a cluster