ready4 – Reporting - tutorials

Docs: Find themed collections of ready4 modules

Wed, 28 Jan 2026 00:00:00 +0000

This below section renders a vignette article from the ready4 library. You can use the following links to:

view the vignette on the library website (adds useful hyperlinks to code blocks)
view the source file from that article, and;
edit its contents (requires a GitHub account).

library(ready4)

Motivation

To use and combine health economic model modules it is first useful to find modules that have been developed using a common framework that promotes inter-operability.

Implementation

A table summarising currently available module libraries authored with the ready4 framework within a specified GitHub organisation can be retrieved from an online dataset by using the get_libraries_tb and update_libraries_tb functions.

Use

In the below example we will search for modules from the readyforwhatsnext model. The source code for these modules all reside in the ready4-dev GitHub repository. The value supplied to the gh_repo_1L_chr argument specifies the repository in which a dataset of readyforwhatsnext module libraries is stored.

libraries_tb <- get_libraries_tb(gh_repo_1L_chr = "ready4-dev/ready4") %>% update_libraries_tb(include_1L_chr = "modules", url_stub_1L_chr = "https://ready4-dev.github.io/")

In this example, module libraries have been grouped in to the following thematic model “sections”.

libraries_tb$Section %>% unique()
#> [1] "People"   "Places"   "Programs"

We can use the print_packages function to display a HTML summary of the module libraries currently available for each section. The resulting table summarises the types of module library (e.g. those for description, developing models or predicting with models), the name and purpose of those libraries, the locations from which development and archived library code can be downloaded and details of supporting documentation for each library (e.g. website, manuals and examples).

print_packages(libraries_tb, sections_chr = "People")

Purpose	Documentation	Code	Examples
Describe and Validate Youth Mental Health Dataset Variables	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	12, 13
Score Multi-Attribute Utility Instruments	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	14, 15
Model Youth Choice Behaviours	Citation , Website , Citation	Dev , Archive
Implement Transfer to Utility Mapping Algorithms	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	16
Explore and Characterise Heterogeneity in Quality of Life Data	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive
Specify Models to Solve Inverse Problems	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	17
Transform Youth Outcomes to Health Utility Predictions	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	18

print_packages(libraries_tb, sections_chr = "Places")

Type	Package	Purpose	Documentation	Code	Examples
		Model Australian Spatial Data	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive
		Model Spatial Features of Health Systems	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive

print_packages(libraries_tb, sections_chr = "Programs")

Type	Package	Purpose	Documentation	Code	Examples
		Undertake Health Economic Budget Impact Analysis.	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive
		Develop, Use and Share Unit Cost Datasets for Health Economic	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	19, 20

Details of how to search for details on individual modules is described in another article.

Docs: Commands for using model modules

Wed, 28 Jan 2026 00:00:00 +0000

This below section renders a vignette article from the ready4show library. You can use the following links to:

view the vignette on the library website (adds useful hyperlinks to code blocks)
view the source file from that article, and;
edit its contents (requires a GitHub account).

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%")

Method	Purpose	Examples
author	Author and save files	5 , 6, 7 , 16 , 17
characterize	Characterize model module data by generating (tabular) descriptive statistics
depict	Depict (plot) features of model module data	13, 14 , 15
enhance	Enhance a model module by adding new elements
exhibit	Exhibit features of model module data by printing them to the R console	2 , 5 , 6, 13 , 14 , 15 , 16 , 17 , 18 , 19 , 20
ingest	Ingest data	1 , 2 , 3 , 6, 13 , 14 , 15 , 16 , 17 , 18
investigate	Investigate solutions to an inverse problem	16 , 17
manufacture	Manufacture a new object
metamorphose	Metamorphose a model module to a model module of a different (non-inheriting) class	17
procure	Procure items from a dataset	5, 17
prognosticate	Prognosticate (make predictions) by solving a forward problem
ratify	Ratify that input or output data meet validity criteria	13, 17 , 19 , 20
reckon	Reckon (calculate) a value
renew	Renew (update) values	1 , 2 , 13, 14 , 15 , 16 , 17 , 19 , 20
share	Share data via an online repository	1 , 13, 14 , 15 , 16

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%")

