ready4 – Documentation

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.

Docs: Installing tools for authoring computational models

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

Before you install

If you are a coder planning on using ready4 to author computational models, then you may wish to install the ready4class, ready4fun and ready4pack libraries.

However, please note that none of these libraries are yet available as a production release. You should therefore understand the limitations of using ready4 software development releases before you make the decision to install this software. Although we use these authoring tools intensively to help us write highly standardised model modules, we feel that these tools are only likely to be helpful to others once much more comprehensive documentation and training resources become available. Without this training and support, these packages are unlikely to appear to be very user-friendly. Furthermore, the initial burden of complying with house-style, file-naming and directory structure requirements of these packages is only likely to be worthwhile if you plan on developing multiple ready4 module libraries. If you still think these tools could be useful to you, consider contacting us first to discuss what additional information may be most helpful to you.

Installation

As ready4class and ready4fun are bundled as dependencies of ready4pack, you can install all three from our GitHub organisation using one command.

devtools::install_github("ready4-dev/ready4pack")

Configuration

To use these computational model authoring tools, you will need to have set-up and appropriately configured your own accounts in:

GitHub (you will need write permissions to a GitHub organisation and to then enable GitHub actions and GitHub pages support for the repositories you create in that organisation);
Zenodo (you will need to have linked each GitHub repository used for your ready4 projects to your Zenodo account); and
Codecov (linked to your GitHub organisation).

The machine onto which you install ready4pack will also need to be securely storing your GitHub credentials (i.e. the value for the GITHUB_PAT token).

Try it out!

It should be noted that the development workflow supported by our computational model authoring tools is not yet well documented. We don’t recommend undertaking R package development with these tools until this has been rectified. However, if you still want to try these tools out, the best place to start is review the examples in the ready4class, ready4fun and ready4pack vignettes.

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: Code repositories

Mon, 01 Jan 0001 00:00:00 +0000

Currently:

one framework library is available on the Comprehensive R Archive Network;
development releases for all ready4 libraries are available in the ready4-dev GitHub organisation; and
citable and uniquely identified (with a DOI) archived releases of ready4 libraries are available in the ready4 Zenodo community and are indexed in OpenAire Explore.

Docs: Motivation

Mon, 01 Jan 0001 00:00:00 +0000

Problem

Health economic models are a potentially useful tool to help health decision makers navigate complexity, but can have significant limitations such as:

Mistakes: Errors, common in even relatively simple health economic models, become both more likely to occur and more difficult to detect as model complexity grows;
Poor transparency: the validity of model analyses can be difficult to adequately ascertain if it is not clear who contributed to the model, what assumptions they made, how model algorithms were implemented, how those algorithms were tested and what data they were applied to;
Contested legitimacy: the value judgments of the model development team (e.g. what types of question are most important for a model to address, what parts of the workings of the system of interest to represent and in what detail, what outcome variables to include, which stakeholders to consult, etc) may differ from those using or affected by model outputs;
Narrow applicability: a model might be too simple to adequately explore some problems and too complex to reliably address others and be hard to transfer beyond a very specific decision context (e.g. within a specific jurisdiction);
Limited interoperability: different approaches to model implementation, dissemination, ownership and reporting makes it more difficult for multiple models to be efficiently and safely combined;
Ease of misuse: in the absence of clear documentation and prominent caveats, a model can easily be applied to decision problems to which it is poorly suited (potentially supporting decisions with serious negative consequences);
Restricted access: a potential overcompensation for fear of model misuse is constructing high barriers to accessing model code and data - thus limiting model testing, reuse and refinement; and
Growing stale: health economic models are rarely updated, meaning they can lose validity with time (e.g. input data becomes less relevant, new better performing algorithms are not incorporated, sudden major changes in environment / epidemiology / policy / service system are not accounted for).

Reponse

To help address these issues, the ready4 software framework aims to support transparent, reusable and updatable model implementations using R.

Docs: Installing tools for authoring and managing model datasets

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

Before you install

If you are a coder or modeller planning to create, share and access model datasets with ready4, then you will need the ready4use library.

However, please note that ready4use is not yet available as a production release. You should therefore understand the limitations of using ready4 software development releases before you make the decision to install this software.

You may already have ready4use installed on your machine (e.g. if you have previously installed other ready4 framework and module libraries that include ready4use as a dependency). If you can run the following command without producing an error message, then you already have it.

find.package("ready4use")

Installation

You can install ready4use directly from its GitHub repository.

devtools::install_github("ready4-dev/ready4use")

Configuration

If one of your intended uses of ready4use is to share outputs in online datasets, you will need to have set up an account on a Dataverse installation (we recommend using the Harvard Dataverse). Some of the key terms and concepts relating to using a Dataverse installation in conjunction with ready4use are described in this tutorial.

You need to ensure that you have write permissions to any Dataverse Datasets that you plan to use to post files to. Furthermore, the machine on which you install ready4use should also securely store your Dataverse account credentials (specifically, values for the DATAVERSE_KEY and DATAVERSE_SERVER tokens). Details of how to do this are described in documentation for the dataverse R package, an important third party dependency package for ready4use.

Try it out

You should now be able to run the example code included in the package vignettes. To run all of this code you will need to replace the details of the Dataverse Dataset to which files are being written to those of your own Dataverse Dataset.

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: Finding modules and sub-modules

Thu, 30 Nov 2023 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

When considering whether to use model modules, model developers and users will often want to see examples of each module’s application The ready4 package includes tools to allow a modelling project’s maintainers to perform automated searches for vignette examples of model modules and to output tabular summaries of these modules that are suitable for inclusion on documentation website pages.

Implementation

Details of how to search for themed collections of modules is described in another article. A table itemising individual model modules and sub-modules authored with ready4 can be generated using make_modules_tb. This function scrapes relevant data from the websites of module libraries that have been developed within a specified project’s GitHub organisation and may take a couple of minutes to execute. In this example, we are going to examine modules from a youth mental health model.

modules_tb <-  make_modules_tb(gh_repo_1L_chr = "ready4-dev/ready4")

A slightly quicker method to achieve a similar result is to use the get_modules_tb function. This function retrieves an archived version (and therefore potentially less up to date) of the modules summary table.

# Not run
# modules_tb <- get_modules_tb(gh_repo_1L_chr = "ready4-dev/ready4")

The modules_tb object itemises both ready4 modules (which always use R’s “S4” class type) and sub-modules (“S3” class type). To display a HTML summary of just ready4 modules, you can use the print_modules function.

print_modules(modules_tb, what_1L_chr = "S4")

Class	Description	Examples
AusACT	Meta data for processing ACT population projections
AusHeadspace	Meta data for constructing Headspace Centre geometries
AusLookup	Lookup tables for Australian geometry and spatial attribute data
AusOrygen	Meta data for constructing OYH Specialist Mental Health Catchment geometries
AusProjections	Meta data for constructing custom Australian population projections boundary
AusTasmania	Meta data for processing Tasmanian population projections
CostlyCorrespondences	Collection of input, standards definition and results datasets for projects to generate standardised costing datasets	1, 2
CostlyCountries	Collection of input, standards definition and results datasets for projects to generate standardised country data for use in costing datasets	1, 2
CostlyCurrencies	Collection of input, standards definition and results datasets for projects to generate standardised currency data for use in costing datasets	2
CostlySeed	Original (non-standardised) dataset (and metadata)	1, 2
CostlySource	Input dataset (and metadata) for generating standardised costing datasets
CostlyStandards	Dataset (and metadata) defining the allowable values of specified variables	1, 2
ScorzAqol6	A dataset and metadata to support implementation of an AQoL-6D scoring algorithm
ScorzAqol6Adol	A dataset and metadata to support implementation of a scoring algorithm for the adolescent version of AQoL-6D	3
ScorzAqol6Adult	A dataset and metadata to support implementation of a scoring algorithm for the adult version of AQoL-6D
ScorzEuroQol5	A dataset and metadata to support implementation of an EQ-5D scoring algorithm	4
ScorzProfile	A dataset to be scored, its associated metadata and details of the scoring instrument
SpecificConverter	Container for seed objects used for creating SpecificModels modules	5
SpecificFixed	Modelling project dataset, input parameters and complete fixed models results
SpecificInitiator	Modelling project dataset, input parameters and empty results placeholder
SpecificMixed	Modelling project dataset, input parameters and complete mixed models results
SpecificModels	Modelling project dataset, input parameters and model comparison results
SpecificParameters	Input parameters that specify candidate models to be explored
SpecificPredictors	Modelling project dataset, input parameters and predictor comparison results
SpecificPrivate	Analysis outputs not intended for public dissemination
SpecificProject	Modelling project dataset, parameters and results
SpecificResults	Analysis results
SpecificShareable	Analysis outputs intended for public dissemination
SpecificSynopsis	Input, Output and Authorship Data For Generating Reports
TTUProject	Input And Output Data For Undertaking and Reporting Utility Mapping Studies	6
TTUReports	Metadata to produce utility mapping study reports
TTUSynopsis	Input, Output and Authorship Data For Generating Utility Mapping Study Reports
VicinityArguments	Function arguments for constructing a spatial object
VicinityLocal	Object defining data to be saved in local directory
VicinityLocalProcessed	Object defining data to be saved in local directory in a processed (R) format
VicinityLocalRaw	Object defining data to be saved in local directory in a raw (unprocessed) format
VicinityLookup	Look up tables for spatiotemporal data
VicinityMacro	Macro level context
VicinityMesoArea	Meso level context - area
VicinityMesoRegion	Meso level context - region
VicinityMicro	Micro level context
VicinityProfile	Information to create a profiled area object
VicinitySpaceTime	Spatiotemporal environment
YouthvarsDescriptives	Metadata about descriptive statistics to be generated
YouthvarsProfile	A dataset and its associated dictionary, descriptive statistics and metadata	8
YouthvarsSeries	A longitudinal dataset and its associated dictionary, descriptive statistics and metadata	8

