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.

2 - System requirements

What you need in order to be able to use ready4 software on your machine.

Currently, all ready4 software is written in R (for libraries), R Markdown (for programs and sub-routines) and JavaScript (for the user interface component of Shiny applications). Therefore:

to use ready4 libraries and programs / subroutines you must have an up to date version of R installed on your machine and it is recommended that you install the RStudio IDE; and
the requirements for using ready4 user interfaces depend on whether you are running a version we have deployed to the web (in which case you just need a supported browser) or whether you are running the app on your local machine (in which case you will need both R and RStudio).

3 - Release statuses

Whether and how you should use a specific version of ready4 software depends in part on its release status.

3.1 - Unreleased code

Some work in progress code has yet to be publicly released or fornmally acknowledged as part of the ready4 suite.

Currently, a new ready4 software project initiated by the ready4 core team will by default be made public as a pre-release version in the ready4 GitHub organisation. However, there are some important exceptions. Principally, these exceptions relate to code that we authored in the initial phase of ready4’s development to which some or all of the following apply:

the code is highly unstable because it has not been (fully) updated to account to major changes implemented in core dependencies;
the code uses outdated naming conventions and is potentially confusing when used in conjunction with other elements of the ready4 suite; and/or
the code repository has yet to be cleansed of artefacts that are not yet appropriate for public dissemination (e.g. renders of draft scientific manuscripts).

Depending on which of the above issues apply to a code repository, that repository will either be:

a private repository (not accessible to anyone outside the core development team); or
a public repository stored in a location other than the ready4 GitHub organisation.

3.2 - Development releases

Development releases provide the most comprehensive and up to date public record of a ready4 project’s source code but may be poorly documented and tested.

A complete record of all publicly available versions of a ready4 software project’s code over its entire development history (including the most up to date version) is stored in the ready4 GitHub organisation. We refer to these comprehensive publicly available source code resources as “development releases” (even though these records will include versions of our code that we have not formally labelled as “releases”).

Public access to development releases allows individuals to install, test and preview code in advance of production versions being released. Development releases also provide transparency as to who contributed what to a software project and when these contributions were made. Accessing the latest development version of the code is particularly useful to people who wish to contribute bug fixes or new features to our code.

Limitations of development releases include the likelihood that some or all of this code may be inadequately documented or tested. In peer reviewed publications, it is generally considered preferable to avoid citing the copies of code stored in GitHub repositories as these repositories are impermanent (they can be moved, renamed or deleted at any time).

3.3 - Production releases

Production releases are the versions of software intended for end-users.

Production releases of our code are intended for end-users and signal that they have undergone a number of quality assurance checks and have some supporting documentation.

Production releases of ready4 R packages will be submitted to CRAN. Unless and until a software item is submitted to a production code repository like CRAN, the recommended platform from which to install our software is that software’s GitHub repository.

Currently only one ready library is available on CRAN.

3.4 - Archived releases

Archived releases are permanent, uniquely identified records of key project milestones.

Software items that we have formally issued as “releases” are archived as permanent, uniquely identified (with DOI) and citable records within the ready4 Zenodo community. Archived releases of ready4 software are useful as they are snapshots of a project at key milestones in its development (e.g. at the time an analysis was undertaken). As these milestones are purposely selected, archived releases are more likely to have undergone some testing and documenting prior to being released than code not selected for release.

A limitation of archived code libraries is that a greater knowledge of R is required to appropriately install R packages from Zenodo compared to the simpler installation process for the versions of code libraries stored on either GitHub or CRAN.

4 - Code libraries

The ready4 framework is distributed as six R libraries.

4.1 - Framework library descriptions

There are two types of framework libraries - a foundational library and libraries of authoring tools.

The two types of framework library are:

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

Currently available framework libraries are summarised below.

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

4.2 - Library documentation

Each ready4 code library is supported by a standardised set of documentation resources.

All ready4 code libraries have:

a website, the URL of which typically takes the form of "https://ready4-dev.github.io/PACKAGE_NAME" (for example the website for the foundational ready4 R package is https://ready4-dev.github.io/ready4 );
a brief PDF manual itemising the subset of classes, methods and functions that will be of interest to most end users, the URL of which takes the form of "https://github.com/ready4-dev/PACKAGE_NAME/releases/download/Documentation_0.0/PACKAGE_NAME_User.pdf" (for example, https://github.com/ready4-dev/ready4/releases/download/Documentation_0.0/ready4_User.pdf);
a more comprehensive PDF manual itemising all included classes, methods and functions, including those that may only be of interest to developers of ready4 libraries, the URL of which takes the form of "https://github.com/ready4-dev/PACKAGE_NAME/releases/download/Documentation_0.0/PACKAGE_NAME_Developer.pdf" (for example, https://github.com/ready4-dev/ready4/releases/download/Documentation_0.0/ready4_Developer.pdf); and
a publicly accessible record of the results of all continuous integration checks performed on each version of the source code, the url of which takes the form of "https://github.com/ready4-dev/PACKAGE_NAME/actions" (for example, https://github.com/ready4-dev/ready4/actions).

All ready4 code libraries include interactive help. Once you have installed and loaded a library, you can view its contents by using the command library(help="PACKAGE_NAME") (for example, library(help="ready4")).

Note that the manuals and files used by the interactive help are currently all automatically authored by tools from our ready4fun package and are therefore quite basic (and in some cases use clumsy English). In the future we hope to augment this machine generated documentation with human-authored documentation.

Most ready4 libraries (the exceptions are those at very early stages of development) have one or more vignette articles that provide examples of how to use it. These are available from the “Articles” section of each library’s website.

4.3 - Dependencies

Search for ready4 library and function dependencies using our interactive app.

As an open-source project, ready4 depends on the software created and shared by others. Using the DependenciesGraphs R package, we have created the Shiny app below to:

explore the inter-dependencies between ready4 libraries;
highlight how our software depends on other R packages;
itemise the contents each ready4 library;
display function help files; and
map function inter-dependencies across multiple ready4 libraries.

To use the app, choose one of the two potential pathways:

For Pathway 1, start at Step 1 (choose the libraries you wish to profile from the drop down menu and click on the Go button), before proceeding to Step 2 (click on one library that you wish to view the contents of), then Step 3 (click on the view functions button) and finally Step 4 (click on the function for which you would like to view documentation);
For Pathway 2, start at Step 1 (choose libraries from the drop down menu), then Step 2 (click on the Find functions button), then Step 3 (select functions from the drop down menu) and finally Step 4 (click on the Make graph button).

Note, as the app is displayed on this page via an iFrame, it may be difficult to view on a phone. If so, you can try the following link: https://orygen.shinyapps.io/dependencies/

4.4 - Installation and set-up

Important information to review before installing and using our software

Most (but not all) of the libraries that comprise the ready4 framework are currently only available as development releases. For these libraries, you will need to use a tool like devtools to install the library directly from our GitHub organisation. If you do not have devtools on your machine you can install it with the following command.

utils::install.packages("devtools")

4.4.1 - Installing the ready4 framework foundation library

The ready4 framework foundation is the first ready4 library you should install.

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.

4.4.2 - Installing authoring tools

Depending on how you plan to use ready4, you may need to install some or all of its authoring tools.

4.4.2.1 - Installing tools for authoring computational models

Instructions for installing the ready4class, ready4fun and ready4pack libraries.

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.

4.4.2.2 - Installing tools for authoring and managing model datasets

Instructions for installing the ready4use library.

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.

4.4.2.3 - Installing tools for authoring reproducible analyses

Instructions for installing the ready4show library.

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.

4.4.3 - Installing ready4 computational model modules

To implement a modelling analysis with ready4 you need to install computational model modules.

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/).

5 - Terms of use

ready4 is distributed without warranties under open source licenses - we just ask you to appropriately cite it.

5.1 - Open source licensing

ready4 is freely available to all under copy-left licensing arrangements.

To help ensure the models we develop are as transparent as possible and to make their algorithms as useful to others as possible, all ready4 software is free and open-source. You are encouraged to make as widespread use of our software, including the creation of derivative works, as you see fit, so long as it is consistent with each item’s license. Our software is typically licensed under GPL-3, a copy-left open-source licensing regime.

5.2 - Citing ready4

If you find ready4 useful, please cite it appropriately - it is easy to do!

To make it easier to cite our software, each software item bundle includes a CITATION.cff file. Inclusion of this file means that the repositories storing our software can generate appropriate citations in the format of most relevance to you.

Currently:

Zenodo provides a free text field under the heading “Cite as” which enables you to generate a wide range of citation manager and journal specific citation outputs. There is also an “Export” tool that will generate citation metadata in multiple output formats;
OpenAire Explore has a “Cite this software” button that allows you to generate a citation in multiple journal formats or to download BibTeX or RIS files;
Github repositories have a “Cite this repository” button that can generate both BibTeX and APA output as well as link to the Citation.cff file.

Additionally, we have included a CITATION file in each of our R libraries so that you can generate a citation from within an R session using the citation function (for example: citation("ready4").

5.3 - Disclaimer

ready4 is distributed without any warranties.

All ready4 software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Furthermore, no ready4 software is yet sufficiently well documented and tested to be given a production release. All ready4 software should therefore viewed as experimental development releases.