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

Return to the regular view of this page.

Code libraries

Code libraries are used to distribute our software framework and modules of our computational model.

1 - Current libraries

ready4 libraries include tools for applying a modelling framework and for implementing computational models.

1.1 - Framework libraries

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.



Type Package Purpose Documentation Code Examples
Implement Transparent, Reusable and Updatable Computational Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 1, 2, 3, 4
Retrieve, Label and Share Model Datasets Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 5, 6, 7
Author Literate Programs to Implement and Report Modelling Analyses Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 8
Author R Packages of Ready4 Model Modules Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 9
Author and Document Functions to Implement Ready4 Algorithms Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 10
Author Ready4 Model Modules Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev, Archive 11

1.2 - Model module libraries

There are three types of model module libraries - those for describing input data, developing models and making predictions.

Computational models developed with ready4 are intended to be both transferable (they are tools that can be used in multiple decision contexts) and modular (they are comprised of self-contained components, each of which performs a narrow sub-set of tasks). For these reasons, ready4 computational models are developed and distributed as libraries of modules.

The three types of ready4 module libraries are:

  • - modules for describing and quality assuring model data;

  • - modules to specify, assess and report statisitical models; and

  • - modules for making predictions.

A table summarising currently available module libraries can be generated by using the make_libraries_tb function from the ready4 framework library.

library(ready4)
libraries_tb <- make_libraries_tb("modules")

Module libraries are thematically grouped under one of four “sections” of the ready4 model, one each for modelling People, Places, Platforms and Programs. We can use the print_packages function to display the module libraries currently available for each section (currently, there are no publicly available libraries of ready4 modules for modelling platforms).

Module libraries for modelling people

print_packages(libraries_tb %>% dplyr::filter(Section == "People"),
               include_1L_chr = "modules")
Type Package Purpose Documentation Code Examples
Describe and Validate Person Records for Use in Youth Mental Health Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 1, 2
Score Multi-Attribute Instruments Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 3, 4
Model Youth Choice Behaviours with Ready4 Citation , Website , Citation Dev , Archive
Implement Transfer to Utility Mapping Algorithms Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 5
Explore and Characterise Heterogeneity in Quality of Life Data Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive
Specify Models to Solve Inverse Problems Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 6
Transform Youth Outcomes to Health Utility Predictions with Ready4 Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive 7

Module libraries for modelling places

print_packages(libraries_tb %>% dplyr::filter(Section == "Places"),
               include_1L_chr = "modules")
Type Package Purpose Documentation Code Examples
Model Australian Spatial Data with Ready4 Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive
Model Spatial Attributes with Ready4 Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive

Module libraries for modelling programs

print_packages(libraries_tb %>% dplyr::filter(Section == "Programs") %>%
                 dplyr::mutate(Type = "Modelling (affordability)"),
               include_1L_chr = "modules")
Type Package Purpose Documentation Code Examples
Undertake Budget Impact Analysis using Open, Modulal Mental Health Citation , Website , Manual - Short (PDF) , Manual - Full (PDF) Dev , Archive

2 - Code library documentation

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

All ready4 code libraries have:

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

ready4 libraries are currently only available as development releases, so you will need to use a tool like devtools to assist with installing ready4 R packages 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.

However, please note that the ready4 library 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.

As all software in the ready4 suite depends on the ready4 library, so 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 directly from its GitHub repository.

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