This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Code libraries

The ready4 framework is distributed as six R libraries.

1: Framework library descriptions
2: Library documentation

3: Dependencies

4: Installation and set-up

4.1: Installing the ready4 framework foundation library
4.2: Installing authoring tools

4.2.1: Installing tools for authoring computational models
4.2.2: Installing tools for authoring and managing model datasets
4.2.3: Installing tools for authoring reproducible analyses

4.3: Installing ready4 computational model modules

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

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.

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