You can use the same function to display only ready4 sub-modules.

print_modules(modules_tb, what_1L_chr = "S3")

Class	Description	Examples
specific_models	Candidate models lookup table
specific_predictors	Candidate predictors lookup table
vicinity_abbreviations	ready4 S3 class for tibble object lookup table for spatial data abbreviations
vicinity_identifiers	ready4 S3 class for tibble object lookup table of unique feature identifiers used for different spatial objects
vicinity_mapes	ready4 S3 class for tibble object that stores spatial simulation parameters relating to Mean Absolute Prediction Errors
vicinity_parameters	ready4 S3 class for tibble object that stores simulation structural parameters relating to the spatial environment
vicinity_points	ready4 S3 class for tibble object lookup table of the longitude and latitude cordinates of sites of services / homes
vicinity_processed	ready4 S3 class for tibble object lookup table of meta-data for spatial data packs (imported and pre-processed data)
vicinity_raw	ready4 S3 class for tibble object lookup table of metadata about raw (un-processed) spatial data to import
vicinity_resolutions	ready4 S3 class for tibble object lookup table of the relative resolutions of different spatial objects
vicinity_templates	ready4 S3 class for tibble object lookup table for base file used in creation of certain spatial objects
vicinity_values	ready4 S3 class for tibble object that stores simulation parameter values for each iteration
youthvars_aqol6d_adol	youthvars ready4 sub-module (S3 class) for Assessment of Quality of Life Six Dimension Health Utility - Adolescent Version (AQoL6d Adolescent)	7
youthvars_bads	youthvars ready4 sub-module (S3 class) for Behavioural Activation for Depression Scale (BADS) scores	7
youthvars_chu9d_adolaus	youthvars ready4 sub-module (S3 class) for Child Health Utility Nine Dimension Health Utility - Australian Adolescent Scoring (CHU-9D Australian Adolescent)	7
youthvars_gad7	youthvars ready4 sub-module (S3 class) for Generalised Anxiety Disorder Scale (GAD-7) scores	7
youthvars_k10	youthvars ready4 sub-module (S3 class) for Kessler Psychological Distress Scale (K10) - US Scoring System scores	7
youthvars_k10_aus	youthvars ready4 sub-module (S3 class) for Kessler Psychological Distress Scale (K10) - Australian Scoring System scores	7
youthvars_k6	youthvars ready4 sub-module (S3 class) for Kessler Psychological Distress Scale (K6) - US Scoring System scores	7
youthvars_k6_aus	youthvars ready4 sub-module (S3 class)for Kessler Psychological Distress Scale (K6) - Australian Scoring System scores	7
youthvars_oasis	youthvars ready4 sub-module (S3 class) for Overall Anxiety Severity and Impairment Scale (OASIS) scores	7
youthvars_phq9	youthvars ready4 sub-module (S3 class) for Patient Health Questionnaire (PHQ-9) scores	7
youthvars_scared	youthvars ready4 sub-module (S3 class) for Screen for Child Anxiety Related Disorders (SCARED) scores	7
youthvars_sofas	youthvars ready4 sub-module (S3 class) for Social and Occupational Functioning Assessment Scale (SOFAS)	7

Docs: Installing authoring tools

Tue, 06 Dec 2022 00:00:00 +0000

Docs: Using ready4 modules

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

Docs: Our priorities

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

Docs: Installing tools for authoring reproducible analyses

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

Before you install

If you are a coder or modeller planning to implement a reproducible analysis with ready4, you will need to install the ready4show library.

However, please note that ready4show is not yet available as a production release. You should therefore understand the limitations of using ready4 software development releases before you make the decision to install this software.

If you have installed other ready4 libraries, then ready4show may have already been installed as a dependency. If you can run the following command without producing an error message, then you already have it.

find.package("ready4show")

Installation

The ready4show library can be installed directly from its GitHub repository.

devtools::install_github("ready4-dev/ready4show")

Try it out!

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

Docs: Installing ready4 computational model modules

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

Before you install

If you plan on using existing ready4 modules for a modelling project, you can review currently available module libraries, to identify which libraries are relevant to your project.

