ready4 – Software - libraries (ready4)

Docs: Template module

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

A potentially attractive approach to modelling complex health systems is to begin with a relatively simple computational model and to progressively extend its scope and sophistication. Such an approach could be described as “modular” if it is possible to readily combine multiple discrete modelling projects (potentially developed by different modelling teams) that each independently describe distinct aspects of the system being modelled.

Implementation

The ready4 facilitates modular model development by supplying a template module that enables model developers to avail of the encapsulation and inheritance features of Object Oriented Programming (OOP). The ready4 framework uses two of R’s systems for implementing OOP - S3 and S4. An in-depth explanation of R’s different class system is beyond the scope of this article, but is explored in Hadley Wickham’s Advanced R handbook. However, it is useful to know some very high level information about S3 and S4 classes:

S4 classes are frequently said to be “formal”, “strict” or “rigorous”. The elements of an S4 class are called slots and the type of data that each slot is allowed to contain is specified in the class definition. An S4 class can be comprised of slots that contain different types of data (e.g. a slot that contains a character vector and another slot that contains tabular data).
S3 classes are often described as “simple”, “informal” and “flexible”. S3 objects attach an attribute label to base type objects (e.g. a character vector, a data.frame, a list), which in turn is used to work out what methods should be applied to the class.

Use

ready4 Model Modules

As we use the term, a “model module” is comprised of both a data-structure (an S4 class) and the algorithms (or “methods”) that are associated with that data-structure. Model modules can be created from a template - the ready4 package’s Ready4Module class.

We can create an object (X) from the Ready4Module template using the following command.

X <- Ready4Module()

However, if we inspect X we can see it is of limited use as it contains no data other than an empty element called dissemination_1L_chr.

str(X)
#> Formal class 'Ready4Module' [package "ready4"] with 1 slot
#>   ..@ dissemination_1L_chr: chr NA

The Ready4Module class is therefore not intended to be called directly. Instead, the purpose of Ready4Module is to be the parent class of other model modules. Prototype tools for authoring modules from this template are described here.

ready4 Concept

Module

An instance of Ready4Module (or classes that inherit from Ready4Module) and its associated methods.

ready4 Model Sub-modules

In ready4, S3 classes are principally used to help define the structural properties of slots (elements) of model modules and the methods that can be applied to these slots. S3 classes created for these purposes are called sub-modules.

ready4 Concept

Sub-Module

An instance of an informal (S3) class and its associated methods that describes, validates and applies algorithms to a slot of a Module.

Docs: Provide end users with a simple and consistent syntax for using model 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

Transparency is one of the underpinning principles of ethical modelling practice. One way to improve the transparency of computational health economic models is to ensure that the programs implementing model analyses can be meaningfully inspected by readers with different levels of technical expertise. Even non-technical readers should be able to follow the high-level logic implemented by model algorithms. If multiple analysis programs are written using a common simplified syntax then reviewers of those programs need to contend with relatively fewer new concepts.

Implementation

ready4 provides a simple syntax that can be consistently applied to attach algorithms (methods) to model modules. It does so by taking advantage of the abstraction and polymorphism features of Object Oriented Programming and R’s use of generic functions. Generic functions don’t implement algorithms themselves - their most salient features are a name and a high level description of the type of task that any method associated with that generic should perform. Whenever a developer creates a method for classes that use R’s S4 and S3 systems (the types used for model modules and sub-modules), they can associate that method with a generic that has a description that is a good match for the algorithm being implemented.

Use

ready4 includes a number of core generic functions which describe the main types of method to be implemented by model modules. These generics correspond exactly to the “core”, “slot” and “extended” commands described in another article.

Notably, the ready4 package does not associate any core or extended methods with the Ready4Module template module. Instead, model developers need to decide which core and extended generics they associate with the modules they derive from the Ready4Module template. This decision is typically made when authoring the methods associated with model modules.

Currently, the only methods defined for Ready4Module are slot-methods. By default, these slot methods are inherited by all modules derived from the Ready4Module template. These methods can be itemised using the get_methods function.

get_methods()
#>  [1] "authorSlot"        "characterizeSlot"  "depictSlot"        "enhanceSlot"       "exhibitSlot"       "ingestSlot"        "investigateSlot"   "manufactureSlot"   "metamorphoseSlot" 
#> [10] "procureSlot"       "prognosticateSlot" "ratifySlot"        "reckonSlot"        "renewSlot"         "shareSlot"

