NOTE: This module is currently under active development and this documentation is a work in progress
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.
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 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.
# 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"