However, please note that no ready4 module library is yet available as a [production release](/docs/software/status/production-releases/. You should therefore understand the limitations of using ready4 software development releases before you make the decision to install this software.

Installation

The command to install each ready4 module takes the following format.

devtools::install_github("ready4-dev/PACKAGE_NAME")

For example, if you are planning to predict health utility using some of the mapping algorithms that we have previously developed, you can install the youthu library with the following command.

devtools::install_github("ready4-dev/youthu")

Configuration

A small number of ready4 modules require that you configure some of the dependencies installed with them before they can be used. In particular:

if you are using modules from the TTU package to undertake a utility mapping study, you will need to have both installed and configured the cmdstanr R package as per the instructions on that package’s documentation website; and
if you are using the mychoice package to undertake a discrete choice experiment study and are using a Mac, you need to ensure that you have a Fortran compiler installed. Some relevant advice on this: https://mac.r-project.org/tools/ .

Try it out!

Before you apply ready4 modules to your own project, you should make sure you can run some or all of the example code included in relevant library vignette articles. The package website URL takes the form of https://ready4-dev.github.io/PACKAGE_NAME/articles/ (e.g. the vignettes for the youthvars package are available at https://ready4-dev.github.io/youthvars/articles/).

Docs: Create a synthetic population of young people attending primary mental health services

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

This below section renders an R Markdown program. The following alternative options may provide improved viewing experience, more contextual information and access to more useful code formats:

Introduction

This program generates a purely synthetic (i.e. fake - no trace of any real records) population that is reasonably representative of the input data we used for the utility mapping study described in the article https://doi.org/10.1101/2021.07.07.21260129.

No access to the real data is required in order to use this program - it is based on summary statistics (e.g. means and standard deviations of variables, correlation matrices). It should be noted however, that a different (and simpler) workflow can be implemented when you do have access to the source dataset (for example, by using the syn function from the synthpop package).

The output of this program is very similar but not identical to a fake dataset created by an earlier version of this program and which is saved in the “ymh_clinical_dict_r3.RDS” file from the https://doi.org/10.7910/DVN/HJXYKQ data repository.

Install required R packages

If you do not have the following packages already installed, uncomment and run the following lines.

# install.packages("faux")
# devtools::install_github("ready4-dev/ready4) 
# devtools::install_github("ready4-dev/youthvars) 
# devtools::install_github("ready4-dev/scorz) 
# devtools::install_github("ready4-dev/specific") 
# devtools::install_github("ready4-dev/TTU")
# devtools::install_github("ready4-dev/youthu")

Load the ready4 framework package.

library(ready4)

Specify parameters to generate outcome fake data

AQoL item response parameters

The first set of input data are the proportions for each allowed response for each of the twenty AQOL-6D questions at both baseline and followup.

aqol_items_prpns_tbs_ls <- list(bl_answer_props_tb = tibble::tribble(
    ~Question, ~Answer_1, ~Answer_2, ~Answer_3, ~Answer_4, ~Answer_5, ~Answer_6,
    "Q1", 0.35, 0.38, 0.16, 0.03, NA_real_,100, # Check item 5 in real data.
    "Q2", 0.28, 0.38, 0.18, 0.08, 0.04,100,
    "Q3", 0.78, 0.18, 0.03, 0.01, 0.0, 100,
    "Q4", 0.64, 0.23, 0.09, 0.0, 100, NA_real_,
    "Q5", 0.3, 0.48, 0.12, 0.05, 100, NA_real_,
    "Q6", 0.33, 0.48, 0.15, 100, NA_real_,NA_real_,
    "Q7", 0.44, 0.27, 0.11, 100, NA_real_, NA_real_,
    "Q8", 0.18, 0.29, 0.23, 0.21, 100, NA_real_,
    "Q9", 0.07, 0.27, 0.19, 0.37, 100, NA_real_,
    "Q10", 0.04, 0.15, 0.4, 0.25, 100, NA_real_,
    "Q11", 0.03, 0.13, 0.52, 0.25, 100, NA_real_,
    "Q12", 0.06, 0.21, 0.25, 0.34, 100, NA_real_,
    "Q13", 0.05, 0.25, 0.31, 0.28, 100, NA_real_,
    "Q14", 0.05, 0.3, 0.34, 0.25, 100, NA_real_,
    "Q15", 0.57, 0.25, 0.12, 100, NA_real_,NA_real_,
    "Q16", 0.48, 0.42, 0.06, 100, NA_real_, NA_real_,
    "Q17", 0.44, 0.3, 0.16, 0.07, 100, NA_real_,
    "Q18", 0.33, 0.38, 0.25, 0.04, 0.0, 100,
    "Q19", 0.33, 0.49, 0.16, 0.02, 0.0, 100,
    "Q20", 0.67, 0.21, 0.02, 100, NA_real_,NA_real_),
    fup_answer_props_tb = tibble::tribble(
    ~Question, ~Answer_1, ~Answer_2, ~Answer_3, ~Answer_4, ~Answer_5, ~Answer_6,
    "Q1", 0.51, 0.33, 0.12, 0.02, NA_real_, 100,
    "Q2", 0.36, 0.38, 0.16, 0.06, 0.02,100,
    "Q3", 0.81, 0.15, 0.04, 0.00, 0.0, 100,
    "Q4", 0.73, 0.18, 0.09, 0.0, 100, NA_real_,
    "Q5", 0.36, 0.42, 0.12, 0.05, 100, NA_real_,
    "Q6", 0.48, 0.40, 0.11, 100, NA_real_,NA_real_,
    "Q7", 0.57, 0.25, 0.09, 100, NA_real_, NA_real_,
    "Q8", 0.31, 0.33, 0.17, 0.12, 100, NA_real_,
    "Q9", 0.13, 0.35, 0.19, 0.23, 100, NA_real_,
    "Q10", 0.1, 0.21, 0.43, 0.16, 100, NA_real_,
    "Q11", 0.06, 0.25, 0.48, 0.18, 100, NA_real_,
    "Q12", 0.08, 0.27, 0.26, 0.25, 100, NA_real_,
    "Q13", 0.07, 0.37, 0.31, 0.19, 100, NA_real_,
    "Q14", 0.08, 0.37, 0.34, 0.15, 100, NA_real_,
    "Q15", 0.62, 0.23, 0.09, 100, NA_real_,NA_real_,
    "Q16", 0.52, 0.40, 0.06, 100, NA_real_, NA_real_,
    "Q17", 0.51, 0.28, 0.15, 0.06, 100, NA_real_,
    "Q18", 0.37, 0.35, 0.25, 0.03, 0.0, 100,
    "Q19", 0.43, 0.40, 0.16, 0.01, 0.0, 100,
    "Q20", 0.77, 0.21, 0.02, 100, NA_real_,NA_real_)) %>%
  youthvars::make_complete_prpns_tbs_ls()

Outcome variable correlation parameters

First we specify the names of variables we will be creating as outcome variables.

var_names_chr <- c("aqol6d_total_w","phq9_total","bads_total",
                   "gad7_total","oasis_total","scared_total","k6_total")

The next step is to specify the correlations between outcome variables (variables assumed to be ordered as in previous step) at baseline and follow-up timepoints.

cor_mat_ls <- list(matrix(c(1,-0.78,0.72,-0.67,-0.71,-0.65,-0.67,
                               NA,1,-0.73,0.69,0.66,0.63,0.71,
                               NA,NA,1,-.57,-0.64,-0.57,-0.65,
                               NA,NA,NA,1,0.74,0.70,0.63,
                               NA,NA,NA,NA,1,0.7,0.59,
                               NA,NA,NA,NA,NA,1,0.55,
                               NA,NA,NA,NA,NA,NA,1),7,7),
                    matrix(c(1,-0.81,0.72,-0.71,-0.73,-0.64,-0.68,
                        NA,1,-0.72,0.69,0.68,0.61,0.68,
                        NA,NA,1,-0.59,-0.61,-0.51,-0.61,
                        NA,NA,NA,1,0.75,0.71,0.6,
                        NA,NA,NA,NA,1,0.68,0.59,
                        NA,NA,NA,NA,NA,1,0.52,
                        NA,NA,NA,NA,NA,NA,1),7,7))

We now specify the univariate distribution parameters for each of the outcome variables.

synth_data_spine_ls <- list(cor_mat_ls = cor_mat_ls,
                            nbr_obs_dbl = c(1068,643),
                            timepoint_nms_chr = c("BL","FUP"),
                            means_ls = list(c(0.6,12.8,78.2, 10.4,8.1,34.2,12.2),
                                            c(0.7,9.8,89.4, 7.9,6.3,28.8,9.8)),
                            sds_ls = list(c(0.2,6.6,24.8,5.7,4.7,17.9,5.8),
                                          c(0.2,6.5,24.4,5.5,4.3,17.8,5.9)),
                            missing_ls = list(c(0,4,10,6,7,7,4),
                                              c(0,5,2,2,1,2,2)),
                            min_max_ls = list(c(0.03,1),
                                              c(0,27),
                                              c(0,150),
                                              c(0,21),
                                              c(0,20),
                                              c(0,82),
                                              c(0,24)),
                            discrete_lgl = c(F,rep(T,6)),
                            var_names_chr = var_names_chr,
                            aqol_tots_var_nms_chr = c(cumulative = "aqol6d_total_c",
                                                      weighted = "aqol6d_total_w"))

Generate fake data

Create fake outcome variable datasets

We now use the parameters we have just specified to create baseline and follow-up datasets with fake data for our nominated outcome variables.

aqol_scores_pars_ls <- list(means_dbl = c(44.5,40.6), 
                            sds_dbl = c(9.9,9.8),
                            corr_dbl = -0.95)
aqol6d_adol_pop_tbs_ls <- aqol_items_prpns_tbs_ls %>%
  scorz::make_aqol6d_adol_pop_tbs_ls(aqol_scores_pars_ls = aqol_scores_pars_ls,
                                     series_names_chr =  c("bl_outcomes_tb",
                                                           "fup_outcomes_tb"),
                                     synth_data_spine_ls = synth_data_spine_ls,
                                     temporal_cors_ls = list(aqol6d_total_w = 0.85))
#> Joining with `by = join_by(id, match_var_chr)`
#> Joining with `by = join_by(id)`
#> Joining with `by = join_by(id, match_var_chr)`
#> Joining with `by = join_by(id)`

Create fake descriptive variables

We now specify the names and statistical parameters of the variables we will be using in descriptive statistics. For this analysis we are not interested in capturing the joint distribution between these variables, so we only use univariate parameters.

descriptives_BL_tb <- tibble::tibble(fkClientID = aqol6d_adol_pop_tbs_ls$bl_outcomes_tb$fkClientID,
                                     round = c(1) ,
                                     d_age = rnorm(1068,18.1,3.3) %>% 
                                       purrr::map_dbl(~min(.x,25) %>% 
                                                        max(12)),
                                     d_gender = c(rep(1,653),
                                                  rep(2,359),
                                                  rep(3,39),
                                                  rep(NA_real_,17)) %>% 
                                       specific::scramble_xx() %>%
                                       factor(labels = c("Female","Male","Other")),
                                     d_sexual_ori_s = c(rep(1,738),
                                                        rep(2,289),
                                                        rep(NA_real_,41)) %>% 
                                       specific::scramble_xx() %>%
                                       factor(labels = c("Straight","Other")),
                                     Region = c(rep(1,671),
                                                rep(2,397)) %>% 
                                       specific::scramble_xx() %>%
                                       factor(labels = c("Metro","Regional")),
                                     CALD = c(rep(T,759),
                                              rep(F,169),
                                              rep(NA,140)) %>% 
                                       specific::scramble_xx(),
                                     d_studying_working = c(rep(1,405),
                                                            rep(2,167),
                                                            rep(3,305),
                                                            rep(4,159),
                                                            rep(NA_real_,32)) %>% 
                                       specific::scramble_xx() %>% 
                                       factor(labels = c("Studying only",
                                                         "Working only",
                                                         "Studying and working",
                                                         "Not studying or working")),
                                     c_p_diag_s = c(rep(1,182),
                                                    rep(2,264),
                                                    rep(3,332),
                                                    rep(4,237),
                                                    rep(NA_real_,53)) %>% 
                                       specific::scramble_xx() %>%
                         factor(labels = c("Depression", "Anxiety","Depression and Anxiety", "Other")),
                         c_clinical_staging_s = c(rep(1,625),
                                                  rep(2,326),
                                                  rep(3,86),
                                                  rep(NA_real_,31)) %>% 
                           specific::scramble_xx() %>%
                           factor(labels = c("0-1a","1b","2-4")),
                         c_sofas = c(rnorm(1068-30,65.2,9.5),
                                     rep(NA_real_,30)) %>% 
                           purrr::map_dbl(~min(.x,100) %>% 
                                            max(0)) %>% 
                           specific::scramble_xx(),
                         s_centre = NA_character_, 
                         d_agegroup = NA_character_, 
                         d_sex_birth_s = NA_character_, 
                         d_country_bir_s = NA_character_,
                         d_ATSI = NA_character_,
                         d_english_home = NA, 
                         d_english_native = NA, 
                         d_relation_s = c(rep(1,325),
                                          rep(2,426),
                                          rep(3,286),
                                          rep(NA_real_,31)) %>% 
                           specific::scramble_xx() %>%
                           factor(labels = c("REPLACE_ME_1",
                                             "REPLACE_ME_2",
                                             "REPLACE_ME_3")))  %>%
  dplyr::mutate(d_sex_birth_s = dplyr::case_when(is.na(d_gender) ~ NA_integer_,
                                                 as.integer(d_gender) %in% 
                                                   c(1L,2L) & 
                                                   runif(1068)>0.995 ~ as.integer(d_gender) %>%
                                                   purrr::map_int(~ ifelse(is.na(.x), 
                                                                           .x, 
                                                                           switch(.x,2L,1L,3L))),
                                                 as.integer(d_gender) == 3 ~ sample(c(1L,2L), 
                                                                                    1068, 
                                                                                    replace = T),
                                                 TRUE ~ as.integer(d_gender)
                                                 ) %>%
                  factor(labels = c("Female","Male")))
#> Registered S3 methods overwritten by 'ggalt':
#>   method                  from   
#>   grid.draw.absoluteGrob  ggplot2
#>   grobHeight.absoluteGrob ggplot2
#>   grobWidth.absoluteGrob  ggplot2
#>   grobX.absoluteGrob      ggplot2
#>   grobY.absoluteGrob      ggplot2
#> Registered S3 methods overwritten by 'rmutil':
#>   method         from 
#>   plot.residuals psych
#>   print.response httr
descriptives_FUP_tb <- descriptives_BL_tb %>% 
  dplyr::filter(fkClientID %in% 
                  aqol6d_adol_pop_tbs_ls$fup_outcomes_tb$fkClientID) %>%
  dplyr::mutate(round = 2,
                d_age = d_age + 0.25,
                Region = Region %>% 
                  specific::randomise_changes_in_fct_lvls(0.98),
                d_studying_working = d_studying_working %>%
                  specific::randomise_changes_in_fct_lvls(0.9),
                c_p_diag_s = c_p_diag_s %>% 
                  specific::randomise_changes_in_fct_lvls(0.90),
                c_clinical_staging_s = c_clinical_staging_s %>% 
                  specific::randomise_changes_in_fct_lvls(0.8),
                c_sofas = c_sofas + rnorm(643,4.7,10) %>% 
                         purrr::map_dbl(~min(.x,100) %>% max(0)))
bl_tb <- dplyr::inner_join(descriptives_BL_tb,
                           aqol6d_adol_pop_tbs_ls$bl_outcomes_tb) 
#> Joining with `by = join_by(fkClientID)`
fup_tb <- dplyr::inner_join(descriptives_FUP_tb,
                            aqol6d_adol_pop_tbs_ls$fup_outcomes_tb)
#> Joining with `by = join_by(fkClientID)`

We make some adjustments to ensure that the c_sofas variable is correlated with our aqol6d_total_w variable at both baseline and follow-up.

bl_tb <- bl_tb %>%
  dplyr::mutate(c_sofas = faux::rnorm_pre(bl_tb$aqol6d_total_w %>% 
                                            as.vector(), 
                                          mu = 65.2, 
                                          sd = 9.5, 
                                          r = 0.5, 
                                          empirical = T) %>% 
                  purrr::map_dbl(~min(.x,100) %>% max(0)))
fup_tb <- fup_tb %>%
  dplyr::mutate(c_sofas = faux::rnorm_pre(fup_tb$aqol6d_total_w %>% 
                                            as.vector(), 
                                          mu = 69.9, 
                                          sd = 10, 
                                          r = 0.5, 
                                          empirical = T) %>% 
                  purrr::map_dbl(~min(.x,100) %>% max(0)))

Combine datasets

We now add the fake outcome variables dataset to the fake descriptive variables dataset.

composite_tb <- dplyr::bind_rows(bl_tb, fup_tb) %>%
  dplyr::mutate(d_age = floor(d_age)) %>%
  dplyr::mutate(d_gender = d_gender %>% as.character() %>%
                  purrr::map_chr(~ifelse(.x=="Other",
                                         sample(c("Genderqueer/gender nonconforming/agender",
                                                              "Transgender"),1),
                                         .x)),
                s_centre = Region %>% as.character() %>%
                  purrr::map_chr(~ifelse(.x=="Metro",
                                         sample(c("Canberra","Southport","Knox"),1),
                                         "Regional Centre")),
                d_country_bir_s = CALD %>%
                  purrr::map_chr(~ifelse(.x,
                                         "Other",
                                         "Australia")), 
                       d_ATSI = CALD %>%
                  purrr::map_chr(~ifelse(.x,
                                         "Yes",
                                         "No")),
                       d_english_home = CALD %>%
                  purrr::map_chr(~ifelse(.x,
                                         "No",
                                         "Yes")), 
                       d_english_native = CALD %>%
                  purrr::map_chr(~ifelse(.x,
                                         "No",
                                         "Yes"))
                ) %>%
  dplyr::select(-CALD) %>%
  dplyr::select(-Region)
composite_tb <- composite_tb %>%
  dplyr::select(-setdiff(names(composite_tb)[startsWith(names(composite_tb),
                                                        "aqol6d_")],
                         names(composite_tb)[startsWith(names(composite_tb),
                                                        "aqol6d_q")]))
composite_tb <- composite_tb %>%
  dplyr::mutate(c_sofas = as.integer(round(c_sofas,0))) %>%
  dplyr::mutate(round = factor(round, labels = c("Baseline",
                                                 "Follow-up"))) %>%
  dplyr::mutate(d_relation_s = dplyr::case_when(d_relation_s %in% 
                                                  c("REPLACE_ME_1","REPLACE_ME_2") ~ 
                                                  "Not in a relationship",
                                                T ~ "In a relationship")) %>%
  youthu::add_dates_from_dstr(bl_start_date_dtm = Sys.Date() - lubridate::days(600),##
                              bl_end_date_dtm = Sys.Date() - lubridate::days(420),
                              duration_args_ls = list(a = 60, b = 140, mean = 90, sd = 10),
                              duration_fn = truncnorm::rtruncnorm,
                              date_var_nm_1L_chr = "d_interview_date") %>%
  dplyr::select(-duration_prd) %>%
  youthvars::transform_raw_ds_for_analysis() %>%
  dplyr::rename(phq9_total = PHQ9,
                bads_total = BADS,
                gad7_total = GAD7,
                oasis_total = OASIS,
                scared_total = SCARED,
                k6_total = K6,
                c_sofas = SOFAS) %>%
  dplyr::select(-c("d_agegroup","Gender", "CALD", "Region"))

Docs: Author and share model modules

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

Docs: Modules pipeline

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

Docs: Contribution types

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

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: Overview

Mon, 01 Jan 0001 00:00:00 +0000

What is ready4?

ready4 is a prototype software framework for developing living and transferable health economic models and applying those models in reproducible and replicable research. The project is implemented in the open source language R and is led by researchers at Monash University.

What is a software framework?

A software framework is a shared technology that can be used by multiple teams to collaboratively author software.

What is a computational model?

A computational model is a simplified representation of a system of interest that is implemented in computer code.

What makes a ready4 model modular?

The paradigms we use for computational model development allow individual model components (modules) to be independently reused (in other models) and safely and flexibly combined (to model more extensive systems).

Why is that useful?

We hope that ready4 will help address significant limitations in how health economic models are implemented, encourage data sharing and facilitate modelling analyses that generate valuable insights for health policymakers and system planners.

Who is it for?

ready4 is designed to be primarily used by coders and modellers working collaboratively on computational modelling projects in which other stakeholders such as funders and researchers make essential contributions.

What is it being used for?

Currently, ready4 is being applied to develop and apply a modular model of youth mental health.

Can I use it?

ready4 is publicly available and free for you to assess (to verify and validate), apply (to use and/or author health economic model modules) and to derive your own derivative works from (to leverage and enhance the work of others) under liberal terms of use.

Why is it a prototype?

Currently, most of the ready4 software suite is available in the form of development releases. That means the libraries implementing ready4 may require more development, documentation and testing before it could be confidently used for scientific purposes other than the specific studies to which the ready4 development team have already applied it.

Why is it called ready4?

ready4 is short-hand for “readyforwhatsnext”, the title of the research project that catalysed the framework and a reference to how computational models can improve the preparedness of decision makers and system planners.

Where should I go next?

We’d recommend reading the documentation in the order in which sections appear in the table of contents (so go next to Examples, then to Getting started and so on). Scientific manuscripts on the framework’s ethical underpinnings and early implementation are also available.

Docs: Examples

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

An scientific summary of the ready4 prototype software framework and its early application in youth mental health is available as an open-access article in PharmacoEconomics.

Additional information is available from the project website of readyforwhatsnext - a modular and open source economic model of youth mental health.

Docs: Before you get started

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Model

Mon, 01 Jan 0001 00:00:00 +0000

A model is a simplified representation of a system of interest. In the way we use the term, we also mean that a model is:

abstract and general (i.e. largely free of non-modifiable data, including numeric values, that are assumption- or context- specific) and
a tool (i.e. a model can be used to help undertake an analysis, it is not the analysis itself).

If a model is used to help solve economic problems (e.g. those arising from scarcity) relating to health and healthcare it is a health economic model. Many health economic models are developed to inform a decision or set of decisions (e.g. relating to youth mental health policy and system design), in which case they can also be called a decision model.

Ideally, a health economic model should have three inter-related representations - conceptual, mathematical and computational.

Conceptual Model

A conceptual model refers to underlying theory and beliefs about a system of interest that can be described in words and pictures.

Mathematical Model

A mathematical model formalises a conceptual model as a set of equations.

Computational Model

A computational model implements the conceptual and mathematical models of a system of interest as computer code.

Computational models can take a modular approach to implementation.

Docs: Module

Mon, 01 Jan 0001 00:00:00 +0000

A modular computational model is one that constructed from multiple self-contained components, called modules. The advantages of developing a modular model include:

each module can be independently re-used in other computational models;
a complex model can be developed iteratively, beginning with a simple representation that is easier to validate and then progressively expanding in scope and functionality through the addition of new modules, to be validated independently and jointly; and
long term and resource intensive model development is more feasible through combining multiple independently managed and financed modelling projects.

To ensure that all ready4 computational model modules can be safely and flexibly combined, each module is created from a template using authoring tools that support standardisation.

Docs: Coders

Mon, 01 Jan 0001 00:00:00 +0000

If you are a coder, you may be a data scientist or software engineer by training or are perhaps a quantitative researcher who spends a high proportion of their time writing code to undertake their work.

Role

The primary role of coders in ready4 modelling projects is to author modules that implement computational models.

Tools

The ready4 tools of most use to coders are the software framework libraries for authoring modules.

Benefits

ready4 provides an opportunity to write software that matters! Our aim is to help improve population health through empowering decision makers with better models. If you already write code for health-economic modelling projects, the ready4 software framework may help you enhance your impact (facilitating code re-use) and work-efficiency (through partial automation of code development and quality-assurance workflows).

Contributing to ready4

The types of contribution you can make to ready4 include:

Docs: Modellers

Mon, 01 Jan 0001 00:00:00 +0000

If you are a modeller, you are responsible for the overall implementation of a modelling study from initial conceptualisation through to analysis and reporting. You are likely to be an economist, epidemiologist or statistician and are probably reasonably comfortable with writing analysis scripts in statistical software (potentially including R), without necessarily being a coding wizard.

Role

The primary role of modellers in ready4 modelling projects is to use modules to undertake analyse as part of modelling projects.

Tools

The ready4 tools of most use to modellers are the software framework libraries for authoring model datasets and analyses and model module libraries for use in computational modelling.

Benefits of using ready4

We hope that ready4 can be of benefit to you by helping you to efficiently build on work by other modellers, to implement more reproducible workflows, and to share your work so that it can be reused.

Contributing to ready4

The types of contribution you can make to ready4 include:

Docs: Modelling project

Mon, 01 Jan 0001 00:00:00 +0000

A ready4 modelling project will use the ready4 software framework to implement the three steps of:

Developing and validating a computational model;
Adding context-specific data to that computational model; and
Applying the computational model to the supplied data to undertake analyses.

The key components of each step are summarised here.

Docs: Planners

Mon, 01 Jan 0001 00:00:00 +0000

If you are an planner, you contribute to policy development or service planning that aims to improve population health. You probably value the role of modelling to inform your work, but are likely to rely on others to provide much of the technical expertise to implement computational models.

Role

The primary role of planners in ready4 modelling projects is co-design and use of models to support decision making.

Tools

The ready4 tools of most use to planners are user-interfaces that convert computational models into useful decision aids.

Benefits of using ready4

We hope that ready4 can provide you with transparent reusable and updatable decision support.

Contributing to ready4

The types of contribution you can make to ready4 include:

Docs: Repeatable research

Mon, 01 Jan 0001 00:00:00 +0000

Although there is widespread support from the scientific community on the importance of repeatable research, the definition of key terms such as reproducibility and replicability can vary across disciplines and methodologies (e.g. the extent to which computational modelling is used). The meanings we intend when using these terms are described below.

Reproduction and Replication

The distinctions we make between reproduction and replication have been guided by the approach outlined in a report by the National Academies of Sciences, Engineering and Medicine. However, we have adapted their definitions slightly as the meanings in that report were framed in terms of study findings / outcomes, whereas our usage relates more to intended objectives when deploying tools.

Our usage

Reproduction

Applying the same analysis code to the same input data with the expectation of generating identical outputs (with the exception of trivial artefacts like datestamps for when analysis reports were produced).

Replication

Applying analysis code used in a study to new input data. The analysis code is reused with only minimal edits that are necessary to account for differences in input data paths and variable names and to study metadata (e.g. investigator names, sample descriptions). The new data can be real or fake, but will include the same structure and concepts / measures as those found in the original study’s dataset. If the new data is a sample from the same population as the original study, then the expectation when undertaking replications is for results across studies to be broadly similar.

Suggested policies

When publishing analysis code we suggest adopting the following rules of thumb:

If the data required to re-run a study analysis are publicly available (or declared by the analysis program itself), publish the code as a reproduction program (e.g. this program for creating a synthetic population).
If the data required to re-run a study analysis are not publicly available, we publish the replication version of the code. The replication version of the code may be configured to ingest a synthetic (fake) representation of the study dataset as with this utility mapping replication program. Details of the (minimal) steps required to revert the replication code to a version that can be used for reproduction purposes are typically embedded within the program itself.

Docs: Users

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Community members

Mon, 01 Jan 0001 00:00:00 +0000

Community members have an important role to play in both the development of the overarching ready4 model and the applicability of ready4 to specific decision problems.

One of the main contributions that community members can make is to provide advice. To date, the advice we have elicited from community members has related to shaping the design and conduct of individual modelling projects. In the medium term, he hope to supplement these opportunities through growing a ready4 support community.

Docs: Funders

Mon, 01 Jan 0001 00:00:00 +0000

There are six main types of funder that can provide cash and/or in kind support to ready4:

Grant making research bodies can support modelling project proposals submitted to their existing funding schemes. These types of funder could also consider making a number of changes to how they work including the assessment weightings and levels of financial support given to the reproducibility, replicability and transferability components of research proposals and initiating targeted calls for proposals to improve the transparency, reuse and maintenance of models to inform policy.
Government departments can support the development of ready4 as part of programs to enhance data analysis and modelling capability in youth mental health by providing support to develop core ready4 infrastructure (e.g. our software maintenance and community development priorities). When commissioning new modelling projects, governments could make providing open access to code and (to the greatest extent feasible, balancing confidentiality considerations) data a requirement of all applicants.
Youth mental health service commissioners can commission data analysis and modelling projects that develop novel decision aids and to apply existing ready4 modules to undertake new analyses.
Philanthropic donors can help accelerate our development and enhance our impact by supporting us to bring our existing in-development software to launch and to further extend the ready4 model.
Corporate sponsors can provide cash, expertise and free product licenses to support both our core open-source infrastructure and individual modelling projects.

Docs: Researchers

Mon, 01 Jan 0001 00:00:00 +0000

Researchers in multiple discipline enhance prior, current or planned future projects related to how environmental, social and technical systems shape health-economic outcomes by using ready4 to:

label and share non-confidential data (e.g. tables of summary statistics / parameter values) from prior and current work to extend access and impact;
working with modellers to undertake modelling analyses;
working with coders to redevelop study analysis scripts by authoring modules that are transferable to other contexts;
supervising student projects to assist with ready4’s current priorities; and/or
develop research proposals that incorporate a modelling project.

Researchers considering using ready4 should ensure they understand the development status of the tools they wish to use. If the required software is not yet a production release (a process we are working on!) we’d suggest only using it for testing or exploratory work that is not designed to inform decision making. All our software is free and open source so you don’t need to ask our permission to use it. We are however, very happy to discuss ideas for potential collaborations - contact the project lead to arrage a chat.

We also welcome advice from researchers about how we can make ready4 more relevant and useful.

Docs: Stakeholders

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Transferability

Mon, 01 Jan 0001 00:00:00 +0000

It is common for discussions of scientific studies to consider the extent to which findings can be generalised (e.g. if a well conducted study concludes with high confidence that an intervention is cost-effective in Australia, is it valid to infer that it is likely to be cost-effective in the United Kingdom?). However, we are more interested in the transferability of computational models (e.g. the extent to which the data-structures and algorithms from a computational model developed for an Australian context can be used to explore similar topics in the United Kingdom). Our usage of the term “transferring” (and by extension “transferability”, “transferable”, “transfers”) reflects this motivation.

Transferring - our meaning

Adapting a computational model, in whole or in part, to extend the types of data and/or research questions to which it can be applied. The new types of data will possess some differences in structure and / or concepts from that to which the computational model had previously been applied and these differences may be why research questions need to be reformulated.

When we use the term transferring, we are typically referring to either (a) authoring or (b) using on of the following:

An analysis program (or sub-routine) that has been adapted from an executable from another study to account for differences in the input data / research question.
Inheriting data-structures and algorithms that selectively re-use, discard and replace elements of a study’s computational model based on an alternative use-case.
(Multi-purpose) function libraries that have been created by decomposing a study’s (single purpose) analysis program.

Examples

The scorz module library was originally developed to provide an R implementation of algorithms in other languages for scoring adolescent AQoL-6D health utility as part of a utility mapping study (which also used the analysis program mentioned above). Examples of all three approaches mentioned in the previous section can be seen by examining the documentation and source code of the scorz library:

Two vignette programs from the scorz library website score different utility instruments. The first program scores adolescent AQoL-6D health utility and acts as a template for the second, which has been modified to score EQ-5D health utility.
Inspecting those example programs shows that one of the key adaptations in the EQ-5D program is to use the ScorzEuroQol5 module instead of the ScorzAqol6Adol module. Both of these modules inherit from ScorzProfile. This arrangement means that all three modules share some features (in terms of both structure and algorithms) but selectively differ (e.g. aspects that are necessarily different for scoring different instruments).
The algorithms attached to each module from the scorz library are principally implemented by functions (the source code for which can be viewed here) that were created when decomposing an early draft of the above mentioned study algorithm. These functions are called by module methods (source code viewable here).

Docs: Downloads

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Purpose

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

The ready4 software framework provides tools to help implement computational health economic models that are transparent, reusable and updatable (TRU).

Transparent

Model code and data are publicly available in online code repositories and data collections. Algorithms are documented and transparently and regularly tested. Model development occurs in the open and invites community participation, with each individual’s contribution publicly identifiable. Analyses are reproducible and replicable.

Reusable

Model modules and datasets originally developed in one modelling project can be independently reused in other projects. As they share a common framework, model modules can be combined in other models and analyses to address multiple topics. Code implementation paradigms facilitate the transfer of model modules for use in other decision contexts.

Updatable

Model code, data and analyses are versioned, with an ongoing program of making new and updated releases. Software is maintained, with opportunities for users and contributors to flag issues, request features and supply code contributions.

The criteria we use for assessing TRU attributes of computational models are described in more detail in this preprint, with a worked example of the application of these criteria provided in this article from PharmacoEconomics.

Docs: Develop, adapt and maintain computational health economic models

Mon, 10 Jun 2024 00:00:00 +0000

Docs: Use modules of health economic models to implement repeatable research

Mon, 10 Jun 2024 00:00:00 +0000

Docs: Implementation

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

Docs: Paradigms

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

Docs: Tutorials

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

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: Authoring model data structures

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

This below section renders a vignette article from the ready4class 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(ready4class)
library(ready4show)
library(ready4use)

Motivation

The ready4 framework uses object oriented programming (OOP) to implement modular approaches to computational models of mental health systems. That means that a standardised approach to developing modules (S4 classes) and sub-modules (S3 classes) is required. ready4class provides the tools to implement this workflow.

Workflow

Prototyes, constructor and manifest

The main classes exported as part of ready4class are readyclass_manifest and ready4class_constructor. ready4class_pt_lup is a tibble based ready4 sub-module, which contains metadata on the prototypes of classes that can be used as sub-components of ready4 modules and sub-modules (for example a tibble based class can be used as a slot in an S4 class). When authoring ready4 R packages, you will create a ready4class_pt_lup instance and store it in an online repository that you have write permissions to. As you create new ready4 modules and sub-modules using ready4class tools, your ready4class_pt_lup object will be updated so that these classes can be made available to any future modules or sub-modules that you author. The ready4class_pt_lup sub-module recently used in workflows for authoring ready4 modules is reproduced below.

x <- ready4use::Ready4useRepos(gh_repo_1L_chr = "ready4-dev/ready4",
                               gh_tag_1L_chr = "Documentation_0.0") %>%
  ingest(fls_to_ingest_chr = "prototype_lup",
         metadata_1L_lgl = F) 
x %>%
  exhibit(scroll_box_args_ls = list(width = "100%"))

Class Prototypes Lookup Table
Class	Value	Namespace	Function	Default	Is Old Class
AusACT	aus::AusACT()	aus	AusACT		FALSE
AusHeadspace	aus::AusHeadspace()	aus	AusHeadspace		FALSE
AusLookup	aus::AusLookup()	aus	AusLookup		FALSE
AusOrygen	aus::AusOrygen()	aus	AusOrygen		FALSE
AusProjections	aus::AusProjections()	aus	AusProjections		FALSE
AusTasmania	aus::AusTasmania()	aus	AusTasmania		FALSE
POSIXt	.POSIXct(NA_character\_)	base	.POSIXct	NA_character\_	FALSE
character	NA_character\_	base		NA_character\_	FALSE
data.frame	data.frame()	base		data.frame()	FALSE
integer	NA_integer\_	base		NA_integer\_	FALSE
list	list(list())	base	list	list()	FALSE
logical	NA	base		NA	FALSE
numeric	NA_real\_	base		NA_real\_	FALSE
function	function() NULL	base		function() NULL	FALSE
CostlyCorrespondences	costly::CostlyCorrespondences()	costly	CostlyCorrespondences		FALSE
CostlyCountries	costly::CostlyCountries()	costly	CostlyCountries		FALSE
CostlyCurrencies	costly::CostlyCurrencies()	costly	CostlyCurrencies		FALSE
CostlySeed	costly::CostlySeed()	costly	CostlySeed		FALSE
CostlySource	costly::CostlySource()	costly	CostlySource		FALSE
CostlyStandards	costly::CostlyStandards()	costly	CostlyStandards		FALSE
dfidx	dfidx::dfidx(dfidx())	dfidx	dfidx	dfidx()	FALSE
Period	lubridate::period()	lubridate	period		FALSE
Ready4Module	ready4::Ready4Module()	ready4	Ready4Module		FALSE
Ready4Private	ready4::Ready4Private()	ready4	Ready4Private		FALSE
Ready4Project	ready4::Ready4Project()	ready4	Ready4Project		FALSE
Ready4Public	ready4::Ready4Public()	ready4	Ready4Public		FALSE
ready4class_constructor	ready4class::ready4class_constructor()	ready4class	ready4class_constructor		TRUE
ready4class_manifest	ready4class::ready4class_manifest()	ready4class	ready4class_manifest		TRUE
ready4class_pt_lup	ready4class::ready4class_pt_lup()	ready4class	ready4class_pt_lup		TRUE
ready4fun_abbreviations	ready4fun::ready4fun_abbreviations()	ready4fun	ready4fun_abbreviations		TRUE
ready4fun_badges	ready4fun::ready4fun_badges()	ready4fun	ready4fun_badges		TRUE
ready4fun_dataset	ready4fun::ready4fun_dataset()	ready4fun	ready4fun_dataset		TRUE
ready4fun_description	ready4fun::ready4fun_description()	ready4fun	ready4fun_description		TRUE
ready4fun_executor	ready4fun::ready4fun_executor()	ready4fun	ready4fun_executor		TRUE
ready4fun_functions	ready4fun::ready4fun_functions()	ready4fun	ready4fun_functions		TRUE
ready4fun_manifest	ready4fun::ready4fun_manifest()	ready4fun	ready4fun_manifest		TRUE
ready4fun_metadata_a	ready4fun::ready4fun_metadata_a()	ready4fun	ready4fun_metadata_a		TRUE
ready4fun_metadata_b	ready4fun::ready4fun_metadata_b()	ready4fun	ready4fun_metadata_b		TRUE
ready4fun_objects	ready4fun::ready4fun_objects()	ready4fun	ready4fun_objects		TRUE
ready4pack_manifest	ready4pack::ready4pack_manifest()	ready4pack	ready4pack_manifest		TRUE
ready4show_authors	ready4show::ready4show_authors()	ready4show	ready4show_authors		TRUE
ready4show_institutes	ready4show::ready4show_institutes()	ready4show	ready4show_institutes		TRUE
ready4show_correspondences	ready4show::ready4show_correspondences()	ready4show	ready4show_correspondences		TRUE
Ready4showPaths	ready4show::Ready4showPaths()	ready4show	Ready4showPaths		FALSE
Ready4showSynopsis	ready4show::Ready4showSynopsis()	ready4show	Ready4showSynopsis		FALSE
ready4use_distributions	ready4use::ready4use_distributions()	ready4use	ready4use_distributions		TRUE
ready4use_dataverses	ready4use::ready4use_dataverses()	ready4use	ready4use_dataverses		TRUE
ready4use_imports	ready4use::ready4use_imports()	ready4use	ready4use_imports		TRUE
ready4use_mapes	ready4use::ready4use_mapes()	ready4use	ready4use_mapes		TRUE
ready4use_dictionary	ready4use::ready4use_dictionary()	ready4use	ready4use_dictionary		TRUE
Ready4useFiles	ready4use::Ready4useFiles()	ready4use	Ready4useFiles		FALSE
Ready4useRaw	ready4use::Ready4useRaw()	ready4use	Ready4useRaw		FALSE
Ready4useProcessed	ready4use::Ready4useProcessed()	ready4use	Ready4useProcessed		FALSE
Ready4useArguments	ready4use::Ready4useArguments()	ready4use	Ready4useArguments		FALSE
Ready4useDyad	ready4use::Ready4useDyad()	ready4use	Ready4useDyad		FALSE
Ready4useIngest	ready4use::Ready4useIngest()	ready4use	Ready4useIngest		FALSE
Ready4useRepos	ready4use::Ready4useRepos()	ready4use	Ready4useRepos		FALSE
Ready4usePointer	ready4use::Ready4usePointer()	ready4use	Ready4usePointer		FALSE
Ready4useRecord	ready4use::Ready4useRecord()	ready4use	Ready4useRecord		FALSE
ScorzProfile	scorz::ScorzProfile()	scorz	ScorzProfile		FALSE
ScorzAqol6	scorz::ScorzAqol6()	scorz	ScorzAqol6		FALSE
ScorzAqol6Adol	scorz::ScorzAqol6Adol()	scorz	ScorzAqol6Adol		FALSE
ScorzAqol6Adult	scorz::ScorzAqol6Adult()	scorz	ScorzAqol6Adult		FALSE
ScorzEuroQol5	scorz::ScorzEuroQol5()	scorz	ScorzEuroQol5		FALSE
sf	sf::st_sf(sf::st_sfc())	sf	st_sf	sf::st_sfc()	FALSE
SpecificConverter	specific::SpecificConverter()	specific	SpecificConverter		FALSE
SpecificFixed	specific::SpecificFixed()	specific	SpecificFixed		FALSE
SpecificInitiator	specific::SpecificInitiator()	specific	SpecificInitiator		FALSE
SpecificMixed	specific::SpecificMixed()	specific	SpecificMixed		FALSE
SpecificModels	specific::SpecificModels()	specific	SpecificModels		FALSE
SpecificParameters	specific::SpecificParameters()	specific	SpecificParameters		FALSE
SpecificPredictors	specific::SpecificPredictors()	specific	SpecificPredictors		FALSE
SpecificPrivate	specific::SpecificPrivate()	specific	SpecificPrivate		FALSE
SpecificProject	specific::SpecificProject()	specific	SpecificProject		FALSE
SpecificResults	specific::SpecificResults()	specific	SpecificResults		FALSE
SpecificShareable	specific::SpecificShareable()	specific	SpecificShareable		FALSE
SpecificSynopsis	specific::SpecificSynopsis()	specific	SpecificSynopsis		FALSE
specific_models	specific::specific_models()	specific	specific_models		TRUE
specific_predictors	specific::specific_predictors()	specific	specific_predictors		TRUE
tbl_df	tibble::tibble()	tibble	tibble		FALSE
tbl_ts	tsibble::tsibble()	tsibble	tsibble		FALSE
TTUProject	TTU::TTUProject()	TTU	TTUProject		FALSE
TTUReports	TTU::TTUReports()	TTU	TTUReports		FALSE
TTUSynopsis	TTU::TTUSynopsis()	TTU	TTUSynopsis		FALSE
VicinityArguments	vicinity::VicinityArguments()	vicinity	VicinityArguments		FALSE
VicinityLocal	vicinity::VicinityLocal()	vicinity	VicinityLocal		FALSE
VicinityLocalProcessed	vicinity::VicinityLocalProcessed()	vicinity	VicinityLocalProcessed		FALSE
VicinityLocalRaw	vicinity::VicinityLocalRaw()	vicinity	VicinityLocalRaw		FALSE
VicinityLookup	vicinity::VicinityLookup()	vicinity	VicinityLookup		FALSE
VicinityMacro	vicinity::VicinityMacro()	vicinity	VicinityMacro		FALSE
VicinityMesoArea	vicinity::VicinityMesoArea()	vicinity	VicinityMesoArea		FALSE
VicinityMesoRegion	vicinity::VicinityMesoRegion()	vicinity	VicinityMesoRegion		FALSE
VicinityMicro	vicinity::VicinityMicro()	vicinity	VicinityMicro		FALSE
VicinityProfile	vicinity::VicinityProfile()	vicinity	VicinityProfile		FALSE
VicinitySpaceTime	vicinity::VicinitySpaceTime()	vicinity	VicinitySpaceTime		FALSE
vicinity_abbreviations	vicinity::vicinity_abbreviations()	vicinity	vicinity_abbreviations		TRUE
vicinity_identifiers	vicinity::vicinity_identifiers()	vicinity	vicinity_identifiers		TRUE
vicinity_mapes	vicinity::vicinity_mapes()	vicinity	vicinity_mapes		TRUE
vicinity_parameters	vicinity::vicinity_parameters()	vicinity	vicinity_parameters		TRUE
vicinity_points	vicinity::vicinity_points()	vicinity	vicinity_points		TRUE
vicinity_processed	vicinity::vicinity_processed()	vicinity	vicinity_processed		TRUE
vicinity_raw	vicinity::vicinity_raw()	vicinity	vicinity_raw		TRUE
vicinity_resolutions	vicinity::vicinity_resolutions()	vicinity	vicinity_resolutions		TRUE
vicinity_templates	vicinity::vicinity_templates()	vicinity	vicinity_templates		TRUE
vicinity_values	vicinity::vicinity_values()	vicinity	vicinity_values		TRUE
youthvars_aqol6d_adol	youthvars::youthvars_aqol6d_adol()	youthvars	youthvars_aqol6d_adol		TRUE
youthvars_chu9d_adolaus	youthvars::youthvars_chu9d_adolaus()	youthvars	youthvars_chu9d_adolaus		TRUE
youthvars_phq9	youthvars::youthvars_phq9()	youthvars	youthvars_phq9		TRUE
youthvars_bads	youthvars::youthvars_bads()	youthvars	youthvars_bads		TRUE
youthvars_gad7	youthvars::youthvars_gad7()	youthvars	youthvars_gad7		TRUE
youthvars_oasis	youthvars::youthvars_oasis()	youthvars	youthvars_oasis		TRUE
youthvars_scared	youthvars::youthvars_scared()	youthvars	youthvars_scared		TRUE
youthvars_k6	youthvars::youthvars_k6()	youthvars	youthvars_k6		TRUE
youthvars_k6_aus	youthvars::youthvars_k6_aus()	youthvars	youthvars_k6_aus		TRUE
youthvars_k10	youthvars::youthvars_k10()	youthvars	youthvars_k10		TRUE
youthvars_k10_aus	youthvars::youthvars_k10_aus()	youthvars	youthvars_k10_aus		TRUE
youthvars_sofas	youthvars::youthvars_sofas()	youthvars	youthvars_sofas		TRUE
YouthvarsDescriptives	youthvars::YouthvarsDescriptives()	youthvars	YouthvarsDescriptives		FALSE
YouthvarsProfile	youthvars::YouthvarsProfile()	youthvars	YouthvarsProfile		FALSE
YouthvarsSeries	youthvars::YouthvarsSeries()	youthvars	YouthvarsSeries		FALSE
MimicAlgorithms	MimicAlgorithms()	mimic	MimicAlgorithms		FALSE
MimicInputs	MimicInputs()	mimic	MimicInputs		FALSE
MimicRepos	MimicRepos()	mimic	MimicRepos		FALSE
MimicConfiguration	MimicConfiguration()	mimic	MimicConfiguration		FALSE

ready4class_constructor is another tibble based ready4 sub-module that summarises the desired features of the ready4 modules and sub-modules that you are authoring. An instance of ready4class_constructor is combined with a ready4fun_manifest sub-module to create a ready4class_manifest sub-module. Instances of ready4class_constructor are most efficiently created using the make_pt_ready4class_constructor function.

y <- make_pt_ready4class_manifest(ready4fun::ready4fun_manifest(),
                                  constructor_r3 = ready4class_constructor()) %>%
  ready4class_manifest()

Typical use

The most important method included in ready4class is the author method for the ready4class_manifest sub-module, that enhances the author method defined for the ready4fun_manifest so that consistently documented R package classes are also generated.

## Not run
author(y)

Examples

ready4class sub-modules and methods are not intended for independent use, but instead should be deployed as part of ready4pack R package authoring workflow.

Future documentation

It should be noted that some ready4class methods require files of a standardised format to be saved in specific sub-directories of the package data-raw directory. Detailed instructions on how to prepare these files are not yet available, but will be outlined in documentation to be released in 2022.

Docs: The role of functional programming in ready4 development

Sat, 24 Dec 2022 00:00:00 +0000

Although the object-oriented programming (OOP) approach ready4 implements has many advantages, it can also have some limitations. Some of these limitations have been colorfully highlighted by a popular quote attributed to Joe Armstrong:

“The problem with object-oriented languages is they’ve got all this implicit environment that they carry around with them. You wanted a banana but what you got was a gorilla holding the banana and the entire jungle.”

In practical terms, this means that if not carefully planned, using OOP can create barriers to code-reuse as algorithms come bundled with artefacts of no/low relevance to many potential users. To help maximise the accessibility and re-usability of ready4 algorithms, these algorithms are primarily written using the functional programming paradigm. Only once an algorithm has been implemented using functions are they then linked to a data-structure by means of a calling method. The typical development workflow for a ready4 computational modelling project might therefore look something the following three step process:

A modelling study algorithm is initially implemented as a program.
To help transfer the methods used in the study algorithm, it is decomposed into functions, which are bundled as a code library (or libraries). The program is updated to use the newly authored functions.
A model module is authored from a template to define a data-structure. A method (or methods) that call the functions authored in the previous step is attached to the module(s) using the ready4 framework’s syntax. The new module is added to the previously created code library and the program is again updated so that the algorithm is now implemented by supplying data to the ready4 module and then calling the desired method(s).

Modellers using ready4 for the most part will only use ready4 modules and will rarely interact directly with the functions that implement module methods. However, these functions are potentially of significant usefulness to coders authoring new algorithms. All ready4 functions are created with minimal, but consistent documentation with the aid of tools from the ready4fun library.

Docs: Authoring model algorithms

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

This below section renders a vignette article from the ready4fun 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)
library(ready4fun)

