auxiliary/docsfordevelopers/documentation.md

In ahgroup/modelbuilder: Building Compartmental Simulation Models Without Coding

Documentation for working on the modelbuilder package

Package structure/use

• The main use case is for the user to load the package and open the main menu by running the modelbuilder() function. This function calls a Shiny app (in the /inst/modelbuilder folder), which is the main user interface. The Shiny app in turn uses the various functions in the /R folder to provide all functionality.
• The main menu lets users build a new model, load an existing model, modify or analyze existing model, export code for existing model
• Each model is saved as list structure called 'mbmodel' and stored as an Rds file.
• Several functions take the model structure and turn it into R code/functions for implementing the model as ODE, stochastic/adaptivetau, discrete time, RxODE, SBML, etc. (only some implemented yet)
• Models can be analyzed through the modebuilder GUI. Once a model is exported as a function, it can't be re-imported.

Package organization

Main functions

• Folder /R contains the main R functions underlying the package.
• None of these functions are meant to be directly called by a user. Users are meant to access all package functionality through the graphical interface.
• While the user interacts with the package through a Shiny app, all functions are non-reactive, i.e. none directly handle reactive onjects, all inputs and outputs are non-reactive objects/variables.

Main app materials

• The /inst folder contains several subfolders:
  • /inst/modelbuilder contains the app.R file which is the main file/menu of the package
  • /inst/docsfordevelopers contains this file and potentially other information needed to work on the package
  • /inst/modelexamples contains rds files with pre-built models the user can load and edit/analyze

Other folders

• /auxiliary contains subfoldes with related resources that are not used/needed for the package use/build but are useful (to the package authors) for maintenance/development/advertising/tracking of the package
• /doc contains the vignettes, this folder is auto-generated and should not be edited, see below.
• /docs contains the package website created by the pkgdown package. Rebuild with pkgdown::build_site(). Don't edit manually.
• /man contains the documentation for all public functions, automatically generated by roxygen
• /Meta contains vignette information and is auto-created by devtools when package is built. Ignore.
• /pkgdown contains extra files for styling of pkgdown created website. Edit to change layout of package website.
• /tests contains code/unit tests, done with the testthat package. Add tests as new functionality is added.
• /vignettes contains the vignette - this is copied to /inst/doc during package building. edits should be done to the file in the /vignettes folder, not the /inst/doc folder.

Package coding conventions

• The name of the non-reactive modelbuilder object must be mbmodel
• To avoid variable naming conflicts with users, we should use internal variable names that are unique. Suggestion is to add "_mb" to all internal variables.
• The generate_discrete and other functions create internal variables in the code that is exported, e.g. 'ts'. If a user happens to call one of their variables/compartments the same name, problems likely arise. Might have to rename our internal variables to something unlikely to conflict (e.g. ts_mb) and/or implement checks to prevent use of certain names.

modelbuilder mbmodel structure

Each model is stored in a list object called mbmodel, and saved as an Rds file.

The model list will have the components described below. The following constraints are currently imposed:

• Variable names have to start with an upper-case letter and can only contain letters and numbers
• Parameter names have to start with a lower-case letter and can only contain letters and numbers
• Only basic math is allowed, functions (e.g. sin/cos/sqrt) are currently not supported

Meta-Information

• mbmodel$title - model title
• mbmodel$description - a short (1 sentence) model description
• mbmodel$author - name of model author/creator
• mbmodel$date - date of creation or last change
• mbmodel$details - a detailed model description

Variable information

• mbmodel$var[[i]]$varname - characters containing variable name, string
• mbmodel$var[[i]]$vartext - description of variable, string
• mbmodel$var[[i]]$varval - starting value, numeric
• mbmodel$var[[i]]$flows - all flow terms, as vector of strings
• mbmodel$var[[i]]$flownames - description of each flow, vector of strings

i = 1..number of variables

Parameter information

• mbmodel$par[[i]]$parname - parameter name
• mbmodel$par[[i]]$partext - description of parameter
• mbmodel$par[[i]]$parval - default value

i = 1..number of parameters

Time information

• mbmodel$time[[i]]$timename - tstart/tfinal/dt (fixed names, in that order)
• mbmodel$time[[i]]$timetext - text
• mbmodel$time[[i]]$timeval - default value

i = 1,2,3 being tstart, tfinal and dt

Optional/possibly for (much) later when we implement fitting to data:

• mbmodel$par[[i]]$lb - lower bound for parameter
• mbmodel$par[[i]]$ub - upper bound for parameter

Model examples

Several model examples following the above structure are in the \auxiliary\modelfiles folder. They are provided both as Rds files and as .R scripts which can be run to produce the Rds files. A script in \auxiliary\helperfuncttions can take a mbmodel provided as Rds or R file and produce the other file. It can also turn any Rds or R script into ode/stochastic/discrete function code.

General information for package development

To work on package through RStudio:

• Load project file in RStudio. Edit files as needed.
• Optionally, use RStudio tie-in with github to sync project to github (the 'git' tab).

Dependency packages for development

• roxygen
• devtools
• testthat
• codecov
• rmarkdown for vignette and shiny documentation
• pkgdown for package doc site
• packages needed: see DESCRIPTION file
• Rtools needs to be installed (on Windows)
• All libraries/packages needed by this one should be loaded via the DESCRIPTION file and not in separate R files
• Any function used from a package should be called explicitly in the code, e.g. dplyr::filter
• Add dependencies on other packages only if really needed

To update R documentation and vignette

• Edit documentation inside R functions.
• Build documentation with More/Document or devtools::document()
• Edit vignette inside the /vignettes folder.
• To build new vignette, run devtools::build_vignettes()
• To update the pkgdown website, run pkgdown::build_site()

To build the package

• "by hand" edit the DESCRIPTION file to make sure it's up to date
• in RStudio, use the functions in the 'build' tab to test and build the package.
• Run clean and rebuild, then build and reload using menu, or devtools::load_all()
• Run the check, fix any errors

To-do at release time (no CRAN release for this package yet)

• Re-build documentation, re-build package
• Re-build vignettes with devtools::build_vignettes()
• Run check and make sure no problems occur
• Re-create package site with pkgdown::build_site()
• Sync everything to github
• Check vignette and function references on website, fix errors
• Run devtools::check_rhub() and devtools::check_win_devel()
• Do a test run of devtools::release()

ahgroup/modelbuilder documentation built on April 14, 2024, 2:29 p.m.