Using model modules for repeatable analyses

• 1: Commands for using model modules
• 2: Authoring scientific manuscripts

1 - Commands for using model modules

library(ready4) 

Motivation

To be used in health economic analyses, model modules need to be called using a programming syntax. Ideally that syntax should be relatively simple, with the name and description of each command reliably communicating the category of operations it performs.

Implementation

ready4 provides a simple syntax that is used by all model modules developed with the ready4 framework.

Use

A table that itemises ready4 commands along with examples of how these commands are used can be ingested from a periodically updated database using get_methods_tb. In the below example we will search for examples of where that syntax has been used by modules from the readyforwhatsnext model. The value supplied to the gh_repo_1L_chr argument specifies the repository in which a dataset of readyforwhatsnext module libraries is stored.

x <- get_methods_tb(gh_repo_1L_chr = "ready4-dev/ready4")

Core commands

A HTML table of ready4’s core commands and examples of the use of each command can be displayed using the print_methods function, using the return_1L_chr = "core" argument.

print_methods(x,
              return_1L_chr = "core",
              scroll_width_1L_chr = "100%") 

Applying commands to module “slots”

Each of the “core” commands also has a “slot” version, which applies the command to a specified slot (a named element of a module). Two of these “slot” methods can also be used for additional purposes:

• procureSlot is a “getter” method - its default behaviour is to return the value of a specified slot. If the argument use_procure_mthd_1L_lgl = T is included in the method call, procureSlot will instead apply the procure method to a specified slot.

• renewSlot is a “setter” method - if any value other than “use_renew_mthd” (the default) is passed to the new_val_xx argument, that value will be assigned to the specified slot.

A HTML table of slot commands and relevant examples can be displayed using the print_methods function, using the return_1L_chr = "slot" argument.

print_methods(x,
              return_1L_chr = "slot",
              scroll_width_1L_chr = "100%")

Extended commands

Finally, there are a small number of other commands that are more general extensions of the core commands. Currently, these extended commands are all variants on the author command, with each extension specifying the type of output to be authored by the method. A HTML table of the extended generics bundled with ready4 can be displayed using the print_methods function, using the return_1L_chr = "extended" argument.

print_methods(x,
              exclude_mthds_for_chr = "Ready4Module",
              return_1L_chr = "extended",
              scroll_width_1L_chr = "100%")

2 - Authoring scientific manuscripts

Motivation

Open science workflows should ideally span an unbroken chain between data-ingest to production of a scientific summary such as a manuscript. Such extensive workflows provide an explicit means of linking all content in a scientific summary with the analysis that it reports.

Implementation

ready4show includes a number of classes and methods that help integrate manuscript authoring into a reproducible workflow. These tools are part of the ready4 framework for transparent, reusable and updatable health economic models.

Load required libraries

We first begin by loading the libraries we will require to implement this workflow.

library(ready4)
library(ready4show)
library(bookdown)
library(rticles)

Set consent policy

By default, methods in the ready4show package will request your consent before writing files to your machine. This is the safest option. However, as there are many files that need to be written locally for this program to execute, you can overwrite this default by supplying the value “Y” to methods with a consent_1L_chr argument.

consent_1L_chr <- "" # Default value - asks for consent prior to writing each file.

Create a synopsis of the manuscript to be authored

To start with we create X, an instance of Ready4showSynopsis, a ready4 module (S4 class). We can use X to record metadata about the manuscript to be authored (including details about the study being summarised and the title and format of the intended output).

X <- Ready4showSynopsis(background_1L_chr = "Our study is entirely fictional.",
                        coi_1L_chr = "None declared.",
                        conclusion_1L_chr = "These fake results are not interesting.",
                        digits_int = 3L,
                        ethics_1L_chr = "The study was reviewed and granted approval by Awesome University's Human Research Ethics Committee (1111111.1).",
                        funding_1L_chr = "The study was funded by Generous Benefactor.",
                        interval_chr = "three months",
                        keywords_chr = c("entirely","fake","do", "not","cite"),
                        outp_formats_chr = "PDF",
                        sample_desc_1L_chr = "The study sample is fake data that pretends to be young people aged 12 to 25 years who attended Australian primary care services for mental health related needs between November 2019 to August 2020.",
                        title_1L_chr = "A hypothetical study using fake data")