Motivation

The ready4 framework uses an object-oriented programming (OOP) approach to implement computational health economic models. One motivation for using OOP is the concept of “abstraction” - making things as simple as possible for end-users of ready4 modules by exposing the minimal amount of code required to implement each method.

However, some users of the ready4 modules will want to “look under the hood” and examine the code that implements module algorithms in much more detail. Reasons to do so include to:

gain detailed insight into how methods are implemented;
test individual sub-components of methods as part of code verification and model validation checks;
re-use sub-components of existing methods when authoring new methods.

To help facilitate achieving these objectives, methods associated with ready4 modules can be de-composed into functions that can be used independent of ready4 modules. However, these functions need to be documented and will be easier to comprehend if they adopt a consistent house style (e.g. naming conventions). ready4fun provides workflow tools (classes, methods, functions and datasets) to achieve these goals.

ready4fun function authoring taxonomies, abbreviations and workflow

The ready4fun package uses taxonomy and abbreviation datasets to ensure standardised function code style and documentation.

Function names begin with a meaningful verb

Consistent with a naming convention popular in the R development community, all functions authored with the ready4 framework need to begin with a verb. Furthermore, the choice of verb is meaningful - it communicates something about the type of task a function implements. For example, all functions beginning with the word “fit” will fit a model of a specified type to a dataset. The definitions of all meaningful verbs used in functions authored for a ready4 framework model implementation can be retrieved using get_fn_types(), which by default returns a dataset instance of the ready4fun_functions submodule.

