Model diagram
It can be difficult for a user to look at a set of parameters, dosing inputs, and outputs and determine how a model works. To aid the user it can be useful to create a model diagram. To utilize the majority of the screen space, the image should be roughly twice as wide as it is tall.
You can create this image in your favorite drawing program. Inkscape is a free vector drawing program available at inkscape.org. If you run the following:
system_fetch_template(cfg, template="Model Diagram")
it will create the file system.svg. You can edit it and save it as a portable network graphics (png) file named system.png in the directory with the ubiquity_app.R file. When you start the ShinyApp it should find that file and create a tab in the plotting area of the App.
Model reports
Sometimes you need more detail than an annotated model diagram. Or you may need to perform some calculations based on the results of a simulation. It may be better to present information in a tabulated format. For these scenarios you can create an RMarkdown file. Create a copy the report template (system_report.Rmd) and a script to test it (test_system_report.r):
system_fetch_template(cfg, template="Shiny Rmd Report")
When this is called you’ll have access to the ubiquity model object (cfg) and the simulation results som. The simulation results will take the form of a deterministic simulation (see the output of ?run_simulation_ubiquity) or, if variability is checked, a stochastic simulation (see output of ?simulate_subjects)
To tell the ShinyApp to load the report (named system_report.Rmd), the following lines need to be added to ubiquity_app.R.
cfg$gui$modelreport_files$R1$title = "Tab Title"
cfg$gui$modelreport_files$R1$file = "system_report.Rmd"
The title field is the title of the tab in the ShinyApp and file is the name of the file that you created. You can create up to five reports this way, and these are differentiated by the list name (R1, R2, … R5).
The file test_system_report.r can be used to debug your model report file. First run your model in the ShinyApp with the reports disabled. When the App runs it stores the state (cfg) and the current simulation results (som) in the following data files:
cfg \(\rightarrow\) transient/rgui/default/gui_state.RDatasom \(\rightarrow\) transient/rgui/default/gui_som.RData
Next load the test script, modify the report name accordingly, and run it:
load("transient/rgui/default/gui_som.RData")
load("transient/rgui/default/gui_state.RData")
params = list()
params$cfg = cfg
params$som = som
rmarkdown::render("system_report.Rmd",
params = params,
output_format = "html_document")
This should generate your report in HTML format. You can insert debugging commands in the report and test it while you add information. Once you have it working, you can enable the report as described above and it should appear as a tab viewable by the user.
Not all reports may depend on user input. For example, if you have an RMarkdown file that documents your modeling assumptions or the model construction process then the content will not change as the user interacts with the App. To use a pre-rendered report you simply have to replace .Rmd with .html:
cfg$gui$modelreport_files$R1$title = "Tab Title"
cfg$gui$modelreport_files$R1$file = "system_report.html"
This will tell the App to read in the html, prevent rendering the report, and speed things up for the user.