Docs: Partially automate maintenance of a modelling project's website

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

Manually keeping track of modules libraries, programs, reporting templates and datasets authored by different teams and stored in different locations can be an onerous undertaking. The ready4 library therefore includes tools to allow a modelling project’s maintainers to perform automated searches for model artefacts and to output tabular summaries of these assets in formats suitable for inclusion on a project documentation website.

Implementation

The ready4 library includes tools to allow a modelling project’s maintainers to partially automate searching for and creating summaries of relevant modelling project assets (e.g. tutorials, releases, etc.) that are suitable for inclusion on documentation website pages.

Use

The documentation website maintenance tools in the ready4 library are designed to be used on a docsy documentation website derived from this template repository. An example of a website created from this template is the readyforwhatsnext model project website, for which source code is available here.

The write_to_render_post is the main ready4 function used specifically for website maintenance tasks. Importantly, the non-CRAN library hugodown needs to be installed to use this function.

write_to_render_post is designed for help overcome practical challenges of rendering RMD or Rmarkdown files (particularly those sourced from an individual module library’s documentation website) to Markdown output in an overall modelling project website. Examples of its use are in this script that is run when updating the readyforwhatsnext project website. The RMD / Rmarkdown files rendered by this example script call other useful functions from the ready4 package, such as:

get_libraries_tb, update_libraries_tb and print_packages for updating details on module libraries (see this example)
make_modules_tb and print_modules for updating details on individual modules (see this example)
make_datasets_tb and print_data for updating details on module datasets (see this example)
get_datasets_tb, make_dss_tb and make_ds_releases_tbl for updating release statuses of module datasets (see this RMD file and its output)
make_programs_tbl for updating details on analysis programs or reporting sub-routines that use model modules (see this RMD file and its associated output as well as this RMD file and its output)
make_code_releases_tbl for updating release statuses of module libraries and programs or reporting sub-routines that use model modules (see this RMD file and its output)

Docs: Why ready4 is object oriented

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

The practical utility and ease of use of computational health economic models are in part shaped by the choice of programming paradigm used to develop them. ready4 adopts an object oriented programming (OOP) paradigm which in practice means that the framework principally consists of classes (representations of data structures useful for modelling health systems) and methods (algorithms that can be applied to these data-structures to generate insight useful for policy-making). Adopting an OOP approach is particular useful for helping to make models transparent, reusable and updatable.

Implementation

Modular Computational Models

Two commonly noted features of OOP - encapsulation and inheritance are particularly useful when developing modular computational health economic models.

Encapsulation

Encapsulation allows us to define the data structures (“classes”) used in computational modelling projects in a manner that allows them to be safely combined. For example, assume there are two computational health economic models, one (A) focused on predicting the types and intensity of services used by individuals that present to health services and the other (B) that predicts outcomes for recipients of these services. It may be desirable to develop a new model (C) that combines A and B to model both service use and outcomes. Using encapsulated code allows all of the features and functionality of A to be made available to B in a manner that protects the integrity of A. Specifically, B can only interact with A using the algorithms (“methods”) that have been already defined for A.

Furthermore, if appropriately implemented, methods associated with a class will work with any combination of input values that can be encapsulated by that class - making computational models more transferable. For example, imagine a class (X) that is used to structure summary data relevant to health systems. Methods associated with X (e.g. a method to derive an unmet need statistic) can then applied to two instances of X - one containing data relevant to the Australian context and one with data from the UK context.

Inheritence

The examples highlighted in the previous section have some potential limitations. What if the developers of A didn’t define methods that would allow B to interact with it in the desired way? Or what if there are a number of differences between the Australian and UK system that need to be accounted for when transferring a method from the former to the latter? These types of issues can be addressed by another key feature of OOP - inheritance. Inheritance allows for a “child” class to be created from a “parent” class. By default, the “child” inherits all of the features of the “parent” including all methods associated with the “parent” class. Importantly however, alternative or additional features can also be specified for the “child” to allow it to implement different methods where necessary. For example, when developing our new computational model C we could create a number of new classes that are children of the classes defined in A. We can then define any additional/alternative methods for these classes that overcome any integration issues between the classes and methods of A and B. In this way, we can enjoy the best of both worlds - leveraging all relevant algorithms from A and B (as there is no need to re-invent the wheel), while ensuring that we transparently develop the additional code required for C. This approach also ensures that the respective contributions of the (potentially different) authorship teams behind A, B and C is clearer.