Method	Purpose	Examples
authorSlot	Apply the author method to a model module slot
characterizeSlot	Apply the characterize method to a model module slot
depictSlot	Apply the depict method to a model module slot
enhanceSlot	Apply the enhance method to a model module slot
exhibitSlot	Apply the exhibit method to a model module slot	4, 17 , 19 , 20
ingestSlot	Apply the ingest method to a model module slot
investigateSlot	Apply the investigate method to a model module slot
manufactureSlot	Apply the manufacture method to a model module slot
metamorphoseSlot	Apply the metamorphose method to a model module slot
procureSlot	Procure (get) data from a slot	4, 14 , 16 , 17
prognosticateSlot	Apply the prognosticate method to a model module slot
ratifySlot	Apply the ratify method to a model module slot
reckonSlot	Apply the reckon method to a model module slot
renewSlot	Renew (set) the values of data in a module slot	4, 14 , 17 , 19 , 20
shareSlot	Apply the share method to a model module slot

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%")

Method	Purpose	Examples
authorClasses	Author and document classes
authorData	Author and document datasets	4, 17
authorFunctions	Author and document functions
authorReport	Author and save a report	4

Docs: Find examples of how model modules are used

Wed, 28 Jan 2026 00:00:00 +0000

This below section renders a vignette article from the ready4 library. You can use the following links to:

view the vignette on the library website (adds useful hyperlinks to code blocks)
view the source file from that article, and;
edit its contents (requires a GitHub account).

library(ready4)

Motivation

To use and combine health economic model modules it is first useful to find modules that have been developed using a common framework that promotes inter-operability.

Implementation

Use

libraries_tb <- get_libraries_tb(gh_repo_1L_chr = "ready4-dev/ready4") %>% update_libraries_tb(include_1L_chr = "modules", url_stub_1L_chr = "https://ready4-dev.github.io/")

In this example, module libraries have been grouped in to the following thematic model “sections”.

libraries_tb$Section %>% unique()
#> [1] "People"   "Places"   "Programs"

print_packages(libraries_tb, sections_chr = "People")

Purpose	Documentation	Code	Examples
Describe and Validate Youth Mental Health Dataset Variables	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	12, 13
Score Multi-Attribute Utility Instruments	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	14, 15
Model Youth Choice Behaviours	Citation , Website , Citation	Dev , Archive
Implement Transfer to Utility Mapping Algorithms	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	16
Explore and Characterise Heterogeneity in Quality of Life Data	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive
Specify Models to Solve Inverse Problems	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	17
Transform Youth Outcomes to Health Utility Predictions	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	18

print_packages(libraries_tb, sections_chr = "Places")

Type	Package	Purpose	Documentation	Code	Examples
		Model Australian Spatial Data	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive
		Model Spatial Features of Health Systems	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive

print_packages(libraries_tb, sections_chr = "Programs")

Type	Package	Purpose	Documentation	Code	Examples
		Undertake Health Economic Budget Impact Analysis.	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive
		Develop, Use and Share Unit Cost Datasets for Health Economic	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	19, 20

Details of how to search for details on individual modules is described in another article.

Docs: Authoring scientific manuscripts

Wed, 28 Jan 2026 00:00:00 +0000

This below section renders a vignette article from the ready4show library. You can use the following links to:

view the vignette on the library website (adds useful hyperlinks to code blocks)
view the source file from that article, and;
edit its contents (requires a GitHub account).

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)

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%"))

First-name	Middle-name	Last-name	Title	Qualifications	Institutes	Sequence Position	Corresponding	Email	Joint-first

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%"))

First-name	Middle-name	Last-name	Title	Qualifications	Institutes	Sequence Position	Corresponding	Email	Joint-first
Alejandra	Rocio	Scienceace	Dr	MD, PhD	Institute_A, Institute_B	1	TRUE	\_institute.com	NA
Fionn	Seamus	Researchchamp	Prof	MSc, PhD	Institute_C, Institute_B	2	NA	\_institute.com	NA

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%"))

Reference	Name
Institute_A	Awesome University, Shanghai
Institute_B	August Institution, London
Institute_C	Highly Ranked Uni, Montreal

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

Old name	New name
PHQ9	PHQ-9
GAD7	GAD-7

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:

ready4 – Reporting - tutorials

Docs: Find themed collections of ready4 modules

Motivation

Implementation

Use

Related content

Docs: Commands for using model modules

Motivation

Implementation

Use

Core commands

Applying commands to module “slots”

Extended commands

Docs: Find examples of how model modules are used

Motivation

Implementation

Use

Related content

Docs: Authoring scientific manuscripts

Motivation

Implementation

Load required libraries

Set consent policy

Create a synopsis of the manuscript to be authored

Add authorship details

Add correspondences

Specify output directory

Create dataset of literate programming files