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 onjects, 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.
- /docsfordevelopers sub-folder contains this file and an R script that does some processing work.
- 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.
Using the DSAIDE solutions
- Each _documentation.Rmd file has the tasks and outcomes to record stored as a table. When knitting/processing this file, both the html file of the documentation is generated and a .tsv file containing a table with the tasks and quantities to be reported, as well as other columns.
- The .tsv files should be copied into the (private) DSAIDEsolutions repository into the tasktable_files folder.
- Solutions and answers to each question are added by scripts in the DSAIDEsolutions repo. Those can be further processed with the grading app (not part of DSAIDE).