Refactor teal.reporter

[donyunardi]

Summary

teal.reporter is a powerful feature that allows users to create reports when they discover interesting analyses during exploration in teal. However, as user requirements continue to evolve, the current design has shown some limitations.

Some key challenges include:

• disk space concerns related to the bookmarking feature: teal issue #1188
• limited customization due to its tight integration with teal module programming, making it difficult for users to modify cards: teal.modules.general issue #736
• reproducibility challenges: teal.reporter issue #280
• additional concerns in nestdevs-tasks issue #44

To address these limitations, we aim to refactor teal.reporter with a more flexible and scalable design. This will involve researching potential solutions, conducting proof-of-concept (PoC) evaluations, and implementing a new design that better supports these evolving requirements.

Please see related comment here.

Definition of Done

• The new design supports bookmarking without excessive disk space usage.
• Users can customize report cards without modifying teal module programming.
• Reports generated through teal.reporter are fully reproducible.
• The refactored system maintains or improves existing functionalities.
• User can disable reporter in one or multiple teal modules

Tasks

• [Research] Research and PoC new teal.reporter design #105
• Implementation phase

[gogonzo]

Current state of insightsengineering/teal.reporter#307

The new design supports bookmarking without excessive disk space usage.

Reporter has been modified and should not cause disc storage problems - we need an app to test it @m7pr

Users can customize report cards without modifying teal module programming.
User can disable reporter in one or multiple teal modules

Not started yet. It needs extra teal function to modify returned ReportDocument object returned from the module (as reactive) and pass (or don't to disable) further.
At this point example app with an explicit <module>$server wrapper is enough to demonstrate the possibility.

Reports generated through teal.reporter are fully reproducible.

@m7pr has made a step forward and split the code so that it is possible to generate an executable document.

[m7pr]

The new design supports bookmarking without excessive disk space usage.
Reporter has been modified and should not cause disc storage problems - we need an app to test it @m7pr

You can use the app from the opening comment of the PR in teal.reporter

Code

devtools::load_all('../teal.reporter')
devtools::load_all('../teal.widgets')
devtools::load_all('../teal.code')
devtools::load_all('../teal')
devtools::load_all('.')

# general data example
data <- teal_data()
data <- within(data, {
  require(nestcolor)
  CO2 <- CO2
  USArrests <- USArrests
})

app <- init(
  data = data,
  modules = modules(
    tm_a_regression(
      label = "Regression",
      response = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = "uptake",
          selected = "uptake",
          multiple = FALSE,
          fixed = TRUE
        )
      ),
      regressor = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variables:",
          choices = variable_choices(data[["CO2"]], c("conc", "Treatment")),
          selected = "conc",
          multiple = TRUE,
          fixed = FALSE
        )
      )
    ),
    tm_a_pca(
      "PCA",
      dat = data_extract_spec(
        dataname = "USArrests",
        select = select_spec(
          choices = variable_choices(
            data = data[["USArrests"]], c("Murder", "Assault", "UrbanPop", "Rape")
          ),
          selected = c("Murder", "Assault"),
          multiple = TRUE
        ),
        filter = NULL
      )
    ),
    tm_g_scatterplot(
      label = "Scatterplot Choices",
      x = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]], c("conc", "uptake")),
          selected = "conc",
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      y = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]], c("conc", "uptake")),
          selected = "uptake",
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      color_by = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(
            data[["CO2"]],
            c("Plant", "Type", "Treatment", "conc", "uptake")
          ),
          selected = NULL,
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      size_by = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]], c("conc", "uptake")),
          selected = "uptake",
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      row_facet = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]], c("Plant", "Type", "Treatment")),
          selected = NULL,
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      col_facet = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]], c("Plant", "Type", "Treatment")),
          selected = NULL,
          multiple = FALSE,
          fixed = FALSE
        )
      )
    ),
    tm_g_bivariate(
      x = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]]),
          selected = "conc",
          fixed = FALSE
        )
      ),
      y = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]]),
          selected = "uptake",
          multiple = FALSE,
          fixed = FALSE
        )
      ),
      row_facet = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]]),
          selected = "Type",
          fixed = FALSE
        )
      ),
      col_facet = data_extract_spec(
        dataname = "CO2",
        select = select_spec(
          label = "Select variable:",
          choices = variable_choices(data[["CO2"]]),
          selected = "Treatment",
          fixed = FALSE
        )
      )
    )
  )
)
if (interactive()) {
  shinyApp(app$ui, app$server, enableBookmarking = "server")
}

