Blog: Framework taxonomies dataset releases

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

Releases of the datasets of the taxonomies that support a consistent code house-style and automation of documentation autoring are described below.

Date	Dataset	Version	Number of files
23-Dec-2022	ready4 Framework Abbreviations and Definitions	3.0	1
25-May-2022	ready4 Framework Abbreviations and Definitions	2.1	1
14-Jan-2022	ready4 Framework Abbreviations and Definitions	2.0	1
14-Jan-2022	ready4 Framework Abbreviations and Definitions	1.0	1

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.

ready4 – Framework - conventions