Add authorship details

Authorship details can be added to slots of X that contain ready4show_authors and ready4show_instututes ready4 sub-modules.

As we can see from the below call to exhibitSlot, X was created with no authorship information.

exhibitSlot(X,
            "authors_r3",
            scroll_box_args_ls = list(width = "100%")) 

We can add details on each author by repeated calls to the renewSlot method.

X <- renewSlot(X,
          "authors_r3",
          first_nm_chr = "Alejandra",
          middle_nm_chr = "Rocio",
          last_nm_chr = "Scienceace",
          title_chr = "Dr",
          qualifications_chr = "MD, PhD",
          institute_chr = "Institute_A, Institute_B",
          sequence_int = 1,
          is_corresponding_lgl = T,
          email_chr = "fake_email@fake_institute.com") %>%
  renewSlot("authors_r3",
            first_nm_chr = "Fionn",
            middle_nm_chr = "Seamus",
            last_nm_chr = "Researchchamp",
            title_chr = "Prof",
            qualifications_chr = "MSc, PhD",
            institute_chr = "Institute_C, Institute_B",
            sequence_int = 2,
            email_chr = "fake_email@unreal_institute.com") 

The updated authorship table can now be inspected.

X %>%
  exhibitSlot("authors_r3",
              scroll_box_args_ls = list(width = "100%")) 

We now need to add additional information for each author institute.

X <- renewSlot(X,
          "institutes_r3",
          short_name_chr = "Institute_A", 
          long_name_chr = "Awesome University, Shanghai") %>%
  renewSlot("institutes_r3",
            short_name_chr = "Institute_B", 
            long_name_chr = "August Institution, London") %>%
  renewSlot("institutes_r3",
            new_val_xx = "use_renew_mthd",
            short_name_chr = "Institute_C", 
            long_name_chr = "Highly Ranked Uni, Montreal")

The updated institutes table can now be inspected.

X %>%
  exhibitSlot("institutes_r3",
              scroll_box_args_ls = list(width = "100%")) 

Add correspondences

We can also add a look-up table about any changes we wish to make from the analysis code of how names of variables / parameters are presented in the manuscript text.

X <- renewSlot(X,
               "correspondences_r3",
               old_nms_chr = c("PHQ9", "GAD7"),
               new_nms_chr = c("PHQ-9", "GAD-7"))

These edits can now be inspected with a call to exhibitSlot.

X %>%
  exhibitSlot("correspondences_r3",
              scroll_box_args_ls = list(width = "100%")) # Add Exhibit Method

Specify output directory

We now update X with details of the directory to which we wish to write the manuscript we are authoring and all its supporting files.

X <- renewSlot(X,
               "a_Ready4showPaths@outp_data_dir_1L_chr",
               new_val_xx = tempdir())

Create dataset of literate programming files

Our next step is to copy a dataset of files that can implement a literate program to generate our manuscript. If you have a template you wish to work with, you can specify its local path using the a_Ready4showPaths@mkdn_source_dir_1L_chr slot of the X. Skip this step if you wish to use the default markdown dataset, which leverages popular rmarkdown toolkits such as bookdown and rticles.

## Not run
# procureSlot(X,
#             "a_Ready4showPaths@mkdn_source_dir_1L_chr",
#             new_val_xx  = "PATH TO MARKDOWN DATASET")

We create the dataset copy with the authorData method.

authorData(X, consent_1L_chr = consent_1L_chr)

Having created a local copy of the template literate program files dataset, it is now possible to manually edit the markdown files to author the manuscript. However, in this example we are skipping this step and will continue to use the unedited template in conjunction with the metadata we have specified in X. We combine the two to author a manuscript using the authorReport method.

authorReport(X, consent_1L_chr = consent_1L_chr)

If we wish, we can now ammend X and then rerun the authorReport method to generate Word and HTML versions of the manuscript.

renewSlot(X,
          "outp_formats_chr",
          new_val_xx = "Word") %>%
  authorReport(consent_1L_chr = consent_1L_chr)

renewSlot(X,
          "outp_formats_chr",
          new_val_xx = "HTML") %>%
  authorReport(consent_1L_chr = consent_1L_chr)

The outputed files are as follows:

• PDF version (and LaTeX file that generated it)
• Word version
• HTML version