Reporting

Starting from the 2023R1 version of the MonolixSuite, Monolix includes a feature of automated report generation. This feature is available in Monolix through Export > Generate report. After defining settings in the window that pops up and clicking on the Generate report button, a report in the form of a Microsoft Word (docx) document will be generated in the specified directory. Note that reports generated using command line and lixoftConnectors will contain tables but no plots. Reporting module is not available on the CentOS 7 version of MonolixSuite 2023R1.

Report generation strategies

When selecting Export > Generate report…, there are two different strategies available for report generation:

1. Using a default template file – choosing this option will generate the report containing tables of estimated population parameters (with standard errors) and log-likelihood and information criteria, as well as all plots available in the interface using their current settings. This option allow to obtain a basic report with all results in one click.

2. Using a custom template file – if users choose this option, they will be required to provide a path to the template word file which contains placeholders that will be replaced by tables, plots and keywords when generating the report.

Several other options are available in the pop-up window after the Generate report option is clicked on:

1. Document watermark – users can specify a custom text that will appear as a watermark in the report. Font family, font size, color, layout and transparency can be specified, if text is entered into the Text input widget.

2. Generated report file – users can choose if the generated report will be saved next to the project file (in that case only the name of the generated report file needs to be given to Monolix) or in a custom directory (absolute path that includes the generated report file name needs to be given).

3. Table styles (only when the custom template file option is selected) – users can choose a style for tables from the list of styles available by default in Microsoft Word. This setting can be overridden by specifying the style directly in the table placeholder. This way custom user-created or company-specific styles can be used.

Default template file

Selecting the option to use the default template file to generate a report gives users a possibility to quickly generate a document containing results of an analysis.

Such a report will consist of:

1. name of the Monolix project

2. data set file name,

3. a date of report generation,

4. a table of estimated population parameters (with standard errors, if calculation of SE was performed),

5. a table of log-likelihood and information criteria (if calculation of likelihood was performed),

6. all plots displayed in the GUI with settings currently defined in the interface.

By clicking on View default template, a Word document containing placeholders for all the elements that will be present in the generated report can be downloaded. This document can then be used as a basis for the creation of a custom template file.

Custom template file

The option to use the custom template file can be selected if a user has previously created a Word document (a template) that typically contains placeholders to be replaced by project-specific information, such as tables of results, plots or settings used in a project. Placeholders are strings with a specific syntax that define the settings and layout with which tables and plots will be generated during the report generation process.

For example, in the picture below, a template file on the right contains a placeholder for the observed data plot. So, after report generation, the report file on the right contains a plot for the observed data instead of this placeholder.

Using placeholders

There are three types of placeholders that can be used:

1. placeholders for project settings,

2. placeholders for plots,

3. placeholders for tables.

Placeholders for project settings are of format %keyword% and, during the report generation step, they will be replaced by project or global Monolix settings. For example, if a custom template file contains the placeholder %SAEM_nbBurningIterations%, this placeholder will be replaced by the number of SAEM burning iterations used by a Monolix project for which the report is being generated. The list of all project settings placeholders can be found here.

Placeholders for plots are of format <lixoftPLH>settings</lixoftPLH> and, during the report generation step, they will be replaced by plots that are available in the Monolix user interface. Placeholders for plots contain settings that describe how the generated plots should look like. All settings that are available for plots in the interface are available in reporting as well, with addition of several others that describe plot dimensions and display of captions. The list of the main plot settings placeholders can be found here.

Placeholders for tables are also of format <lixoftPLH>settings</lixoftPLH>. Placeholders for tables contain settings that describe how the generated table should look like and they allow more flexibility in the layout compared to the display of tables in the GUI. Indeed, table placeholders can contain settings that result in generated tables being different from the ones available in the Results tab of the Monolix interface, such as an option to choose which rows or columns to include in the table, or to split tables in a different direction that the one present in interface. Here is the list of all settings that can be used for table placeholders.

Placeholders do not need to be written by the users. They can be generated through the interface, using the Copy reporting placeholder ( ) button which can be found next to every plot and results table. Clicking on this button will display the corresponding placeholder in a pop-up window. The displayed placeholder can then be copied to a template file and will be replaced by the table or plot, exactly as they are shown in the interface, with all stratification options and display settings applied.

