Creating bespoke reports

This vignette introduces the essentials of how to add visualisations from the mantis package into your own bespoke html reports. It will be assumed that you already know how to generate html documents from a Rmd file, including creating tabsets. If you don’t, take a look at the official documentation and/or the many other online resources available before proceeding.

Note: Currently, mantis uses rmarkdown to generate its content and reports, and so the visualisations may not render as expected if added to a Quarto report. In future there will be more support for generating/adding to Quarto reports.

Overview

The standard mantis_report() is designed for quick and simple review of time series that can be stored in a single data frame. If you like the mantis visualisations but want to build a more complex report, e.g. to display data from multiple data frames, display mantis content alongside other (non-mantis) content, or to add your own branding, you can create your own html report using existing rmarkdown functionality, and then insert mantis content and/or tabs into your report as desired.

The easiest way to get started with this is to clone the mantis-templates project to see it in action, then choose a template Rmd file that you can copy from/adapt.

Adding mantis content

mantis includes one main function bespoke_rmd_output() for creating content for bespoke reports. This function use side-effects to generate the desired markdown, and must be placed inside a {r, results='asis'} chunk.

The function can:

The function also includes a few additional parameters not available in the standard mantis_report() to allow some extra control over the display.

Example:

```{r, results='asis'}
# create a parent tab with a set of child tabs
mantis::bespoke_rmd_output(
  df = mantis::example_prescription_numbers,
  inputspec = mantis::inputspec(
    timepoint_col = "PrescriptionDate",
    item_cols = c("Location", "Antibiotic"),
    value_col = "NumberOfPrescriptions",
    tab_col = "Location"
  ),
  outputspec = mantis::outputspec_interactive(
    plot_value_type = "value",
    plot_type = "bar",
    item_labels = c("Antibiotic" = "Antibiotic name"),
    plot_label = "Prescriptions over time",
    sync_axis_range = FALSE,
    item_order = list("Location" = c("SITE3", "SITE2", "SITE1"))
  ),
  timepoint_limits = c(NA, Sys.Date()),
  fill_with_zero = FALSE,
  tab_name = "Group of child tabs",
  tab_level = 1
)
```

Extra requirements for interactive reports

Due to complexities in the way dygraphs widgets are rendered, there are two additional chunks that must be included in the Rmd file, otherwise the graphs can disappear unexpectedly.

Firstly, add the following chunk to the Rmd file to ensure the dygraphs plots are initialised. Remember to set the same plot_type as the one you are using for the rest of the report. This is best placed at the bottom of the file as it can lead to an extra line space. Note: unlike when creating mantis content, this chunk should not include results='asis'.

```{r}
# this chunk is necessary when using mantis::outputspec_interactive().
# it ensures that the dygraphs render when built using `cat()`
# set the plot_type to the same plot_type as the real output
mantis::bespoke_rmd_initialise_widgets(plot_type = "bar")
```

Secondly, when the browser window is resized, all dygraphs plots on inactive tabs disappear. A workaround for this is to redraw them all by reloading the page. To do this, add the following chunk at the top of the Rmd file.

```{js}
// this chunk is necessary when using mantis::outputspec_interactive(). 
// when the browser window is resized, all dygraphs on inactive tabs disappear. Reload page to 
// redraw them all.
window.onresize = function(){ location.reload(); }
```