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

Return to the regular view of this page.

Executables

Executables (programs and sub-routines) are used to apply computational models to data and to report the resulting analyses.

Currently all ready4 programs and subroutines are written in R Markdown. Each ready4 program and subroutine depends on at least one ready4 framework library as well as one or more ready4 module libraries. The required libraries will vary based on the purpose of the program. ready4 programs and subroutines typically generate reporting documents in file formats such as PDF, Word and HTML.

1 - Programs

Programs are used to generate and report a model analysis.

What are ready4 programs?

Programs can be executed in their current form without the need for additional input data and, unless modified or run interactively (prompting a user for inputs during execution), will always generate the exact same output. They are typically deployed for configuring the run specifications of a computational model, specifying the data to which it will be applied and reporting analysis results.

Why are they useful?

ready4 programs can be used for the following purposes:

  • to reproduce a study analysis, in which case you will need access to the original study data, and may also need to modify the program to specify the path to this data from your machine;
  • to replicate a study analysis (ie to apply the study algorithm to similar but different input data [this can be a new sample from the same population or, if used for demonstration purposes, fake data representative of the original study dataset]), in which case you will need to modify the program to specify the path to this data; and
  • to transfer a study analysis, in which case you use the program as a template to be modified to reflect key differences between the original study and your study.

Current ready4 programs

Currently available ready4 programs are summarised in the below table.

Program Release Date Description Source
aqol6dmap_fakes 0.0.9.0 02-Mar-2022 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. Dev, Archive
aqol6dmap_use 0.1 13-Sep-2022 Apply AQoL-6D Utility Mapping Models To New DataThis release includes minor formatting change and an updated version number. Dev, Archive
dce_sa_analysis 0.1.1 27-Oct-2022 A self-documenting R Markdown program for analysing responses to a discrete choice experiment exploring the online help-seeking preferences of socially anxious young people. Dev, Archive
dce_sa_design 0.0.9.3 26-Oct-2022 An R Markdown program to create the experimental design for a Discrete Choice Experiment (DCE) exploring online help seeking in socially anxious young people.This release uses functions from the mychoice R package (https://github.com/ready4-dev/mychoice). Dev, Archive
ttu_lng_aqol6_csp 0.1 16-Sep-2022 Complete study program to reproduce all steps from data ingest through to results dissemination for a study to map mental health measures to AQoL-6D health utility. Dev, Archive

Documentation

ready4 programs are typically self-documenting, meaning that each section of code is integrated with plain English descriptions of the purpose it fulfills. The only programs that are not self-documenting are those whose primary purpose is to produce a document (normally an analysis report). Self-documenting programs and sub-routines will be typically documented as a PDF or HTML render of the RMarkdown source file. This rendered document will be bundled with the program, but in some cases may also be shared in online data repositories.

2 - Subroutines

Subroutines perform part of an analysis and reporting algorithm.

What are ready4 subroutines?

Sub-routines need to be called by parent programs that supply them with input data. Sub-routines can be called by multiple programs and will produce output that varies based on the input values they are supplied with. They are typically deployed to implement parts of a model’s analysis and reporting algorithm.

Why are they useful?

ready4 subroutines can be used for the following purposes:

  • to help execute a program or function written by a third party (in which case you probably won’t need to modify the subroutine and may not even be aware that it is being used);
  • to help execute a program or function that you write (in which case, you shouldn’t have to modify the subroutine, but may find it useful to customise it to your purposes); and
  • to serve as a template for subroutines you write yourself that perform similar tasks (in which case you will be rewriting the subroutine’s code).

Current ready4 subroutines

Currently available ready4 subroutines are summarised in the below table.

Subroutine Release Date Description Source
ms_tmpl 0.1.1.0 19-Apr-2022 A collection of files to provide a template for generating scientific manuscripts describing open source mental health systems models projects that use the ready4 framework.This release is a minor patch to correct an incorrectly specified version number. Dev , Archive
mychoice_results 0.1 07-Nov-2022 Report results from a Discrete Choice Experiment implemented with the mychoice R package. Dev, Archive
ttu_lng_ss 0.9.0.1 23-Jun-2023 This sub-routine program extends the R package TTU by providing a toolkit for automatically authoring a first draft of a scientific manuscript from results generated by TTU modules. The program is intended for use and as the last component of TTU’s reporting workflow for utility mapping modelling projects. An example of this workflow is available at: https://doi.org/10.5281/zenodo.6116077 . This program generalises a program that produced the manuscript for a real world study (https://doi.org/10.1101/2021.07.07.21260129). The program can produce manuscripts in PDF / LaTex (example - https://dataverse.harvard.edu/api/access/datafile/4957407) and Word (example - https://dataverse.harvard.edu/api/access/datafile/4957416). It should be noted that the Word output requires some manual editing to adapt section numbering, modify table headers and resize tables to page boundaries.This release fixes a bug that prevented the previous version from rendering. Dev , Archive
ttu_mdl_ctlg 0.1.0.1 18-Jul-2023 A reporting template for utility mapping models created using the TTU package (https://ready4-dev.github.io/TTU/index.html). This release includes minor bug fixes. Dev, Archive

Documentation

ready4 programs are currently minimally documented, typically in the form as notes contained in a README file in the source code bundle.