Let’s take a look at how “Copy reporting placeholder” buttons work on a specific example. If we load the demo project_censoring.pkx, go to the Observed data plot and click on the Copy reporting placeholder button above the plot, a pop-up window will appear containing the placeholder for the plot, which can then be used in a report template to generate the plot that looks exactly like the plot currently shown in the interface. As you can see on the screenshot below, the placeholder contains information about plot type, plot size, caption and axes labels.

If we now close the pop-up, enable legend and open the pop-up again, the placeholder will contain the enabled legend setting and, if we put the placeholder in a report template, the generated plot will have a legend present in its corner, as shown in the screenshot on the right.

If we would like our report to have the Observed data plot stratified by a categorical covariate, SEX, we can stratify the plot in the interface and click on the Copy reporting placeholder button again to generate a placeholder for this plot, as shown on the images below. You can notice that the generated placeholder now contains settings stratification and layout, which control stratification and plot layout.

There are several options present inside the “Placeholder for Report Template” pop-up:

1. indent – determines number of spaces used for indentation of settings in the placeholder,

2. flow level – determines the compactness of placeholders, i.e how often we start a new line (lower the number, more compact the placeholder will be),

3. dimensions units – gives the ability to choose if width and height will be in cm or inches,

4. lock aspect ratio – if on, changing width or height will change the other dimension to keep the aspect ratio present on the screen.

It is possible to edit placeholders directly inside the pop-up. Clicking on the Preview button will generate and open a Word document containing a plot or a table described with the placeholder. This option is especially useful when a user manually modifies placeholders, to check if the syntax and the behavior are correct.

Copy to clipboard button will copy the placeholder with the <lixoftPLH> tag, ready to be pasted to the custom Word template.

Using areTaskResultsAvailable

Besides placeholders, templates can include the areTaskResultsAvailable tag, which can be used to display part of the template conditionally in the report.

For example, if a template contains the text:

<? areTaskResultsAvailable(likelihood) ?>
Show this if likelihood estimation has been run
</?>

The text “Show this if likelihood estimation has been run” will be present in the generated report, only if results of the likelihood task are available, otherwise the tags and the text will not be present in the generated report. Besides text, it is possible to include placeholders inside the areTaskResultsAvailable tag. The syntax of areTaskResultsAvailable tag is areTaskResultsAvailable(task, method), with the method argument being optional. Tasks that can be used inside the parentheses are:

• populationParameters,

• individualParameters (methods: mode and mean),

• correlationMatrix (methods: stochasticApproximation and linearization),

• likelihood (methods: importanceSampling and linearization).

It is also possible to show content when task results are not available by writing !areTaskResultsAvailable.

Example use of a custom template

Download custom template for Warfarin case study

Here is an example custom template to use with the warfarin project available in demo projects (Monolix Demos > 1.1.libraries of models > warfarinPK_project.mlxtran). This dataset is also the topic of a video explaining the typical workflow in Monolix here. The custom template includes table of contents for tables and figures, which get updated when generating the report.

Renamings

A section Reporting placeholder entry renamings in Preferences can be used to change words and phrases that will appear in generated reports by default. For example, if we give alias “Thetas” to the placeholder entry “fixedeffects”, the word “fixedeffects” in the population parameter table generated by the reporting feature will be replaced by the word “Thetas”.

In addition, it is possible to rename words found in generated tables, by specifying an argument renamings inside the placeholder. This allows users to change words present in the data set as well. For example, if an imported data set contains a column “Formulation” with values T (for the test drug) and R (for the reference drug), specifying the following inside a placeholder will replace all occurrences of word “T” inside the table with “test” and “R” with “reference”:

renamings:
    T: test
    R: reference

For categorical covariates, it is possible to specify both the covariate name and the covariate modality to be replaced, in order to avoid ambiguities if, for example, category “0” appears in several covariates. In addition, quotes can be used if spaces are needed within the springs:

renamings:
    SEX#0: Male
    SEX#1: Female
    RACE#0: Caucasian
    RACE#1: "African american"
    RACE#2: Hispanic

Respecting the indentation before the modalities to replace and the space after the “:” is crucial to have the placeholder properly recognized.

Generating reports from the command line

It is possible to generate a report directly from R with the connector generateReport() or through the command line, without using the Monolix interface. This can be useful when running Monolix on a server.

Note that reports generated via command line will not contain plots. This is a known limitation of the current implementation of the reporting feature.

To generate a report via command line, the executable reportGenerator can be called from the lib folder (typically $HOME/Lixoft/MonolixSuite2023R1/lib/):

reportGenerator -p monolix_project_path

Multiple options can be provided to reportGenerator: