NOTE: This module is currently under active development and this documentation is a work in progress
Introduction
The model building module is constructed around the rxode2 package. It allows you to load a base model from either the model catalog or a user-create file. Once loaded the user can modify a model (change the structure, parameter values, etc), make a copy, etc. You can upload a model in rxode2 format and also NONMEM format. The NONMEM file (control stream or listing output) will be converted after upload into rxode2 using the nonmem2rx package.
Model catalog
The model catalog is built from the sources field of the configuration file. It can include the models from the nlmixr2lib model library. You can also include user defined files. If they are specified but not found, they will be skipped. Edit the MB yaml file to to alter this.
User-defined models
User-defined models can be included in the catalog or uploaded into
the app. These models can be specified in either NONMEM or rxode2
formats. For NONMEM models it can be a control stream (good), the
listing output from an estimation (better), or the XML output from an
estimation (best). To use an nlmixr2 model you simply need a function
definition assigned to the object my_fcn. For examples
see:
system.file(package="ruminate", "templates", "MB_model_rxode2.R")system.file(package="ruminate", "templates", "MB_model_NONMEM.ctl")
Modules are specified in the sources section of the
configuration file. The default configuration file will look in the
working directory of the App for user_model.R and
user_model.ctl. So if you have a rxode2 model you can name
it user_model.R and place it in the app directory to be
included in the catalog. Similarly if you have a NONMEM control stream
you can name it user_model.ctl, and it will be included
automatically. If these do not exist they will be skipped. You can
create as many entries as you want.
Configuration File
# The MC field is a skeleton for constructing new modules
MC:
# Module informaiton
module:
type: "MB"
# internal R Object: module ID used in deployment
depends:
id_ASM: "ASM"
# The prefix of object names created in the generated code
element_object_name: "MB_obj"
# This is a list of model sources. In the app the sources will be listed in
# the order shown here. This is also referred to as the model catalog. If
# the type is set to nlmixr2lib it will insert the models from nlmixr2lib.
# User defined models can be used as well. See the examples below for
# rxode2 and NONMEM models.
#
# - group: This is how models will be grouped in the selection pulldown.
# - name: Short name for the model: **NOTE that names need to be unique**.
# - description: Verbose description of the model.
# - type: Supported model types are "nlmixr2lib", "rxode2" or "NONMEM".
# - obj: For the rxode2 type you need to also specify the name of the object
# that is created. This option is only used for the rxode2 type.
# - file: For both rxode2 and nlmixr2 you need to specify a character string
# with a file path. This will be evaluated as an R command, so keep that
# in mind. If the file is not found it will be skipped when the app loads.
sources:
- source:
group: "User-defined Models"
name: "rxode2 User model"
description: "User-defined rxode2 model"
type: "rxode2"
obj: "my_fcn"
file: 'file.path(getwd(),"user_model.R")'
- source:
group: "User-defined Models"
name: "NONMEM User model"
description: "User-defined NONMEM model"
type: "NONMEM"
file: 'file.path(getwd(),"user_model.ctl")'
- source:
group: "Model Library"
type: "nlmixr2lib"
name: "nlmixr2 Model Library"
# The include section is optional. You can use this section to copy files
# from the directory where you are running the app to the user directory to be
# used in the app and when saved. The source and dest options can be a path
# command like below or a double
# quoted string: '"/path/to/file"'
# The dest should be relative to user directory (think the root of the zip
# file that is exported). See formods.yaml for examples.
#
# include:
# files:
# - file:
# source: 'file.path(system.file(package="onbrand"), "templates", "report.docx")'
# dest: 'file.path("config","report.docx")'
code: # module specific code options
packages: [ "rxode2", "nonmem2rx", "nlmixr2lib"]
readOnly: TRUE
mode: r
# Controls what is shown in the compact ui mode:
compact:
code: TRUE
clip: TRUE
# This is where you put reporting options. The expected options are shown
# here, but module-specific options can also be added if needed:
reporting:
enabled: TRUE
# Priority of reporting relative to other modules
# (higher numbers are reported first)
priority: 1
# put different formatting options (widths, heights,
# shinyWidgets button sizes, etc) here.
formatting:
# Dimensions of code snippet box
code:
width: 800
height: 300
preview:
width: "800px"
height: "500px"
input:
current_element:
width: "200px"
tooltip: "Change the current model."
tooltip_position: "right"
element_name:
width: "200px"
button_clk_run:
size: "sm"
block: TRUE
button_clk_del:
size: "sm"
block: TRUE
tooltip: "Delete the current model."
tooltip_position: "right"
button_clk_save:
size: "sm"
block: TRUE
tooltip: "Save the name for the current model."
tooltip_position: "right"
button_clk_clip:
size: "sm"
block: TRUE
tooltip: "Copy the code to generate the current model to the clipboard."
tooltip_position: "right"
button_clk_copy:
size: "sm"
block: TRUE
tooltip: "Make a copy of the current model."
tooltip_position: "right"
button_clk_append_model:
size: "sm"
block: TRUE
tooltip: "Append to current model."
tooltip_position: "right"
button_clk_new:
size: "sm"
block: TRUE
tooltip: "Create a new model."
tooltip_position: "right"
width: 100
export_nonmem:
size: "sm"
block: TRUE
color: "primary"
tooltip: "Download the current model in NONMEM format."
tooltip_position: "right"
width: 100
export_monolix:
size: "sm"
block: TRUE
color: "primary"
tooltip: "Download the current model in Monolix format."
tooltip_position: "right"
width: 100
catalog_selection:
width: "200px"
truncate: 65
tooltip: "Select base model from the catalog."
tooltip_position: "top"
model_type_selection:
width: "200px"
tooltip: "Select the type of the model being uploaded."
tooltip_position: "right"
choices:
rxode2: "rxode2 function"
NONMEM: "NONMEM (XML, lst, or ctl)"
default: "rxode2"
upload_model_file:
width: "400px"
append_model:
tooltip: "Append the selected sub-model to the current model."
tooltip_position: "bottom"
no_models: "None available"
width: "200px"
base_from:
size: "normal"
status: "primary"
tooltip: "You can select the base model from a catalog or upload your own"
tooltip_position: "bottom"
choices:
catalog: "Model Catalog"
user: "User-defined model"
default: "catalog"
# The timescales here can be altered manually. This is the general format:
# short_name:
# conv: "10"
# verb: "A more verbose name"
# match: ["sn"]
#
# The conv filed is the mathematical conversion between different
# timescales. Below everything is relative to seconds. So the conv for
# seconds is 1. The conv fields for days is
#
# 1 1 day
# conv = ------------------------- = -------------- ---
# sec min 24 hr 60 x 60 x 24 sec
# 60 --- x 60 --- x ------
# min hr day
#
# Generally you dont want to change what is already here in terms of
# these short name used. You can remove timescales you don't want to use
# or add timescales that you need but are not present.
#
# -verb You can change the verb field (what the user sees).
#
# The match field is a list of values that can be matched to the short
# name so if the short name is 'days' when reading in the metadata from
# nlmixr2 models. You you may want to match 'd', 'day', etc.
#
# -match: ["day", "d"]
#
# The order of Appearance is the same order seen here. The default
# is the selected short name for the specified timescale
time_scales:
width: "200px"
default: "weeks"
tooltip: "Choose the timescale of the model."
tooltip_position: "top"
choices:
months:
conv: "1/(60*60*24*7*4)"
verb: "Months"
match: ["mo"]
weeks:
conv: "1/(60*60*24*7)"
verb: "Weeks"
match: ["wk","weeks"]
days:
conv: "1/(60*60*24)"
verb: "Days"
match: ["d", "day", "days"]
hours:
conv: "1/(60*60)"
verb: "Hours"
match: ["hr", "hours", "hrs"]
# min:
# conv: "1/60"
# verb: "Minutes"
# match: ["min", "minutes"]
# sec:
# conv: "1"
# verb: "Seconds"
# match: ["sec", "seconds", "s"]
labels:
current_element: NULL # "Select model"
element_name : NULL # "model name"
upload_model_file: NULL
base_from: NULL
catalog_selection: NULL
export_nonmem: "NONMEM"
export_monolix: "Monolix"
export_pause: "Exporting model."
model_type_selection: NULL
time_scale: NULL
catalog_empty: "No models were found, the catalog is empty"
save_btn: "Save"
clip_btn: "Code"
copy_btn: "Copy"
del_btn: "Delete"
new_btn: "New"
append_model_btn: "Append Model"
append_model: "Available Sub-Models"
building_model: "Building model, be patient."
appending_model: "Appending sub-model, be patient."
element_name_diff: "The model name has changed."
model_code_diff: "Manual changes have been made to the model."
save_change_detected: "You need to click on the save button for these changes to take effect."
head_base_model: "Starting model"
head_model_code: "Model code"
head_time_scale: "Model time-scale"
errors:
no_model_found: "No model was found."
base_model_build_failed: "The base model build failed."
manual_model_update_failed: "Manual model update failed."
user_file_upload_failed: "User-defined model failed."
nlmixr2lib_not_found: "The nlmixr2lib package was not found. This library will not be available."
selected_id_bad_list: "Unable to find a list for the selected component."
selected_id_bad_row: "Selected component should have 1 row."
fetch_catalog_failed: "Unable to fetch model catalog."
fetch_appends_failed: "Unable to fetch appendable models"
append_failed: "Unable to append sub-model"
tooltips:
# Set to FALSE to disable tool tips for this module
include: TRUE
elements: "Show model components"
show_code: "Show model code"
url_rxode: "https://nlmixr2.github.io/rxode2/articles/rxode2-syntax.html"
url_model_types: "https://ruminate.ubiquity.tools/articles/model_builder.html#model-catalog"
components:
input_tip: "My tool tip"