ready4 – Framework - foundation

Docs: Installing the ready4 framework foundation library

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

Before you install

If you plan to use ready4 for any purpose, you will need to install the ready4 foundation library.

As all software in the ready4 suite depends on the ready4 library, in most cases you do not need to install this library directly (it will come bundled with whatever other ready4 suite software you install).

If you can run the following command without producing an error message, then you already have it.

find.package("ready4")

Installation

You can install the ready4 library from CRAN.

utils::install.packages("ready4")

Alternatively, you can install the latest development release of ready4 directly from its GitHub repository.

utils::install.packages("devtools")
devtools::install_github("ready4-dev/ready4")

Try it out!

Before you apply ready4 tools to your own project, you should make sure you can run some or all of the example code included in the package vignettes.

Blog: Framework library releases

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

Currently available (as at 28-Jan-2026) releases of framework libraries are described below.

## NULL

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: Framework library descriptions

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

The two types of framework library are:

- the foundational ready4 module and syntax; and
- tools to implement standardised, semi-automated workflows for authoring and documenting computational models.

Currently available framework libraries are summarised below.

Purpose	Documentation	Code	Examples
Author, Ingest, Label and Share Health Economic Model Datasets	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	1, 2, 3
Author Health Economic Analysis Programs and Reporting Templates	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	4
Author and Document Functions that Implement Transferable Health	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	5
Author and Document Classes that Make Health Economic Models	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev, Archive	6
Author R Packages of Health Economic Model Modules	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	7
Implement Transparent, Reusable and Updatable Computational Health	Citation , Website , Manual - Short (PDF) , Manual - Full (PDF)	Dev , Archive	8 , 9 , 10, 11

Blog: ready4 PharmacoEconomics article

Tue, 21 May 2024 00:00:00 +0000

The ready4 framework has achieved another milestone with the publication of the first peer-reviewed article relating to its development and application.

The first peer-reviewed publication describing the ready4 software framework is now available in PharmacoEconomics. Thank you to the co-authors, advisers and peer-reviewers who helped achieve this outcome.

Blog: ready4 is now on CRAN

Wed, 17 Apr 2024 00:00:00 +0000

The ready4 framework has reached a major milestone with the inclusion on CRAN of the ready4 foundation library.

The first of the six libraries that comprise the ready4 software framework is now available on CRAN. Thank you to the volunteer peer-reviewers who took the time to review our submissions and help ensure that the library was compliant with all required CRAN policies.

Blog: Introducing ready4 framework modules and syntax

Fri, 14 Jan 2022 00:00:00 +0000

The ready4 framework has reached a major milestone with the launch of tools to implement modular models that use a simple and consistent syntax.

Development version software to implement and extend the ready4 framework has been publicly available for over a year now. However, the way that this code was limited has limited its potential utility as a toolkit for developing transparent and modular mental health systems models. The latest release of the ready4 R package addresses these limitations with two important innovations:

introducing the concept of modules, to facilitate consistent application of an Object Oriented Programming approach throughout the ready4 software suite;
codifying a simple and consistent syntax for use in all programs that implement configurations of models developed with the ready4 framework.

To view or cite the archive copy of the version of the ready4 package which introduced these innovations use https://doi.org/10.5281/zenodo.5847544. To view or cite the most recently archived copy of the ready4 package use https://doi.org/10.5281/ZENODO.5606250. The latest documentation for the package is available at https://ready4-dev.github.io/ready4/