{"id":26481472,"url":"https://github.com/ggpmxdevelopment/ggpmx","last_synced_at":"2025-04-05T22:08:09.355Z","repository":{"id":37939792,"uuid":"181708751","full_name":"ggPMXdevelopment/ggPMX","owner":"ggPMXdevelopment","description":"ggPMX R package","archived":false,"fork":false,"pushed_at":"2025-04-03T13:11:22.000Z","size":29592,"stargazers_count":39,"open_issues_count":55,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-05T22:07:56.752Z","etag":null,"topics":["pharmacometrics","pmx","r","reporting"],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ggPMXdevelopment.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-16T14:41:37.000Z","updated_at":"2025-01-24T13:17:00.000Z","dependencies_parsed_at":"2025-02-20T15:33:05.547Z","dependency_job_id":"334fa68e-9260-48e6-8636-b650f035973d","html_url":"https://github.com/ggPMXdevelopment/ggPMX","commit_stats":{"total_commits":1378,"total_committers":24,"mean_commits":"57.416666666666664","dds":0.5609579100145138,"last_synced_commit":"ee65d769ee832779dd0fa5696138df407132734a"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggPMXdevelopment%2FggPMX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggPMXdevelopment%2FggPMX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggPMXdevelopment%2FggPMX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggPMXdevelopment%2FggPMX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ggPMXdevelopment","download_url":"https://codeload.github.com/ggPMXdevelopment/ggPMX/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406090,"owners_count":20933803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pharmacometrics","pmx","r","reporting"],"created_at":"2025-03-20T03:20:40.221Z","updated_at":"2025-04-05T22:08:09.317Z","avatar_url":"https://github.com/ggPMXdevelopment.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\"\n)\n```\n\n# ggPMX \u003cimg src=\"man/figures/logo.jpg\" align=\"right\" width=\"120\" /\u003e\n\n**Authors**:  Amine Gassem, Irina Baltcheva, Christian Bartels, Souvik Bhattacharya, Thomas Dumortier, Matthew Fidler, Seid Hamzic, Inga Ludwig, Ines Paule, Didier Renard, Bruno Bieth\n\n[![R-CMD-check](https://github.com/ggPMXdevelopment/ggPMX/workflows/R-CMD-check/badge.svg)](https://github.com/ggPMXdevelopment/ggPMX/actions)\n[![CRAN\\_Status\\_Badge](https://www.r-pkg.org/badges/version/ggPMX)](https://cran.r-project.org/package=ggPMX)\n[![Coverage Status](https://codecov.io/gh/ggPMXdevelopment/ggPMX/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ggPMXdevelopment/ggPMX)\n[![](https://cranlogs.r-pkg.org/badges/last-week/ggPMX?color=green)](https://cran.r-project.org/package=ggPMX)\n\n\n# Overview\n\nggPMX is an open-source R package freely available on CRAN since April 2019. It generates standard diagnostic plots for mixed effect models used in pharmacometric activities. The package builds on the R-package ggplot2 and aims at providing a workflow that is **consistent**, **reproducible** and **efficient**, resulting in **high quality graphics** ready-to-use in submission documents and publications. Intuitive functions and options allow for optimal figure customization and graphics stratification. ggPMX enables straightforward generation of PDF, Word or PNG output files that contain all diagnostic plots for keeping track of modeling results. The package is currently compatible with Monolix versions 2016 and later, NONMEM version 7.2 and later and nlmixr.\n\nUsing simple syntax, the toolbox produces various goodness-of-fit diagnostics such as:\n- residual- and empirical Bayes estimate (EBE)-based plots, \n- distribution plots, \n- prediction- and simulation-based diagnostics (visual predictive checks). \n\nggPMX creates plot objects which can be further customized and extended using the extensive [ggplot2 syntax](https://ggplot2.tidyverse.org/reference/gg-add.html).\n\nIn addition, shrinkage and summary parameters tables can be also produced. By default, the PDF- or Word-format diagnostic report contains essential goodness-of-fit plots. However, these can be adapted to produce different sets of diagnostics as desired by the user, and any of the plots may be customized individually. The types of supported customizations include modifications of the graphical parameters, labels, and various stratifications by covariates.\n\n# Installation\n\n```{r, eval = FALSE}\n\n# Either install from CRAN\ninstall.packages(\"ggPMX\")\n# Or the development version from GitHub:\n# install.packages(\"devtools\")\ndevtools::install_github(\"ggPMXdevelopment/ggPMX\")\n```\n\n# Testing the install\n\nOnce ggPMX is installed, you can test if everything is working well.  If successful you should see a plot created after the following build-in example.\n\n```R\nlibrary(ggPMX)\nctr \u003c- theophylline()\nctr %\u003e% pmx_plot_eta_matrix()\n```\n\n\u003cimg src=\"man/figures/ggpmx_example1.png\" /\u003e\n\n\n\n# Cheatsheet\n\n\u003cimg src=\"man/figures/ggPMX_cheat_sheet_0_9_4.png\"  /\u003e\n\n\n# Feedback\n\nggPMX is now ready for inputs and enhancements by the pharmacometric community.\n- Please use [ package issues](https://github.com/ggPMXdevelopment/ggPMX/issues) to fill in your feedback.\n\n\n\\clearpage  \n```{r load_package, echo=FALSE,warning=FALSE,message=FALSE}\nknitr::opts_chunk$set(out.width = \"100%\", warning = FALSE, message = FALSE)\nlibrary(ggPMX)\nlibrary(ggplot2)\nlibrary(xtable)\nlibrary(knitr)\n\ntheophylline \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir \u003c- file.path(theophylline, \"Monolix\")\ninput_data \u003c- file.path(theophylline, \"data_pk.csv\")\n\nctr \u003c- theophylline()\n```\n\n\n# Introduction \nThe `ggPMX` package generates standard diagnostic plots and tables for mixed effect models used in Pharmacometric (PMX) activities. The tool is built upon the ggplot2 package and supports models developped with Monolix, NONMEM and nlmixr software. The current release (1.2) supports models fitted with Monolix versions 2016 and later, NONMEM version 7.2 and later and nlmixr.\n\nThe package aims to provide a workflow that is consistent, efficient and which results in high quality graphics ready to use in official documents and reports. The package allows a high degree of flexibility and customization, yet providing an acceptable default setting. The package also allows to fully automate plots and report generation. \n\nThe general context is the analysis of mixed effect models fitted to data. ggPMX was developed in the framework of Pharmacometric activities, in which case the model is a population pharmacokinetic (PK) and/or pharmacodynamic (PD) model and the data is clinical or pre-clinical PK and/or PD data.\n\nIn the context of model building, evaluation and qualification, it is good practice to assess the goodness-of-fit of models by inspecting (qualitatively and quantitatively) a set of graphs that indicate how well the model describes the data. Several types of diagnostic plots allow to evaluate a mixed effects model fit, the most common being:\n\na. residual-based plots\nb. prediction-based plots\nc. empirical Bayes estimates (EBE)-based plots\nd. simulation-based plots.\n\nThe following figures are examples of diagnotic plots. \n```{r illustrate_diagnostic, out.width='.25\\\\linewidth', fig.width=4, fig.height=4, fig.show='hold', echo=FALSE}\nctr \u003c- theophylline()\nctr %\u003e% pmx_plot_dv_pred\nctr %\u003e% pmx_plot_npde_time\nctr %\u003e% pmx_plot_vpc\nctr %\u003e% pmx_plot_eta_box\nctr %\u003e% pmx_plot_eta_matrix(\n  shrink=list(size=3, hjust=1.5, fun=\"var\"))\n```\n\nThis document introduces the ggPMX functionalities and syntax. \n\n## Architecture \n\nThe high level architecture is represented in the figure below. The key components of the package are the following:\n\n* **Reader** - reads model outputs from different sources (i.e. text files containing population parameters, model predictions, individual random effects, simulations and data-related inputs like covariates) and restructures these outputs into standard formats for internal processing.\n* **Generator** ??? processes outputs from Reader. It contains R language code to produce the plots and is factorized into a small set of flexible key functions.  A set of default plots is defined in a configuration file. The configuration file can be adapted, e.g., to have different configurations for different types of modeling activities. \n* **Controller** - serves as user interface. The user will call Generator functions via wrapper functions in the Controller to produce either all the default plots or selected plots of interest. In addition to editing the configuration, the user has different options to adapt aspects of the plots to specific requirements. Plots may be adapted by setting parameters of the wrapper functions that generate the plots; there exist additional wrapper functions to change aspects of the existing default plots. The plots are, in general, returned as ggplot objects that can be further customized using ggplot functionalities. \n* **Reporter** - generates sets of graphs and tables and integrates them into an output file (Word or PDF) with annotations.\n\n```{r echo=FALSE, out.width='80%', fig.align='center'}\nknitr::include_graphics(\"man/figures/ggPMX_arch.png\")\n```\n\nThe package is coded using object-oriented programming meaning that information is encoded in objects. The user can change or print the content of objects via functions. Such an implementation allows to have code that is modular and easily customizable. \n\n## Workflow overview\n\nThe typical workflow of ggPMX is as follows:\n\n1. The user creates the Controller using pre-defined configurations (yaml templates) for plot settings.\n2. The Controller implicitly calls the Reader that reads and stores modelling outputs into a standard format. As a result, the Controller contains all available plots with their default values according to the configuration used.\n3. The Generator allows to print the available plots by calling the corresponding functions. Plots can be modified by using optional arguments.\n4. A call to the Reporter allows to create a pdf or docx report. The report Rmarkdown template can also be personalized.\n\nThe most important task for the user is the Controller creation. This step requires careful consideration because it involves different options according to the type of model (PK or PKPD) and software (Monolix, NONMEM or nlmixr) used for model fitting. The next section describes the Controller creation for the different possible cases.\n\nOnce the Controller is created, it implicitly calls the Reader and creates the diagnostic plots. The user can then generate the graphs by calling pre-defined functions. The same syntax is used independent of the model structure (PK or PKPD model) and of the fitting software.\n\nThe Reporter creates one report per endpoint, i.e., one report for PK and one for each PD endpoint. \n\n## Modeling datasets\n\nFor the sake of this document, three types of datasets are defined.\n\n* The *input modeling dataset* is the one used for model fitting (the actual data). There are no particular requirements regarding this dataset.\n* The *output modeling datasets* are those output from the fitting tool (Monolix, NONMEM or nlmixr). See the appendix for more details on software requirements.\n* The *ggPMX datasets* are the ones created within (internal to) ggPMX. \n\n\n# Controller\nA diagnostic session starts with the creation of a Controller. The Controller is the \"user interface\" of the package and allows to conrol all possible options. It is a container that stores configuration fields (model- and input data-related information), datasets and plots. It can be used as a reference object in which the user can see the names of the exisitng plots, the names of the `ggPMX` datasets, etc. The syntax of the Controller creation differs depending on the software used for model fitting and on the number of model endpoints (or outputs). This section presents different cases of Controller creation. For simplicity, the case of models with one single output is presented first, then generalized to several outputs.\n## Single-endpoint models\n\nIn general, models with only one endpoint (or output) are mostly PK models, but these could also be k-PD models. \n\nTo illustrate `ggPMX` functionalities, the single-endpoint built-in model called **theophylline** is used hereafter. The **theophylline** population PK example has the following characteristics:\n\n- The input modeling data contains PK samples of 2 studies, each with 25 individuals who recieved a unique dose of 2000 mg theophylline. \n- The model is a simple one-compartmental PK model with first-order absorption. \n- The following covariates are used: weight (WT0) on volume (V) and clearance (Cl), age (AGE0), sex (SEX) and study (STUD) on clearance. \n- Random effects on all three parameters (ka, Cl, V) are included. \n- The residual error is proportional.\n\nThe input modeling dataset has the following columns:\n```{r,echo=FALSE}\ntheophylline_path \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir          \u003c- file.path(theophylline_path, \"Monolix\")\ninput_data_path   \u003c- file.path(theophylline_path, \"data_pk.csv\")\n\ninput_data_theo   \u003c- read.csv(input_data_path)\nhead(input_data_theo)\n```\nNote that the DVID (or CMT/YTYPE) column is missing, but since this is a single-endpoint model, it is not necessary in that case.\n\n```{r,echo=FALSE,results='asis',out.width='.9\\\\linewidth'}\n\nout \u003c- rbind(\n  c(\"sys\", \"Software used for model fittng (Monolix or nlmixr)\", \"mlx, mlx2018, nm\"),\n  c(\"config\", \"A pre-defined configuration is a set of default settings\", \"standing\"),\n  c(\"directory\", \"Path to the directory containing model output files\", \"\"),\n  c(\"input\", \"Path to input modeling dataset (dataset used for model fitting)\", \"\"),\n  c(\"dv\", \"Measurable variable name, as defined in the input modeling dataset\", \"DV, LIDV, LNDV, Y, etc.\"),\n  c(\"dvid\", \"Endpoint (output) name, as defined in the input modeling dataset\", \"DVID, YTYPE, CMT, etc.\")\n)\n\ncolnames(out) \u003c- c(\"Argument\", \"Description\", \"Values\")\n\nxt \u003c- xtable(head(out), label = \"tab:pmx_mandatory\", caption = \"Mandatory arguments of pmx() function\")\nprint(xt, comment = F)\n```\n\n## Controller creation\n\nThe Contoller creation is wrapped in a function called \"theophylline()\" for quick reference:\n```{r}\nctr \u003c- theophylline()\n```\n\n### Models fitted with Monolix (versions 2016 and later) \n\n#### `pmx_mlx()`\n\nThe controller initialization using the Monolix controller `pmx_mlx()`, which is a wrapper function for `pmx()` with `sys=\"mlx\"` (See Appendix A).\n```{r, eval = FALSE}\ntheophylline_path \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir          \u003c- file.path(theophylline_path, \"Monolix\")\ninput_data_path   \u003c- file.path(theophylline_path, \"data_pk.csv\")\n\nctr \u003c- pmx_mlx(\n  directory = work_dir,\n  input     = input_data_path,\n  dv        = \"Y\"\n)\n```\n\n####`pmx_mlxtran()`\n\nThe controller initialization can be simplified by using the Monolix controller `pmx_mlxtran()`. This function parses the mlxtran file of a Monolix project and assigns automatically the different fields necessary to the Controller creation. The only mandatory argument is file_name, the path to the mlxtran file.\n```{r, eval = FALSE}\nmlxtran_path \u003c- file.path(system.file(package = \"ggPMX\"), \n                          \"testdata\", \"1_popPK_model\", \"project.mlxtran\")\n\nctr \u003c- pmx_mlxtran(file_name = mlxtran_path)\n```\nThe user can verify the content of the Controller and how parameters are assigned by printing it. \n\n\n### Models fitted with NONMEM (versions 7.2 and later) \n\n#### `pmx_nm()`\n\nThe controller initialization using the NONMEM controller `pmx_nm()` is based on reading functions of the xpose package.\nIt is highly recommended (but not required) to use the \"sdtab, patab, cotab, catab\" table naming convention followed by a run number (e.g. sdtab001,cotab001)\nThis will enable automatic recognition of covariates. It is also recommended to name the model files accordingly (e.g. run001.lst). \nIn order to generate a VPC a simulation dataset is required (see section about VPC)\n\nFor controller generation it is recommended to use the model file:\n```{r, eval = FALSE}\nnonmem_dir \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\",\"extdata\")\nctr \u003c- pmx_nm(\n  directory = nonmem_dir,\n  file     = \"run001.lst\" \n)\n```\n\nor the run number. The standard prefix is \"run\", however can be specified using `prefix`\n```{r, eval = FALSE}\nnonmem_dir \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\",\"extdata\")\nctr \u003c- pmx_nm(\n  directory = nonmem_dir,\n  runno     = \"001\" #can be a string or a number\n)\n```\n\n\n### Models fitted with nlmixr\n\n#### `pmx_nlmixr()`\n\nIt is simple to create a ggPMX controller for a nlmixr object using `pmx_nlmixr()`.\nUsing the theophylline example with a nlmixr model we have:\n\n```{r, eval = FALSE}\none.cmt \u003c- function() {\n  ini({\n    ## You may label each parameter with a comment\n    tka \u003c- 0.45 # Log Ka\n    tcl \u003c- 1 # Log Cl\n    ## This works with interactive models\n    ## You may also label the preceding line with label(\"label text\")\n    tv \u003c- 3.45; label(\"log V\")\n    ## the label(\"Label name\") works with all models\n    eta.ka ~ 0.6\n    eta.cl ~ 0.3\n    eta.v ~ 0.1\n    add.sd \u003c- 0.7\n  })\n  model({\n    ka \u003c- exp(tka + eta.ka)\n    cl \u003c- exp(tcl + eta.cl)\n    v \u003c- exp(tv + eta.v)\n    linCmt() ~ add(add.sd)\n  })\n}\n\nfit \u003c- nlmixr(one.cmt, theo_sd, est=\"saem\", control=list(print=0))\n```\n\nThe `fit` object is a nlmixr fit; You can read it into the nlmixr controller by:\n\n```{r, eval = FALSE}\nctr \u003c- pmx_nlmixr(fit, \n                  vpc = FALSE ## VPC is turned on by default, can turn off\n)\n```\n\n### Optional arguments for controller creation\n\nThe following are some optional arguments to the controller function (for details of each option, see the corresponding section or use `?pmx_mlx`, `?pmx_nm`, `?pmx_nlmixr`):\n\n* cats: character vector of categorical covariates\n* conts: character vector of continuous covariates\n* occ: character occasional covariate variable name (currently not available for NONMEM or nlmixr)\n* strats: character extra stratification variables\n* settings: global pmxSettingsClass (`pmx_settings()`) shared between all plots\n* endpoint: pmxEndpointClass (`pmx_endpoint()`) or integer or charcater of the endpoint code (depends on the fitting software)\n* sim: pmxSimClass object for VPC generation. (syntax for VPC generation is depending on the fitting software)\n\n\n## Multiple-endpoint models\n\nModels with more than one endpoint (or output) are mostly PKPD models, but these could also be, for example, PK binding models in which there are measurements and predictions of both PK and its target.\n\nggPMX produces one diagnostics report per endpoint. As a consequence, the endpoint (if more than one) should be set at the time of the Controller creation in order to filter the observations dataset and to keep only the values corresponding to the endpoint of interest. There are two ways of dealing with endpoints, using pmx_endpoint() (only for Monolix), or a simplified syntax for endpoints which is supported by all software outputs.\n\n### Using pmx_endpoint() (only for Monolix)\n\nTo handle this, the user creates an \"endpoint\" object using the function `pmx_endpoint()` having the following attributes:\n\n- **code** (charcater): how the endpoint is coded in the input (modeling) dataset\n- **label**: can be used in the title of some plots or for the report file name\n- **unit**: used in the axis label for some plots\n- **files** (list): `list(predictions=\"predictions1\",finegrid =\"finegrid1\")` \n- **trans**: whether the value must be transformed before being displayed and which transformation to use.\n\nTo illustrate the Controller creation with multiple-endpoint models, a built-in PKPD example is used. The input dataset is called pk_pd.csv and has the following columns.\n\n```{r, echo=F}\npkpd_path       \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"pk_pd\")\npkpd_work_dir   \u003c- file.path(pkpd_path, \"RESULTS\")\npkpd_input_file \u003c- file.path(pkpd_path, \"pk_pd.csv\")\n\ninput_data \u003c- read.csv(pkpd_input_file)\nhead(input_data)\n```\n\nThe dvid column contains values=3 for PK (first endpoint) and dose and =4 for PD (second endpoint). Monolix2016 outputs are found in folder RESULTS/ which contains predictions1.txt and finegrid1.txt for PK predictions, and predictions2.txt and finegrid2.txt for PD predictions. The Endpoint and Controller objects are created as follows:\n```{r}\npkpd_path       \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"pk_pd\")\npkpd_work_dir   \u003c- file.path(pkpd_path, \"RESULTS\")\npkpd_input_file \u003c- file.path(pkpd_path, \"pk_pd.csv\")\n\nep \u003c- pmx_endpoint(\n  code  = \"4\",\n  label = \"some_label\",\n  unit  = \"some_unit\",\n  file.code = \"2\", # will use predictions2.txt and finegrig2.txt\n  trans = \"log10\"\n)\n\nctr \u003c- pmx_mlx(\n  directory = pkpd_work_dir,\n  input     = pkpd_input_file,\n  dv        = \"dv\",\n  dvid      = \"dvid\",\n  endpoint  = ep\n)\n```\n\n### A simplified syntax for endpoints (for Monolix, NONMEM and nlmixr)\nFor NONMEM and nlmixr users, endpoint can be simply specified  in the controller creation by e.g. `endpoint = 1`\n\nNONMEM\n```{r, eval = FALSE}\nctr \u003c- pmx_nm(\n  directory = nonmem_dir,\n  file     = \"run001.lst\",\n  endpoint = 1 ## select the first endpoint \n  dvid = \"DVID\" ## use this column as observation id \n)\n```\n\nnlmixr\n```{r, eval = FALSE}\nctr \u003c- pmx_nlmixr(fit, \n                  endpoint = 1 ## select the first endpoint \n                  dvid = \"DVID\" ## use this column as observation id \n)\n```\n\nAlso for Monolix users, a simplified syntax for the Endpoint creation exists in the case where the endpoint code matches the files post-fixes (code=1 corresponds to predictions1.txt, code=2 corresponds to predictions2.txt). Instead of passing a pmxEndpoint object as argument of the Controller, the user can specify the numerical value corresponding to the YTYPE/CMT/DVID column.\n```{r, echo=T, eval = FALSE}\npmx_mlx(\n  dvid = \"YTYPE\", ## use this column as observation id \n  endpoint = 1,   ## select the first endpoint \n  ...)            ## other pmx parameters , config, input,etc..\n```\nInternally, a pmxEndpoint object will be created, and observations having YTYPE=x will be filtered.  \n\n### Note: dependent variable renaming for Monolix\n\nWhen fitting a multiple-endpoint model, Monolix is known to rename endpoint variables to y1, y2.\nFor controller creation to work it may necessary to reverse this renaming in the simulation file (e.g. y1 -\u003e LIDV).\n\n## Controller with covariates\n\nBesides the mandatory fields to initialize a Controller, the user can set optional parameters related to covariates. This feature is illustrated below with the Theophylline example.\n\n```{r init_ctr_covar}\ntheophylline_path \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir          \u003c- file.path(theophylline_path, \"Monolix\")\ninput_data_path   \u003c- file.path(theophylline_path, \"data_pk.csv\")\n\nctr \u003c- pmx_mlx(\n  directory = work_dir,\n  input     = input_data_path,\n  dv        = \"Y\",\n  cats      = c(\"SEX\"),\n  conts     = c(\"WT0\", \"AGE0\"),\n  strats    = c(\"STUD\", \"SEX\")\n)\n```\n`Conts` are the continuous covariates. `Cats` are categorical covariates used in the model, whereas `strats` are categorical variables that can be used for plot stratification, but are not used as covariates in the model.\n\nThe covariates can be accessed using helper functions:\n\n```{r get_covar}\nctr %\u003e% get_cats()\nctr %\u003e% get_conts()\nctr %\u003e% get_strats()\nctr %\u003e% get_covariates()\n```\n\n\n## Controller content\nThe content of the Controller can be seen by printing it:\n```{r display_ctr}\nctr\n```\n\nIt contains three tables:\n\n- The first table is the Controller configuration. The user can see the working directory, the input modeling dataset name, the dependent variable (DV) name and other fields related to the model (e.g., continuous and discrete covariates).\n\n- The second table lists the `ggPMX` datasets. The first column (`data_name`) of this table contains the ggPMX name of the dataset; the second column (data_file) contains the names of the output modeling datasets (for example estimates.txt); in the third column (data_label) contains the dataset description.\n\n- The third table provides the list of available plots in the Generator. It corresponds to Table \\ref{tab:plots_list}.\n\n\n### Plot names\n\nThe Controller is a container that stores all plots. To get the list of plots, the function `plot_names()` is used:\n```{r plot_lists}\nctr %\u003e% plot_names()\n```\nAn alternative way to display the names of the existing plots is by printing the content of the Controller as done above.\n\n`ggPMX` provides a specialized function to create and update each plot `pmx_plot_xx()` where `xx` is the plot name from the list above. \n\n### Plot types\n\nEach plot type is a class of similar plots. `ggPMX` defines the following plot types:\n\n  + SCATTER: residual plots\n  + IND: individual plots display longitudinal (time course) predictions and data (one panel per individual)\n  + DIS: distribution of empirical Bayes estimates (EBE) histogram or boxplot\n  + ETA_PAIRS: random effects (ETA) distributions and correlations structure\n  + ETA_COV: relationships between random effects (ETA) and continuous or categorical covariates\n  + PMX_QQ: quantile-quantile plot (qq-plot)\n\nThe following syntax allows to see which type of plot corresponds to which plot name:\n```{r plot_types}\nctr %\u003e% plots()\n```\n\n```{r datasets_list,echo=FALSE,results='asis'}\n\nout \u003c- rbind(\n  c(\"input\", \"Input modeling dataset\"),\n  c(\"estimates\", \"Estimated population parameters\"),\n  c(\"eta\", \"Random effects, their standard deviation and residual errors (to calculate shrinkage)\"),\n  c(\"predictions\", \"Observations and predictions at times of observations dataset\"),\n  c(\"finegrid\", \"Additional predictions (at times without observations)\")\n)\n\ncolnames(out) \u003c- c(\"ggPMX dataset\", \"Description\")\n# knitr::kable(out)\n# latex(head(out), file='', label='tab:ggPMX_datasets', caption='ggPMX datasets',where = \"!htbp\")\nxt \u003c- xtable(head(out), label = \"tab:ggPMX_datasets\", caption = \"ggPMX datasets\")\nprint(xt, comment = F)\n```\n\n# Default diagnostic plots\n```{r echo=FALSE}\ntheophylline \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir \u003c- file.path(theophylline, \"Monolix\")\ninput_data \u003c- file.path(theophylline, \"data_pk.csv\")\n\nctr \u003c- theophylline()\n```\n\nThe diagnostic plots of ggPMX are generated by calling the functions `pmx_plot_xx()` where `xx` is a placeholder for the plot name. The list of names of all available plots can be seen via:\n```{r}\nctr %\u003e% plot_names()\n```\n\nAs a convention, when plots are described as ???Y vs. X???, it is meant that Y is plotted on the vertical axis and X on the horizontal axis.\n\nAs an example, a plot of individual weighted residuals (IWRES) versus time (with default settings) can be generated using a single-line code:\n```{r fig.height=5, fig.width=8}\nctr %\u003e% pmx_plot_iwres_time\n```\n\nThe complete list of available plots per plot type (given in parenthesis) is given below:\n\n- Residual plots (**SCATTER**)\n```{r basics_res, eval=F, out.width='.48\\\\linewidth', fig.height=4, fig.width=6, fig.show='hold', fig.align='center'}\nctr %\u003e% pmx_plot_dv_pred\nctr %\u003e% pmx_plot_dv_ipred\n\nctr %\u003e% pmx_plot_iwres_time\nctr %\u003e% pmx_plot_npde_time\n\nctr %\u003e% pmx_plot_iwres_ipred\nctr %\u003e% pmx_plot_abs_iwres_ipred\n\nctr %\u003e% pmx_plot_npde_pred\n```\n\n- Empirical Bayes Estimates (EBE), also called \"eta\", histogram and boxplot (**DIS**)\n```{r basics_ebe_hist, eval=F , fig.height=3, fig.width=3, fig.show='hold', fig.align='center'}\nctr %\u003e% pmx_plot_eta_hist\nctr %\u003e% pmx_plot_eta_box\n```\n\n- Individual plots (**IND**)\n```{r basics_indiv, eval=F, fig.height=6, fig.width=6, fig.show='hold', fig.align='center'}\nctr %\u003e% pmx_plot_individual(which_pages = 1)\n```\n\n- QQ-plots (**PMX_QQ**)\n```{r basics_qq, eval=F, fig.height=3, fig.width=3, fig.show='hold', fig.align='center'}\nctr %\u003e% pmx_plot_npde_qq\nctr %\u003e% pmx_plot_iwres_qq\n```\n\n- Distribution and correlation structure of random effects (**ETA_PAIRS**)\n```{r basics_matrix_plot, eval=F,  fig.height=6, fig.width=6, fig.show='hold', fig.align='center'}\nctr %\u003e% pmx_plot_eta_matrix\n```\n\n# Visual Predictive Checks (VPC)\n\n## Initialization\n\nIn order to generate VPCs a simulation dataset is requried. Creation of VPC is slightly different dependening on the fitting software used (Monolix, NONMEM or nlmixr). Make sure to use the same name for the dv column in the simulation file as the one used in the input (modeling dataset).\n\n### Models fitted with Monolix (versions 2016 and later) \n\nMonolix users, need to run a simulation with simulx. Here's an example code\n\n```{r, eval = FALSE}\n## Create simulated object using simulx\nmysim \u003c- simulx(project=project_dir, nrep=100) #\n## Retrieve simulated dataset (assumed to be in y1)\nsimdata \u003c- mysim$LIDV\n```\n\nFor use with ggPMX, it is required that the IDs are reverted to the original IDs as in the modelling dataset for ggPMX.\n\n```{r, eval = FALSE}\n## Need to revert the original IDs as in modeling dataset for ggPMX\n## Rename IDs column to same name as in modeling dataset, e.g.\n## ???id??? in the example below\nsimdata \u003c- simdata %\u003e% \n  mutate(newId = as.numeric(as.character(id))) %\u003e%\n  left_join(., mysim$originalId) %\u003e%\n  mutate(id = as.numeric(as.character(oriId))) %\u003e%\n  select(-oriId, -newId) %\u003e%\n  data.table::data.table()\n\n## It's highly recommended to store your simulation as .csv\nvpc_file \u003c- write.csv(simdata, file = \"my_VPC.csv\", quote=FALSE, row.names = FALSE)\n```\n\n`pmx_sim` creates a simulation object. It takes the following arguments:\n\nArgumentss\n\n1. **file**\tcharacter path to the simulation file\n2. **irun**\tcharacter name of the simulation column\n3. **idv**\tcharacter name of the ind. variable\n4. **dv**\tcharacter name of the observation variable\n\n\nWithin pmx vpc controller, it is called like : \n\n```{r }\n\ntheoph_path \u003c- file.path(\n  system.file(package = \"ggPMX\"), \"testdata\",\n  \"theophylline\"\n)\nWORK_DIR \u003c- file.path(theoph_path, \"Monolix\")\ninput_file \u003c- file.path(theoph_path, \"data_pk.csv\")\nvpc_file \u003c- file.path(theoph_path, \"sim.csv\")\n\nctr \u003c- pmx_mlx(\n  directory = WORK_DIR,\n  input = input_file,\n  dv = \"Y\",\n  cats = c(\"SEX\"),\n  conts = c(\"WT0\", \"AGE0\"),\n  strats = \"STUD\",\n  settings = pmx_settings(\n    use.labels=TRUE,\n    cats.labels=list(\n      SEX=c(\"0\"=\"Male\",\"1\"=\"Female\")\n    )\n  ),\n  sim = pmx_sim(\n    file = vpc_file,\n    irun =\"rep\",\n    idv=\"TIME\"\n  )\n)\n\n\n```\n\n### Models fitted with NONMEM (versions 7.2 and later) \n\nIt is required to provide simulation tables to generate VPCs. Furthermore, it is highly recommended that simulation tables have a \"sim\"-suffix and are kept with the same naming convetion as for the prediction tables (e.g sdtab001sim, catab001sim)). In this case they're automatically recognized by the runnumber (runno) or by the model file if specified there. For post-hoc simulation it is possible to include an additional simfile:\n\n```{r, eval = FALSE}\nctr \u003c- pmx_nm(\n  directory = model_dir,\n  file      = \"modelfile.ctl\" #or .lst\n  simfile   = \"simulation_modelfile.ctl\" #or .lst\n)\n```\n\nImportant: When simulations are performed post-hoc and the controller is generated by run number, the reader might load the wrong .ext file (used for parameters). A warning message is displayed.\n\n### Models fitted with nlmixr\n\nFor nlmixr users, the VPC is generated automatically with the controller creation and turned on by default `vpc = TRUE`.\n\n```{r, eval = FALSE}\nctr \u003c- pmx_nlmixr(fit) ## VPC will be generated automatically, vpc = TRUE\n\nctr \u003c- pmx_nlmixr(fit, \n                  vpc = FALSE ## But can be turned off\n)\n```\n\n## VPC plot\n\nThe plot options are described in `?pmx_plot_vpc` function. \n\n### Default\n\n```{r}\nctr %\u003e% pmx_plot_vpc\n```\n\n### Scatter/Percentile\n\nBy default the vpc plot is **percentile** ; , but we can plot the **scatter** type:\n```{r}\nctr %\u003e% pmx_plot_vpc(type =\"scatter\")\n```\n\n### Binning\n\n```{r}\nctr %\u003e% pmx_plot_vpc(bin=pmx_vpc_bin(style = \"kmeans\",n=5))\n```\n\n### Set custom x- and/or y-axis labels\n\n```{r}\nctr %\u003e% pmx_plot_vpc(labels = c(x = \"DV axis\", y = \"TIME axis\"))\n```\n\n### Stratification \n\n```{r}\nctr %\u003e% pmx_plot_vpc(strat.facet=~SEX,facets=list(nrow=2))\n```\n\n### Monolix-like customisation\n\nUser can customize the options to get a Monolix-like display.\n\n```{r}\nctr %\u003e% pmx_plot_vpc(\n  strat.facet=~SEX,\n  facets=list(nrow=2),\n  type=\"percentile\",\n  is.draft = FALSE,\n  pi = pmx_vpc_pi(interval = c(0.1,0.9),\n              median=list(color=\"green\"),\n              extreme= list(color=\"green\")),\n  obs = pmx_vpc_obs(color=\"blue\",shape=18,size=2),\n  ci = pmx_vpc_ci(interval = c(0.1,0.9),\n              median=list(fill=\"red\"))\n)\n```\n\n\n\n# Diagnostics report\n```{r echo=FALSE}\ntheophylline \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir \u003c- file.path(theophylline, \"Monolix\")\ninput_data \u003c- file.path(theophylline, \"data_pk.csv\")\n\nctr \u003c- theophylline()\n```\n\nA report (in pdf and docx format) containing all default diagnostic plots can be created using the *pmx_report* function. The *output* can take three different values:\n\n- \"report\": produces a pdf and a docx file (named `name.pdf` and `name.png` specified in argument *name*, located in *save_dir*) with default diagnostic plots\n- \"plots\": produces a folder named after *plots_subdir* parameter (`ggpmx_GOF` by default, if parameter is not specified) located in *save_dir* that contains all default diagnostic plots, each in a pdf and png file. The different plots are numerated in order to have an unique identifier for each plot (ex: ebe_box-1.pdf). This is necessary for having correct footnotes that indicated the path to the source file (for submission reports).\n- \"all\": is a combination of both options above.\n\nExample:\n```{r eval=FALSE}\nctr %\u003e% pmx_report(name='Diagnostic_plots2',\n                   save_dir = work_dir,\n                   plots_subdir = \"ggpmx_report\",\n                   output='all')\n```\n\nNote that running the same command first with the option \"output='plots'\" and then with the option \"output='report'\" will remove the *ggpmx_GOF* folder. \n\nNote also that by default, the report will have the DRAFT label on all plots. The label can be removed by using the settings argument in the Controller creation.\n\nThe user can customize the default report by creating a \"template\". To create a template, the user should create first a default report with the following command:\n```{r eval=FALSE}\nctr %\u003e% pmx_report(name='Diagnostic_plots1',\n                   save_dir = work_dir,\n                   plots_subdir = \"ggpmx_report\",\n                   output='report')\n```\nThe Rmarkdown (.Rmd) file is the \"template\". The user can modify the Rmarkdown file as desired (ex: changing the size of some figures) and save the modified file. The new template can be used with the following command:\n```{r eval=FALSE}\nctr %\u003e% pmx_report(name='Diagnostic_plots3',\n                   save_dir = work_dir,\n                   plots_subdir = \"ggpmx_report\",\n                   output='report',\n                   template=file.path(work_dir,'Diagnostic_plots1.Rmd'))\n```\n\n\n# Customizing plots\nAny particular plot can be customized in two ways:\n\n-\tSpecifying options in each call of a plot (on the fly, recommended): \n```{r eval=F}\nctr %\u003e% pmx_plot_xx(list of options)\n```\n\n-\tCustomizing a type of plot for all subsequent calls in the session by modifying the Controller:\n```{r eval=F}\nctr %\u003e% pmx_update(???xx???, list of options)\n```\n\nHelp(pmx_gpar) lists some options. \n\nHelp(pmx_plot_xx) lists some possible parameters to update a particular plot. \n\nTo obtain an exhaustive list of possible options for a particular plot, use the following:\n```{r eval=F}\nctr %\u003e% get_plot_config(\"xx\")\n```\n\n## Visualization of BLQs (Monolix and NONMEM)\nIt is possible to visualize BLQ (below the limit of quantification) values in the individual plots.\nFor this, `bloq` needs to be specified using the pmx_bloq function (see example below with the `pmx_mlxtran()` function).\n```{r eval=F}\nctr %\u003e% pmx_mlxtran(file_name = mlx_file, bloq=pmx_bloq(cens = ???BLQ???, limit = ???LIMIT???))\nctr %\u003e% pmx_plot_individual()\n```\n\n## Simulated BLOQ (Monolix 2018 and later)\n\nMonolix users may want to plot simulated BLQs. This is possible for outputs with Monolix 2018 and later.\nAn additional dataset is loaded (sim_blq), which will be used for plotting insted the regular \"predictions\"-dataset.\n\nThe `sim_blq` statment can be specified within the plot (locally) ...\n```{r eval=F}\nctr %\u003e% pmx_mlxtran(file_name = mlx_file))\nctr %\u003e% pmx_plot_iwres_ipred(sim_blq = TRUE)\n```\n\n... or within the controller (globally).\nIf this statment is used within the controller, all corresponding plots will plot simulated BLOQs by default.\n```{r eval=F}\nctr %\u003e% pmx_mlxtran(file_name = mlx_file, sim_blq = TRUE))\nctr %\u003e% pmx_plot_iwres_ipred()\n```\n\n\n## Customizing global settings - `pmx_settings()`\n\nThe user can define a Controller with global settings that will be applied to all plots. For example remove draft annoataion, use abbreviation defintions to define axis labels, etc. \n\nA settings object is defined by using the function `pmx_settings()`. The created object is passed as the parameter \"settings\" to `pmx()`. By doing so, the settings are defined globally and apply to all plots. For a complete list of global settings with their corresponding default values, please consult the ggPMX Help (`?pmx_settings`).\n\n```{r settings_example, fig.width=5, fig.height=4,eval=FALSE}\n\n## set one or more settings\nmy_settings \u003c- pmx_settings(\n  is.draft   = FALSE,\n  use.abbrev = TRUE,\n  ...) ### set other settings parameters here \nctr \u003c-\n  pmx_mlx(\n    ..., ## put here other pmx parametes \n    settings = my_settings\n  ) \n```\n\n\n### Remove DRAFT label globally \n\nBy default in the \"standing\" configuration, a DRAFT label is printed on all plots. In order to switch this label off, the user sets the `is.draft` option of `pmx_settings()` to `FALSE`.\n\n```{r settings_is_draft,fig.height=3, fig.width=3, fig.show='hold', fig.align='center'}\n\nctr \u003c- theophylline(settings = pmx_settings(is.draft = FALSE))\n\n```\n\n### Reordering facet panels\n\nThe order of factors in a facet plot is determined by the data contained in the predictions data frame. Ordering of facet panels can be performed by changing the factor specification for facet columns in the *predictions* data frame.\n\nThe example below defines a Controller with changed SEX facet panels order: 1 will be plotted before 0 rather than the other way round.\n\n```{r, eval=FALSE}\nctr \u003c- theophylline()\nctr[[\"data\"]][[\"predictions\"]][[\"SEX\"]] \u003c-\n  factor(ctr[[\"data\"]][[\"predictions\"]][[\"SEX\"]], levels=c(\"1\",\"0\"))\n\npmx_plot_iwres_ipred(ctr, strat.facet=~SEX)\n```\n\n### Use abbreviation definitions \n\nThe standing configuration initializes all plots using abbreviations for axis labels. Each abbreviation has its corresponding definition. To get the list of abbreviation : \n\n```{r settings_get_abbrev}\nctr %\u003e% get_abbrev\n```\nYou can update one abbreviation to set a custom label \n\n```{r settings_set_abbrev}\nctr %\u003e% set_abbrev(TIME=\"TIME after the first dose\")\n```\n\nUsing `use.abbrev` flag you can use abbreviation definition to set axis labels:\n\n```{r settings_use.abbrev}\nctr \u003c- theophylline(settings=pmx_settings(use.abbrev = TRUE))\nctr %\u003e% set_abbrev(TIME=\"Custom TIME axis\")\nctr %\u003e% pmx_plot_npde_time\n\n```\n\n### Use `finegrid.txt` file for individual plots\n\nwithin Monolix, user can choose to not use finegrid file even if it is present. \n\n```{r settings_use.finegrid}\nctr \u003c- theophylline()\nctr %\u003e% pmx_plot_individual(use.finegrid =FALSE, legend.position=\"top\")\n```\n\n### Set stratification color legend\n\nIn case of color startfication user can customize the legend. For example here using the `ggplot2::scale_color_manual`:\n\n```{r settings_color_scales_local}\nctr \u003c- theophylline()\nctr %\u003e% pmx_plot_npde_time(strat.color=\"STUD\")+ \n      ggplot2::scale_color_manual(\n        \"Study\",\n        labels=c(\"Study 1\",\"Study 2\"),\n        values=c(\"1\"=\"green\",\"2\"=\"blue\"))\n    \n\n```\n\nAnother way to do it is to define a global `scales.color` parameter that will applied to all plots with strat.color :\n```{r settings_solor_scales,fig.height=5, fig.width=8}\n\nctr \u003c- theophylline(\n  settings=\n    pmx_settings(\n      color.scales=list(\n        \"Study\",\n        labels=c(\"Study 1\",\"Study 2\"),\n        values=c(\"1\"=\"orange\",\"2\"=\"magenta\"))\n    )\n)\n\nctr %\u003e% pmx_plot_npde_time(strat.color=\"STUD\")\n```\n\n```{r settings_solor_scales_a,fig.height=5, fig.width=11}\nctr %\u003e% pmx_plot_eta_box(strat.color=\"STUD\")\n```\n\n\n### Define labels of categorical variables\n\nIn case of faceting by stratification user can redfine categorical labels to have more human readables strips. Lables are defined within `cats.labels` argument and user can use them by setting `use.lables` to TRUE.\n\n```{r settings_cat_labels}\n\n\nctr \u003c- theophylline(\n  settings=\n    pmx_settings(\n      cats.labels=list(\n        SEX=c(\"0\"=\"M\",\"1\"=\"F\"),\n        STUD=c(\"1\"=\"Study 1\",\"2\"=\"Study 2\")\n      ),\n      use.labels = TRUE\n    )\n)\n\nctr %\u003e% pmx_plot_npde_time(strat.facet=~SEX)\n```\n\n```{r settings_cat_labels2, fig.height=5, fig.width=8}\n\n\nctr \u003c- theophylline(\n  settings=\n    pmx_settings(\n      cats.labels=list(\n        SEX=c(\"0\"=\"M\",\"1\"=\"F\"),\n        STUD=c(\"1\"=\"Study 1\",\"2\"=\"Study 2\")\n      ),\n      use.labels = TRUE\n    )\n)\n\nctr %\u003e% pmx_plot_npde_time(strat.facet=~SEX)\n```\n\n```{r settings_cat_labels3, fig.height=8, fig.width=8}\nctr %\u003e% pmx_plot_eta_box(strat.facet =~SEX)\n```\n\n### Define binning used for VPC plots\n\nThe type of binning used for VPC plots can be applied as an update to the controller object, causing the binning to be applied to subsequent VPC plots.\n\nUpdating the controller is achieved using `pmx_update` in a command like:\n\n```{r, eval=FALSE}\npmx_update(ctr, \"pmx_vpc\", bin=pmx_vpc_bin(within_strat=TRUE, style=\"jenks\"))\n```\n\nSubsequent VPC plotting calls will then use \"jenks\" style binning. For example:\n\n```{r, eval=FALSE}\nctr %\u003e% pmx_plot_vpc\n```\n\n# Appendix\n\n## Generic Controller creation with `pmx()`\n\nThe function `pmx()` is the generic function for greating a Controller. The user needs to specify a set of arguments such as the path to the model directory, the software used for model fitting (Monolix or nlmixr), the name of a configuration. A list of all existing configurations is provided in the Appendix. All **mandatory** arguments of `pmx()` are listed in Table \\ref{tab:pmx_mandatory}.\n\nThe example below defines a Controller with the *standing* (standard) configuration. \n```{r init_ctr}\ntheophylline_path \u003c- file.path(system.file(package = \"ggPMX\"), \"testdata\", \"theophylline\")\nwork_dir          \u003c- file.path(theophylline_path, \"Monolix\")\ninput_data_path   \u003c- file.path(theophylline_path, \"data_pk.csv\")\n\nctr \u003c- pmx(\n  sys       = \"mlx\",\n  config    = \"standing\",\n  directory = work_dir,\n  input     = input_data_path,\n  dv        = \"Y\",\n  dvid      = \"DVID\"\n)\n```\nNote that the column \"DVID\" of data_pk.csv does not exist; however it is not needed here because there is only one single output of the model. As dvid is a mandatory argument, it still needs to be provided and was set arbritrarly to \"DVID\" in the example above. \n\nThe input dataset can be provided to ggPMX via its location (as in the example above) or as a data frame (maybe give an example). The modeling output datasets have to be in the location that is indicated as working directory (`work_dir` in the example above).\n\n\n## Software requirements\n\nggPMX is compatible with Monolix versions 2016 and later, NONMEM version 7.2 and later, and nlmixr.\n\n### Monolix\n\nIn order to be able to produce all available diagnostic plots, the following tasks should be executed in Monolix during the model fitting procedure:\n\n* Population parameters;\n* Individual parameters (EBEs);\n* Standard errors;\n* Plots.\n\nIn addition, make sure to export charts data (In Monolix 2018: Settings -\u003e Preferences -\u003e Export -\u003e switch on the Export charts data button).\nSelect at least the following plots to be displayed and saved: individual fits and scatter plot of the residuals.\n\n### NONMEM\n\nNONMEM Version 7.2/7.3/7.4\nPreferred output tables according ???sdtab, patab, cotab, catab??? convention\nSimulation are required for creation of VPC (e.g. sdtab1sim)\n\n### nlmixr\n\nFit objects need to be generated by nlmixr and have data attached.\nStandard errors are required (a successful covariance plot) for full diagnostic checks. Can use `boostrapFit()` to get standard error estimates if necessary\n\n\n## Plots table\n\nThe main target of ggPMX is to create a report containing the following plots (see abbreviation list below): \n\n```{r plots_list,echo=FALSE,results='asis'}\n\nout \u003c- rbind(\n  c(\"Scatter plot of NPDE vs population predictions\", \"SCATTER\", \"npde_pred\"),\n  c(\"Scatter plot of NPDE vs time\", \"SCATTER\", \"npde_time\"),\n  c(\"Scatter plot of IWRES vs time\", \"SCATTER\", \"iwres_time\"),\n  c(\"Scatter plot of observations vs population predictions\", \"SCATTER\", \"dv_pred\"),\n  c(\"Scatter plot of observations vs individual predictions\", \"SCATTER\", \"dv_ipred\"),\n  c(\"Scatter plot of absolute value of IWRES vs individual predictions\", \"SCATTER\", \"abs_iwres_ipred\"),\n  c(\"Scatter plot of IWRES vs individual predictions\", \"SCATTER\", \"iwres_ipred\"),\n  c(\"Plots of observations and model predictions per individual\", \"IND\", \"individual\"),\n  c(\"Histogram of EBE\", \"DIS\", \"ebe_hist\"),\n  c(\"Boxplot of EBE\", \"DIS\", \"ebe_box\"),\n  c(\"Distribution and quantile-quantile plot of IWRES\", \"QQ\", \"qq_iwres\"),\n  c(\"Distribution and correlation structure of RE (`ETA`)\", \"ETA_PAIRS\", \"eta_matrix\"),\n  c(\"Relationships between RE and categorical covariates\", \"ETA_COV\", \"eta_cats\"),\n  c(\"Relationships between RE and continuous covariates\", \"ETA_COV\", \"eta_conts\"),\n  c(\"Visual predictive check (VPC)\", \"VPC\", \"vpc\")\n)\n\ncolnames(out) \u003c- c(\"Plot Name\", \"ggPMX type\", \"ggPMX name\")\nxt \u003c- xtable(out, label = \"tab:plots_list\", caption = \"List of all diagnostic plots\")\nprint(xt, comment = F)\n```\nAbbreviations:\n\n- NPDE: normalized prediction distribution errors\n- IWRES: individual weighted residuals\n- EBE: empirical Bayes estimates\n- RE: random effects\n- VPC: visual predivtive check\n\n## ggPMX main functions\n\n`ggPMX` implements few functions to generate and manipulate diagnostic plots. \n(Should we list pmx and pmx_mlx separately and say the differences? Or it's maybe clear from the previous sections.)\n\n```{r functions_list,echo=FALSE,results='asis'}\n\nout \u003c- rbind(\n  c(\"1\", \"pmx, or pmx_mlx\", \"Creates a controller\"),\n  c(\"2\", \"plot_names or plots\", \"Lists controller plots\"),\n  c(\"3\", \"get_data\", \"Lists controller data\"),\n  c(\"4\", \"get_plot\", \"Prints a plot\"),\n  c(\"5\", \"set_plot\", \"Creates a new plot\"),\n  c(\"6\", \"pmx_update\", \"Updates an existing plot\"),\n  c(\"7\", \"pmx_filter\", \"Filters globally the data of the current session\"),\n  c(\"8\", \"pmx_copy\", \"Returns a deep copy of the controller\")\n)\n\ncolnames(out) \u003c- c(\" \", \"Function name\", \"Description\")\n\nxt \u003c- xtable(out, label = \"tab:func_list\", caption = \"List of all `ggPMX` functions\")\nprint(xt, comment = F)\n```\n\n(Apparently, it's not the full list. Add all functions.)\nThe design of the package is around the central object: the controller. It can introspected or piped using the `%\u003e%` operand. \n\n**Note that**:\n\nThe controller is an `R6` object, it behaves like a reference object.  Some functions (methods) can have a side effect on the controller and modify it internally. Technically speaking we talk about chaining not piping here. However, using `pmx_copy` user can work on a copy of the controller.\n\n\n## ggPMX graphical parameters \n\nGraphical parameters in `ggPMX` are set internally using the `pmx_gpar` function. A number of graphical parameters can be set for the different plot types. \n\n```{r pmx_gpar_args}\nargs(pmx_gpar)\n```\nMore information can be found in the help document `?pmx_gpar` and in the examples that follow.\n\n## Pre-defined configurations\n\nFor the moment we are mainly using standing configuration. In the next release user can specfiy configuration either by cretaing a custom yaml file or an R configuration object. Also ggPMX will create many helper functions to manipulate the configuration objects.\n\n\n## Shrinkage\n\n## Default call\n\nThe shrinkage is a computation within controller data. In general it is used to annotate the plots. Although one can get it independently from any plot using `pmx_comp_shrink`. It is part of the `pmx_compt_xx` layer( In the future we will add , `pmx_comp_cor` , `pmx_comp_summary`,..)\n\nHere the basic call:\n\n```{r shrink_comp}\nctr %\u003e% pmx_comp_shrink\n```\n\n\nWe get the shrinkage for each effect (**SHRINK** column).\n\nThe same values can be shown on distribution plot , for example  : \n\n```{r shrink_plot_box}\nctr %\u003e% pmx_plot_eta_box\n\n```\nor : \n```{r shrink_plot_hist,fig.height=8, fig.width=5}\nctr %\u003e% pmx_plot_eta_hist\n\n```\n\nYou can add or remove shrinkage annotation using `is.shrink` argument ( TRUE by default) : \n\n```{r shrink_plot_no}\nctr %\u003e%   pmx_plot_eta_box( is.shrink = FALSE) \n\n```\n\n\n\n## Var function\n\nYou can compute shrinkage by applying either standard deviation `sd` or variance `var` : \n```{r, compute_var }\nctr %\u003e% pmx_comp_shrink(  fun = \"var\")\n```\n\n```{r, shrink_plot_var}\nctr %\u003e% pmx_plot_eta_box( shrink=pmx_shrink(fun = \"var\"))\n```\n\nNote that for plotting functions which take a shrink parameter, this can be created using the `pmx_shrink` function to create a `pmxShrinkClass` object (or it can be a list which can be converted into such an object using `pmx_shrink`).\n\n \n## Shrinkage and stratification\n\nShrinkage can be applied after stratification :\n\n```{r shrink_comp_strat}\nctr %\u003e% pmx_comp_shrink(strat.facet = ~SEX)\n```\nor by grouping like : \n\n```{r shrink_comp_strat_color}\nctr %\u003e% pmx_comp_shrink(strat.color = \"SEX\")\n```\n\nWe can \n```{r shrink_plot_strat, fig.width=9, fig.height=8}\nctr %\u003e% pmx_plot_eta_hist(is.shrink = TRUE, strat.facet = ~SEX,\n                          facets=list(scales=\"free_y\"))\n```\nor \n \n```{r fig.width=12, fig.height=6}\nctr %\u003e% pmx_plot_eta_box(is.shrink = TRUE, strat.facet = \"SEX\",\n                          facets=list(scales=\"free_y\",ncol=2))\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggpmxdevelopment%2Fggpmx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fggpmxdevelopment%2Fggpmx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggpmxdevelopment%2Fggpmx/lists"}