auxiliary/docsfordevelopers/documentation.md

In ahgroup/DSAIRM: Dynamical Systems Approach to Immune Response Modeling

Documentation for working on the DSAIDE/DSAIRM packages

The DSAIDE and DSAIRM packages are very similar in structure, so the text below applies to both. I mostly write DSAIDE, sometimes DSAIRM. Just substitute with whichever package you work on.

Package structure/use

• The main use case is the user calling the dsaidemenu() function. This function calls a Shiny app (in the /inst/DSAIDE folder), which is the main user interface. The Shiny app in turn uses the various generate_ functions to build the UI. Users can select models/apps, which are each encoded by one or more simulate_ function.
• An alternative use case is for users to write code that directly calls the simulate_ functions.
• The simulate_ functions can also be downloaded and modified by the user.
• The package documentation contains more information.

Package organization

Main functions

• Folder /R contains the main R functions, i.e. the simulators and various helper functions.
• All simulators, which can be called directly by advanced users start with simulate_.
• The functions/files generate_text, generate_ggplot and generate_plotly can take results returned from the simulator functions and generate plots. Users might want to use those combined with running the simulate_ functions.
• All other functions/files are only needed for the package/UI to work. They are public/exported, but are generally not meant to be directly accessed by users.
• While some of the functions are meant to be used as part of a shiny app, none directly handle reactive objects, all inputs and outputs are non-reactive objects/variables.

App materials

• The /inst folder contains several subfolders:
• The /appinformation subfolder contains files with documentation and settings for each simulator/app. Each App has an Rmd+HTML file containing the documentation. Those files contain the documentation displayed at the bottom of each app, and app-specific settings that are needed for proper display and running through the UI. There is also a bibliography/references file, and the very important apptable.tsv (tab separated table) file. The latter contains details for each app which are being parsed by various functions in the package.
• The DSAIDE or DSAIRM subfolder contains the main app.R Shiny app. It also includes a css file for styling and a google analytics file for tracking users when deployed to a server. A subfolder created by rsconnect during package upload to shinyapps.io might also be present.
• /helperfunctions contain various non-exported functions that are used when building the package, mainly when generating the html version of the documentation from the Rmd files.
• /mbmodels contains Rds files of underlying simulation models that have been created with the modelbuilder package. If those are present and the apptable.tsv file specifies they should be used, then the UI for a model is generated by using the information in the mbmodel, instead of parsing the documentation header of a simulation file.
• /media sub-folder contains figures and a bib file used as part of the documentation (i.e. the Rmd files).
• /simulatorfunctions subfolder contains the R code for all simulator functions. The functions in this folder are copies of the simulatorfunctions in the /R folder. They are used by the package to create the shiny UI (see the generate_shinyinput function). They are also contained in a zip folder which can be downloaded by users for easy access and editing. Before a new version of the package is released, it is important to ensure that the simulator_ functions in this subfolder and the zip file are up-to-date and correspond to the files in the /R folder.

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
• /data contains data used as part of the R package. The data files are documented in data.R in the /R folder.
• /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.

Adding new apps/features

If you plan to build/contribute new apps or new features to the package, I would be delighted to include them! The best idea is to first contact me (through Github or email) and tell me that you would like to contribute. We can then discuss a bit before you embark on the effort.

To build a new app, you need to create the following:

• The main simulator_NNN function.
• The NNN_documentation.Rmd file.

If you contribute/send those files, I will - after testing - include them into the package. You'll of course receive full credit as package contributor.

Style Guide

• Documentation Sectioning
  • Overview
    • Learning Objectives (stated imperatively)
  • The Model
    • Model Overview (number processes)
    • Model Diagram
    • Model Equations ({+} optional subsections, use aligned equations)
    • Model Concepts ({-} optional section)
    • Notes
  • What To Do
    • Unit description ({-} not section; bolded)
    • Tasks
  • Further Information
    • References

Suggestions for Consistency in Formatting

• Capitalization rules to follow title rules ("To"" when an infinitive also)
• Documentation: bullets for lists only and notes section)
• Emphasizing or Referring to Concepts or App Components
  • Apps referenced in bold italics
  • App tabs referenced in italics
  • When outside equations, parameters in italics, using appropriate subscript / superscript, or plain text when written out
  • When outside equations, variables in bold when single letter, or plain text when written out (e.g., I versus immune response)
    • initial values (subscript naught),
    • max values (subscript peak?, superscript *) just write out,
    • min values (subscript *?) just write out,
    • final values (subscript final or time number?) just write out,
    • steady state (subscript s)
  • Subscripts / superscripts should be lowercase except when referencing a variable (e.g., d~I~)
  • Concepts or keywords or vocabulary in bold italics at least upon first introduction

Information for package development

To work on package through RStudio:

• Fork and clone package from Rstudio.
• Load DSAIDE.Rproj in RStudio. Edit files as needed.
• Use devtools/roxygen to build and document the package. Either use RStudio's functionality (or command line) to test/build packages using devtools. The package follows Hadley's recommendations and workflow described here: http://r-pkgs.had.co.nz/
• Optionally, use RStudio tie-in with github to sync project to github (the 'git' tab). Alternatively, use your favorite git client.
• Rtools needs to be installed (on Windows).

Dependency packages

All libraries/packages needed to allow the package to run should be loaded via the DESCRIPTION file and not in separate R files. See that file for dependencies.

Additional packages are needed for development (but not use) of the package. Those are listed in the suggests section of the DESCRIPTION file.

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 re-build html documentation files, copy and zip simulator functions and build vignettes and site, run the processing-script provided in this folder.

To build the package

• 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 deploy package to shinyappsio

to deploy, follow these steps (also listed in the main app.R file): 1. go into the folder where this file (app.R) resides 2. install the package through CRAN or github if we want to use the github version devtools::install_github('ahgroup/DSAIDE') 3. uncomment this line of code library('DSAIDE') 4. with the above 'library' statement active, deploy with: run rsconnect::deployApp(account = 'epibiouga') as suitable, change the account to another one, e.g. handelgroup tokens need to be set up for the connection to work 5. comment out the library command again

To-do for CRAN release

• "by hand" edit the DESCRIPTION file to make sure it's up to date
• run processing-script to Re-build documentation, vignettes and copy latest versions of simulator functions - see above
• Run check and make sure no problems occur
• update news.md and cran-comments.md
• 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(), devtools::check_win_release() and devtools::check_win_devel(), devtools::check_mac_release()
• Do a test run of devtools::release() - fix any remaining issues, then re-run and release

Trouble-shooting

• If you get the 'can't find qpdf error' during build, try this (on windows): https://stackoverflow.com/questions/41570633/how-to-build-qpdf-on-windows

ahgroup/DSAIRM documentation built on Oct. 4, 2023, 6:50 a.m.