Similarly, inheritance would allow re-use of much of the code from a model of the Australian health system when exploring similar topics within the UK context, while making it straightforward to develop additional code that addresses relevant divergence in features between the two jurisdictions. In practical terms, this would mean developing two child classes of X - class Y for use with Australian data and class Z for use in the UK system. All methods that are not specific to a particular jurisdiction are defined for X and inherited by Y and Z. Methods that are only appropriate for use in the Australian context are defined for Y, while UK specific methods are defined for Z.

Transparent Computational Models

To make modelling analysis programs more readily understood, the ready4 package provides a simple and consistent syntax. Such simplified approaches are facilitated by two other commonly noted features of OOP - polymorphism and abstraction.

Polymorphism

Polymorphism allows for similar concepts to be represented using consistent syntax. The same top level code can therefore be generalised to multiple model implementations, making algorithms simpler to understand and easier to re-use.

Returning to a previous example, the exact same command (e.g. a call to the method exhibit) can be applied to both Y (used for Australian data) and Z (used for UK data). However, the algorithm implemented by that command can vary based on the class that each method is applied to (ie a different algorithm is applied when the data is specified as being from the UK compared to being specified as Australian).

Abstraction

The simplicity enabled by polymorphism is enhanced by Abstraction, which basically means that only the briefest and easiest to comprehend parts of the code are exposed by default to potential users. Once an instance of a model module template class is created, the entire program to ingest model data, analyse it and produce a scientific summary can be represented in a few brief lines of code, readily comprehensible to non-coders. When using open source languages, the elegance and simplicity of abstraction does not restrict the ability of more technically minded users exploring the detailed workings of the underpinning code.

Docs: Search open access data collections

Thu, 30 Nov 2023 00:00:00 +0000

library(ready4)

The make_datasets_tb function from the ready4 library can be used to create a summary table of the open access datasets we curate in our ready4 Dataverse Collection.

make_datasets_tb("ready4") -> x

One way to inspect this information is to group contents by Dataverse Collections using the print-data function.

print_data(x,
           by_dv_1L_lgl = T) %>%
  kableExtra::scroll_box(width = "100%")

Dataverse	Name	Description	Creator	Datasets
TTU	Transfer to Utility	A collection of transfer to utility datasets developed with the ready4 open science framework.	Orygen	1, 2, 3
fakes	Fake Data For Instruction And Illustration	Fake data used to illustrate toolkits developed with the ready4 open science framework.	Orygen	4 , 5 , 6 , 7 , 8 , 9 , 10
firstbounce	First Bounce	A ready4 framework model of platforms. Aims to identify opportunities to improve the efficiency and equity of mental health services.	Orygen
ready4fw	ready4 Framework	A collection of datasets that support implementation of the ready4 framework for open science computational models of mental health systems.	Orygen	11
readyforwhatsnext	readyforwhatsnext	Data collections for the readyforwhatsnext mental health systems model.	Orygen	12, 13
springtides	Springtides	A ready4 framework model of places. Synthesises geometry (boundary, coordinate) and spatial attribute (e.g. population counts, environmental characteristics, service identifier and model coefficients associated with areas) data.	Orygen	14
springtolife	Spring To Life	A ready4 framework model of people. Models the characteristics, behaviours, relationships and outcomes of groups of individuals relevant to policymakers and service planners aiming to improve population mental health.	Orygen	15

Alternatively, we can itemise individual Dataverse Datasets. When doing so, it makes sense to prepare separate views for toy datasets designed for instruction and real datasets appropriate for use in modelling.

Datasets appropriate for use in modelling projects can be returned by supplying the value “real” to the what_1L_chr argument of print_data.

print_data(x,
           what_1L_chr = "real") %>%
  kableExtra::scroll_box(width = "100%")

Title	Description	Dataverse
Transfer to AQoL-6D Utility Mapping Algorithms	Catalogues of models (and the programs that produced them) that can be used in conjunction with the youthu R package to predict AQoL-6D health utility (and thus, derive QALYs) from measures collected in youth mental health services.	TTU
Transfer to AQoL-6D From Measures Collected In Primary Youth Mental Health Services	This is a work in progress dataset to support the implementation and reporting of a study to map measures collected in Australian primary youth mental health services to AQoL-6D health utility.	TTU
Transfer to CHU-9D From Measures Collected In Primary Youth Mental Health Services	This is a work in progress dataset to support the implementation and reporting of a study to map measures collected in Australian primary youth mental health services to CHU-9D health utility	TTU
ready4 Framework Abbreviations and Definitions	This dataset contains resources that help ready4 Framework Developers adopt common standards and workflows.	ready4fw
readyforwhatsnext posters	A collection of poster summaries about the readyforwhatsnext project and its outputs.	readyforwhatsnext
Australian demographic input parameters for Springtides model	Geometry, spatial attribute and metadata inputs for the demographic module of the readyforwhatsnext model. The demographic module is a systems dynamics spatial simulation of area demographic characteristics. The current version of the model is quite rudimentary and is designed to be extended by other models developped with the ready4 open science mental health modelling tools.	readyforwhatsnext
Springtides reports for Local Government Areas in the North West of Melbourne	This dataset is a collection of reports generated by a development version of the Springtides Model Of Places. Each report summarises prevalence projections for a specified mental disorder / mental health condition for a Local Government Area that is wholly or partially within the catchment area of the Orygen youth mental health service in North West Melbourne. As these reports were generated by a development version of the Springtides Model, these projections should be regarded as exploratory.	springtides
Modelling the online helpseeking choice of socially anxious young people	Models to predict the online helpseeking choices of socially anxious young people in Australia and replication code and documentation to implement the discrete choice experiment that generated the models. All study outputs were created with the aid of the mychoice R package (https://ready4-dev.github.io/mychoice).	springtolife

To view toy datasets, instead supply the value “fakes”.

print_data(x,
           what_1L_chr = "fakes") %>%
  kableExtra::scroll_box(width = "100%")

Title	Description	Dataverse
TTU (Transfer to Utility) R package - AQoL-6D vignette output	This dataset has been generated from fake data as an instructional aid. It is not to be used to inform decision making.	fakes
TTU (Transfer to Utility) R package - EQ-5D vignette output	This dataset is provided as a teaching aid. It is the output of tools from the TTU R package, applied to a synthetic dataset (Fake Data) of psychological distress and psychological wellbeing. It is not to be used to support decision-making.	fakes
Synthetic (fake) youth mental health datasets and data dictionaries	The datasets in this collection are entirely fake. They were developed principally to demonstrate the workings of a number of utility scoring and mapping algorithms. However, they may be of more general use to others. In some limited cases, some of the included files could be used in exploratory simulation based analyses. However, you should read the metadata descriptors for each file to inform yourself of the validity and limitations of each fake dataset. To open the RDS format files included in this dataset, the R package ready4use needs to be installed (see ). It is also recommended that you install the youthvars package ( ) as this provides useful tools for inspecting and validating each dataset.	fakes
ready4use R package vignette output	This dataset is provided so that others can compare the output they generate when implementing vignette code with that generated by the authors.	fakes
Specific R Package - AQoL-6D Vignette Output	This dataset is provided so that others can apply the algorithms we have developed, consistent with the principles of the ready4 open science framework for data synthesis and simulation in mental health.	fakes
Synthetic (fake) dataset for hypothetical replication of study mapping psychological distress and functioning measures to AQoL-6D health utility	This dataset is comprised of fake data that has been created to illustrate the potential transfer of a study algorithm for creating utility mapping models to new data. Outputs in this dataset are for instructional purposes only and should not be used to inform decision making.	fakes
Synthetic (fake) dataset for hypothetical replication of study mapping psychological distress and functioning measures to CHU-9D health utility	This dataset is comprised of fake data that has been created to illustrate the potential transfer of a study algorithm for creating CHU-9D utility mapping models to new data. Outputs in this dataset are for instructional purposes only and should not be used to inform decision making	fakes

Docs: Finding modules of health economic models

Thu, 05 Jan 2017 00:00:00 +0000

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

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.

ready4 – Software - libraries (ready4)

Docs: Template module

Motivation

Implementation

Use

ready4 Model Modules

Module

ready4 Model Sub-modules

Sub-Module

Docs: Provide end users with a simple and consistent syntax for using model modules

Motivation

Implementation

Use

Docs: Partially automate maintenance of a modelling project's website

Motivation

Implementation

Use

Docs: Why ready4 is object oriented

Motivation

Implementation

Modular Computational Models

Encapsulation

Inheritence

Transparent Computational Models

Polymorphism

Abstraction

Docs: Search open access data collections

Docs: Finding modules of health economic models

Docs: Find examples of how model modules are used

Motivation

Implementation

Use

Related content