However I do not see a lot of disk space being saved. Rather the opposite.

shiny bookmark for tm_g_bivariate that is still kept in the old fashion for old teal.reporter classes

shiny bookmark for module that is written using new teal.reporter class that needs to be stored as .rds file

[m7pr]

Users can customize report cards without modifying teal module programming.

I was trying to create a prototype of a function that would edit the module's report_card insightsengineering/teal@c0b9836
but for now ended up with some namespace collision as inputs are not visible in the server function

[m7pr]

Hey! Here's a quick update and a TODO list of future tasks we can tackle after finishing the current research.

---

Done

teal.modules.general

• Rewrote example modules to align with the new design
  👉 POC Redesign of teal.reporter teal.modules.general#862
• Ensured reproducibility of reports
  👉 Improve the Reproducibility Mechanisms and Code Display in Report Output teal.reporter#280
• Extended teal.code::eval_code and teal.code::get_code to support code labelling
  👉 introduce label to eval_code, within and get_code teal.code#248

teal

• Exposed reporter as an init parameter to allow global disabling
  👉 [Feature Request]: Globally disable reporter feature teal#871
• Added reporter$set_template() for setting custom templates when users add cards
  👉 [Feature Request]: User-defined templates for reports teal.reporter#271
• Introduced modify_teal_module_output() so devs can modify or disable report cards
  👉 [Feature Request]: Allow app dev to supply card function. teal.modules.general#736
  👉 Also allows disabling reporter on a per-module basis
  👉 optional reporter in the independent teal modules teal#678
• Added add_document_button_server() with a standalone "+" button (no more old buttons in modules)
  👉 https://github.com/insightsengineering/coredev-tasks/issues/545

teal.reporter

• Added report_document() and edit_report_document() for the new ReportDocument S3 class
• Extended Previewer and Reporter to support ReportDocument
• Deleted private Rendered class
• Refactored:
  • report_render_and_compress
  • report_render
  • Added load report button to previewer buttons

---

In Progress

teal

• Finalize placement of the "+" button
  👉 POC Redesign of teal.reporter teal#1499 (comment)

teal.reporter

• Add interactive editing of report objects in the previewer:
  • Work in progress 👉 Edit Functionality for the Report Previewer module teal.reporter#312
  • User request 👉 Showcase functionality of editor for report previewer teal.reporter#306

---

🔜 TODOs

Module Packages

• Rewrite report cards based on the new design in:
  • teal.modules.general - 15 modules (23 hours)
  • teal.modules.clinical - 36 modules (54 hours)
  • teal.osprey - 10 modules (15 hours)
  • teal.goshawk - 6 modules (9 hours)
  • teal.hermes - 8 modules (12 hours)

teal

• Documentation (13 hours)
  • Add documentation and a vignette for modify_teal_module_output()
• Code
  • Deep clone reporter in init
    👉 POC Redesign of teal.reporter teal#1499 (comment)
  • Use appendTab to enable/disable reporter from UI
    👉 POC Redesign of teal.reporter teal#1499 (comment)
• Wrappers (13 hours)
  • Consider which wrappers to expose for modify_teal_module_output() (e.g. disable_teal_module_report_card)
• Print
  • Consider extending print of modules to include report_card body
    👉 POC Redesign of teal.reporter teal.modules.general#862 (comment)

teal.reporter

• Fix known issues:
  • Naming updates after card content changes
    👉 Redesign of teal.reporter Cards teal.reporter#307 (comment)
  • Broken examples for report_document
    👉 Redesign of teal.reporter Cards teal.reporter#307 (comment)
  • Same-name cards getting overwritten 🙃
  • Make cards and blocks in the Previewer sortable
• Documentation
  • Write a vignette covering new features
  • Deprecate old methods
• Fix failing tests
• Further refactoring:
  • Check for code reuse opportunities between download_report_button_srv and reporter_previewer_srv
    👉 Redesign of teal.reporter Cards teal.reporter#307 (comment)

---

Future Plans

• Expose Show R Code as a button next to Add to Report button
  • This will require the module to return teal_data/qenv
  • This will require srv_teal_module to depend on whether module returned teal_data/qenv to show the button
  • This will allow to modify the teal_data/qenv returned by the module, so that Show R Code can be also customized or nullified