x <- get_fn_types(gh_repo_1L_chr = "ready4-dev/ready4")
class(x)
#> [1] "ready4fun_functions" "tbl_df"              "tbl"                 "data.frame"

exhibit(x,select_int = 1:2, scroll_box_args_ls = list(width = "100%"))

Meaningful verbs
Verb	Description
Add	Updates an object by adding new values to new or empty fields.
Assert	Validates that an object conforms to required condition(s). If the object does not meet all required conditions, program execution will be stopped and an error message provided.
Bind	Binds two objects together to create a composite object.
Calculate	Performs a numeric calculation.
Close	Closes specified connections.
Fit	Fits a model of a specified type to a dataset.
Force	Checks if a specified local or global environmental condition is met and if not, updates the specified environment to comply with the condition.
Format	Modifies the format of an object.
Get	Extracts data from an object.
Import	Reads a data object in its native format and converts it to an R object.
Impute	Imputes data.
Knit	Knits an RMD or Rmarkdown file.
Launch	Launches an R Shiny app.
Make	Creates a new R object.
Plot	Plots data.
Predict	Applies a model to make predictions.
Print	Prints output to console.
Randomise	Randomly samples from data.
Read	Reads an R script into memory.
Remove	Edits an object, removing a specified element or elements.
Rename	Renames elements of an object based on a pre-specified schema.
Reorder	Reorders an object to conform to a pre-specified schema.
Replace	Edits an object, replacing a specified element with another specified element.
Reset	Edits an object, overwriting the current version with a default version.
Rowbind	Performs custom rowbind operations on table objects.
Scramble	Randomly reorders an object.
Transform	Edits an object in such a way that core object attributes - e.g. shape, dimensions, elements, type - are altered.
Unload	Performs a custom detaching of a package from the search path.
Update	Edits an object, while preserving core object attributes.
Validate	Validates that an object conforms to required criteria.
Write	Writes a file to a specified local directory.

Function inputs and outputs have meaningful suffices

The type of input (arguments) required and output (return) produced by a function can be efficiently communicated by using meaningful suffices. For example all objects ending in “_chr” are character vectors and all objects ending in “_int” are integer vectors. Definitions of all meaningful suffices used in functions authored for a ready4 framework model implementation can be retrieved using get_obj_types(), which by default returns a dataset instance of the ready4fun_objects submodule.

y <- get_obj_types(gh_repo_1L_chr = "ready4-dev/ready4")
class(y)
#> [1] "ready4fun_objects" "tbl_df"            "tbl"               "data.frame"

exhibit(y, select_int = 1:2, scroll_box_args_ls = list(width = "100%"))

Meaningful suffices
Suffix	Description
arr	array
chr	character
dbl	double
df	data.frame
dtm	date
env	environment
fct	factor
fn	function
int	integer
lgl	logical
ls	list
lup	lookup table
mat	matrix
mdl	model
plt	plot
prsn	person
r3	ready4 submodule
r4	ready4 module
rgx	regular expression
s3	S3
s4	S4
sf	simple features object
tb	tibble
tsb	tsibble

Consistent use of abbreviations

Further information about the purpose of a function and the nature of its inputs and outputs can be encoded by using naming conventions that make consistent use of abbreviations. A master table of the abbreviations used in a ready4 framework model implementation can be retrieved using get_abbrs(), which by default returns a dataset instance of the ready4fun_abbreviations submodule.

z <- get_abbrs(gh_repo_1L_chr = "ready4-dev/ready4")
class(z)
#> [1] "ready4fun_abbreviations" "tbl_df"                  "tbl"                     "data.frame"

exhibit(z %>% head(50), select_int = 1:2, scroll_box_args_ls = list(width = "100%"))

Abbreviations
Abbreviation	Description
...	additional arguments
1L	length one
1L_chr	character vector of length one
1L_chr_ls	list of character vectors of length one
1L_dbl	double vector of length one
1L_dbl_ls	list of double vectors of length one
1L_dtm	date vector of length one
1L_dtm_ls	list of date vectors of length one
1L_fct	factor vector of length one
1L_fct_ls	list of factor vectors of length one
1L_int	integer vector of length one
1L_int_ls	list of integer vectors of length one
1L_lgl	logical vector of length one
1L_lgl_ls	list of logical vectors of length one
1L_rgx	regular expression vector of length one
1L_rgx_ls	list of regular expression vectors of length one
1Ls	length ones
8d	8 Dimension
8ds	8 Dimensions
AusACT	Meta data for processing ACT population projections.
AusHeadspace	Meta data for constructing Headspace Centre geometries.
AusLookup	Lookup tables for Australian geometry and spatial attribute data.
AusOrygen	Meta data for constructing OYH Specialist Mental Health Catchment geometries.
AusProjections	Meta data for constructing custom Australian population projections boundary.
AusTasmania	Meta data for processing Tasmanian population projections.
CostlyCorrespondences	Collection of input, standards definition and results datasets for projects to generate standardised costing datasets.
CostlyCountries	Collection of input, standards definition and results datasets for projects to generate standardised country data for use in costing datasets.
CostlyCurrencies	Collection of input, standards definition and results datasets for projects to generate standardised currency data for use in costing datasets.
CostlySeed	Original (non-standardised) dataset (and metadata).
CostlySource	Input dataset (and metadata) for generating standardised costing datasets.
CostlyStandards	Dataset (and metadata) defining the allowable values of specified variables.
MimicAlgorithms	The core set of functions that define simulation behaviour.
MimicConfiguration	Configuration details for a simulation run.
MimicInputs	Model input data (regression models, population and parameters).
MimicRepos	Local and remote repositories for model input and output data.
OLS	ordinary least squares
OOS	occasion of service
OOSs	occasion of services
Ready4showPaths	Metadata about paths to Markdown input and output
Ready4showSynopsis	Metadata about a scientific summary manuscript.
Ready4useArguments	ready4 module class containing data to be passed to a function that constructs a spatial object from a lookup table.
Ready4useDyad	A dataset and data dictionary pair.
Ready4useFiles	ready4 module class defining data to be saved in local directory.
Ready4useIngest	Ingested data and descriptive metadata.
Ready4usePointer	Metadata on local and remote data storage locations.
Ready4useProcessed	ready4 module class defining data to be saved in local directory in a processed (R) format.
Ready4useRaw	ready4 module class defining data to be saved in local directory in a raw (unprocessed) format.
Ready4useRecord	Ingested data, descriptive metadata and provenance details.
Ready4useRepos	Metadata about online data repositories.
ScorzAqol6	A dataset and the required information to implement an AQoL-6D scoring algorithm.

The ready4fun_abbreviations submodule is searchable. It is therefore possible to see if an abbreviation has been defined for an existing word or phrase…

procure(z,"template")
#> # A tibble: 2 × 3
#>   short_name_chr long_name_chr plural_lgl
#>   <chr>          <chr>         <lgl>     
#> 1 tmpl           template      FALSE     
#> 2 tmpls          templates     TRUE

…and to look-up the meaning of an abbreviation…

procure(z,"org",type_1L_chr = "extension")
#> # A tibble: 2 × 3
#>   short_name_chr long_name_chr plural_lgl
#>   <chr>          <chr>         <lgl>     
#> 1 org            organisation  FALSE     
#> 2 orgs           organisations TRUE

…or whether a potential abbreviation has already been defined.

procure(z,"org", type_1L_chr = "extension", what_1L_chr = "string")
#> [1] "org"  "orgs"

Workflow

Manifest

The main class exported as part of ready4fun is the ready4 sub-module ready4fun_manifest which is used to specify metadata (including details of the repository in which the fn_types_lup, seed_obj_lup_tb and abbreviations_lup objects are stored) for the functions being authored and the R package that will contain them.

x <- ready4fun_manifest()

Typical Usage

A ready4fun_manifest object is most efficiently created with the aid of the make_pkg_desc_ls and make_manifest functions rather than a direct call to the ready4fun_manifest() function.

## Not run
x <- ready4fun::make_pkg_desc_ls(
  pkg_title_1L_chr = "Your Package Title",
  pkg_desc_1L_chr = "Your Package Description.",
  authors_prsn = c(
    utils::person("Author 1 Name",
      role = c("aut", "cre")
    ),
    utils::person("Author 2 Name", role = c("cph"))
  ),
  urls_chr = c(
    "Package website url",
    "Package source code url",
    "Project website"
  )
) %>%
  ready4fun::make_manifest(
    copyright_holders_chr = "Organisation name",
    custom_dmt_ls = ready4fun::make_custom_dmt_ls(user_manual_fns_chr = c("Functions to be included in main user manual are itemised here")),
    dev_pkgs_chr = c("Any development package dependencies go here"),
    path_to_pkg_logo_1L_chr = "Local path to package logo goes here",
    piggyback_to_1L_chr = "GitHub Release Repository to which supporting files will be uploaded",
    ready4_type_1L_chr = "authoring",
    zenodo_badge_1L_chr = "DOI badge details go here"
  )

The main method defined for ready4fun_manifest is author which, assuming the raw undocumented function files are saved in the appropriate directories, will author an R package in which all functions are consistently documented.

## Not run
author(x)

Examples

The ready4fun_manifest sub-module and its methods along with the make_pkg_desc_ls and make_manifestfunctions are designed to be used as part of the ready4pack R package authoring workflow. That vignette includes links to two examples of where the ready4pack workflow has been used to author R package. To illustrate how readyfun tools used as part of that workflow are used to document functions, we are just going to focus on the program used to create the ready4show package.

That program makes use of ready4fun tools that read all undocumented package functions, performs automated checks to ensure that these functions appropriately use the taxonomies and abbreviations mentioned previously (prompting authors to make specific amendments if they do not) and then rewrites these functions to the package R directory, appending tags (with the aid of the sinew package) that will generate meaningful documentation.

For example, one of the functions to be documented is the knit_from_tmpl, which is transformed to a version with tags. The tags added to all functions are then used to generate the package documentation, including the package manual. Two versions of the ready4show package manual are generated - a slimmed down version for end-users and a more detailed inventory of contents intended for developers.

Future documentation

Detailed guidance for how to apply ready4fun workflow tools has yet to be prepared but is planned for 2024.

Docs: Dissemating citable, documented and quality assured model module libraries

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

This below section renders a vignette article from the ready4pack 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)
library(ready4fun)
library(ready4class)
library(ready4pack)

ready4pack is a toolkit for bundling collections of modules for computational health economic models authored with the ready4 framework as R packages that are:

Citable (with a Zenodo generated DOI and an algorithm generated CITATION file);
Community-minded (applying deprecation conventions supported by lifecycle);
Documented (applying a function self-documenting algorithm that extends sinew, deploying a GitHub pages hosted and pkgdown generated website and authoring PDF manuals stored in a GitHub Release via piggyback);
Internally consistent implementing automated checks to ensure consistency in naming conventions, etc;
Licensed (via a usethis generated GPL-3 license);
Quality assured (using continuous integration via GitHub actions and R-CMD-Check); and
Versioned (applying usethis version increments).

ready4pack extends ready4 framework tools for authoring module algorithms (ready4fun) and data structures (ready4class) and wraps functions from a number of third party R development workflow tools (such as devtools). ready4pack integrates these tools in a common workflow, while adding tools for authoring and documenting datasets to be shipped with model module R packages.

A combination of the ready4_pack_manifest class and author method are used to implement this workflow. This workflow has been used to author all public versions of the ready4 R packages available in the ready4 github repository.

Workflow

Manifest

The main class exported as part of ready4pack is readypack_manifest list based ready4 sub-module, that extends the ready4fun_manifest and ready4class_manifest sub-modules.

Typical usage

readypack_manifest sub-module is most efficiently created with the aid of the make_pt_ready4pack_manifest function and combines instances of the ready4fun_manifest and ready4class_constructor sub-modules.

x <- make_pt_ready4pack_manifest(ready4fun::ready4fun_manifest(),
                                 constructor_r3 = ready4class::ready4class_constructor()) %>%
  ready4pack_manifest()

The main method defined for readypack_manifest is author which extends the author method for ready4class_manifest to author a consistently documented R package.

## Not run
author(x)

Examples

Workflow example one

The program to author and document the ready4show package is relatively simple and authors:

the ready4show package CITATION, DESCRIPTION, LICENSE and README files;
all files in the ready4show package R directory;
the ready4show package website;
two versions of the ready4show package manual - a slimmed down version for end-users and a more detailed inventory of contents intended for developers;
an initial ready4show release for hosting supporting files, the creation of which will trigger archiving on Zenodo with a ready4show package DOI; and
an R-CMD-check continuous integration algorithm to be implemented each time a new version of ready4show is pushed to the main branch of the GitHub source code repository.

Workflow example two

The program to author and document the youthvars package is a bit more complex as it includes syntax to create package datasets. In addition to the package datasets, the algorithm creates content corresponding to the previous example, specifically:

the youthvars package CITATION, DESCRIPTION, LICENSE and README files;
all files in the youthvars package R directory;
the youthvars package website;
two versions of the youthvars package manual - a slimmed down version for end-users and a more detailed inventory of contents intended for developers;
an initial youthvars release for hosting supporting files, the creation of which will trigger archiving on Zenodo with a youthvars package DOI; and
an R-CMD-check continuous integration algorithm to be implemented each time a new version of youthvars is pushed to the main branch of the GitHub source code repository.

Future documentation

A more detailed guide to using ready4pack will be created in 2023.

Docs: Model

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

Docs: Model modules

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

Docs: Finding and using open access data

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