ready4 – Author and share model modules

Docs: Authoring model data structures

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

This below section renders a vignette article from the ready4class 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(ready4class)
library(ready4show)
library(ready4use)

Motivation

The ready4 framework uses object oriented programming (OOP) to implement modular approaches to computational models of mental health systems. That means that a standardised approach to developing modules (S4 classes) and sub-modules (S3 classes) is required. ready4class provides the tools to implement this workflow.

Workflow

Prototyes, constructor and manifest

The main classes exported as part of ready4class are readyclass_manifest and ready4class_constructor. ready4class_pt_lup is a tibble based ready4 sub-module, which contains metadata on the prototypes of classes that can be used as sub-components of ready4 modules and sub-modules (for example a tibble based class can be used as a slot in an S4 class). When authoring ready4 R packages, you will create a ready4class_pt_lup instance and store it in an online repository that you have write permissions to. As you create new ready4 modules and sub-modules using ready4class tools, your ready4class_pt_lup object will be updated so that these classes can be made available to any future modules or sub-modules that you author. The ready4class_pt_lup sub-module recently used in workflows for authoring ready4 modules is reproduced below.

x <- ready4use::Ready4useRepos(gh_repo_1L_chr = "ready4-dev/ready4",
                               gh_tag_1L_chr = "Documentation_0.0") %>%
  ingest(fls_to_ingest_chr = "prototype_lup",
         metadata_1L_lgl = F) 
x %>%
  exhibit(scroll_box_args_ls = list(width = "100%"))

Class Prototypes Lookup Table
Class	Value	Namespace	Function	Default	Is Old Class
AusACT	aus::AusACT()	aus	AusACT		FALSE
AusHeadspace	aus::AusHeadspace()	aus	AusHeadspace		FALSE
AusLookup	aus::AusLookup()	aus	AusLookup		FALSE
AusOrygen	aus::AusOrygen()	aus	AusOrygen		FALSE
AusProjections	aus::AusProjections()	aus	AusProjections		FALSE
AusTasmania	aus::AusTasmania()	aus	AusTasmania		FALSE
POSIXt	.POSIXct(NA_character\_)	base	.POSIXct	NA_character\_	FALSE
character	NA_character\_	base		NA_character\_	FALSE
data.frame	data.frame()	base		data.frame()	FALSE
integer	NA_integer\_	base		NA_integer\_	FALSE
list	list(list())	base	list	list()	FALSE
logical	NA	base		NA	FALSE
numeric	NA_real\_	base		NA_real\_	FALSE
function	function() NULL	base		function() NULL	FALSE
CostlyCorrespondences	costly::CostlyCorrespondences()	costly	CostlyCorrespondences		FALSE
CostlyCountries	costly::CostlyCountries()	costly	CostlyCountries		FALSE
CostlyCurrencies	costly::CostlyCurrencies()	costly	CostlyCurrencies		FALSE
CostlySeed	costly::CostlySeed()	costly	CostlySeed		FALSE
CostlySource	costly::CostlySource()	costly	CostlySource		FALSE
CostlyStandards	costly::CostlyStandards()	costly	CostlyStandards		FALSE
dfidx	dfidx::dfidx(dfidx())	dfidx	dfidx	dfidx()	FALSE
Period	lubridate::period()	lubridate	period		FALSE
Ready4Module	ready4::Ready4Module()	ready4	Ready4Module		FALSE
Ready4Private	ready4::Ready4Private()	ready4	Ready4Private		FALSE
Ready4Project	ready4::Ready4Project()	ready4	Ready4Project		FALSE
Ready4Public	ready4::Ready4Public()	ready4	Ready4Public		FALSE
ready4class_constructor	ready4class::ready4class_constructor()	ready4class	ready4class_constructor		TRUE
ready4class_manifest	ready4class::ready4class_manifest()	ready4class	ready4class_manifest		TRUE
ready4class_pt_lup	ready4class::ready4class_pt_lup()	ready4class	ready4class_pt_lup		TRUE
ready4fun_abbreviations	ready4fun::ready4fun_abbreviations()	ready4fun	ready4fun_abbreviations		TRUE
ready4fun_badges	ready4fun::ready4fun_badges()	ready4fun	ready4fun_badges		TRUE
ready4fun_dataset	ready4fun::ready4fun_dataset()	ready4fun	ready4fun_dataset		TRUE
ready4fun_description	ready4fun::ready4fun_description()	ready4fun	ready4fun_description		TRUE
ready4fun_executor	ready4fun::ready4fun_executor()	ready4fun	ready4fun_executor		TRUE
ready4fun_functions	ready4fun::ready4fun_functions()	ready4fun	ready4fun_functions		TRUE
ready4fun_manifest	ready4fun::ready4fun_manifest()	ready4fun	ready4fun_manifest		TRUE
ready4fun_metadata_a	ready4fun::ready4fun_metadata_a()	ready4fun	ready4fun_metadata_a		TRUE
ready4fun_metadata_b	ready4fun::ready4fun_metadata_b()	ready4fun	ready4fun_metadata_b		TRUE
ready4fun_objects	ready4fun::ready4fun_objects()	ready4fun	ready4fun_objects		TRUE
ready4pack_manifest	ready4pack::ready4pack_manifest()	ready4pack	ready4pack_manifest		TRUE
ready4show_authors	ready4show::ready4show_authors()	ready4show	ready4show_authors		TRUE
ready4show_institutes	ready4show::ready4show_institutes()	ready4show	ready4show_institutes		TRUE
ready4show_correspondences	ready4show::ready4show_correspondences()	ready4show	ready4show_correspondences		TRUE
Ready4showPaths	ready4show::Ready4showPaths()	ready4show	Ready4showPaths		FALSE
Ready4showSynopsis	ready4show::Ready4showSynopsis()	ready4show	Ready4showSynopsis		FALSE
ready4use_distributions	ready4use::ready4use_distributions()	ready4use	ready4use_distributions		TRUE
ready4use_dataverses	ready4use::ready4use_dataverses()	ready4use	ready4use_dataverses		TRUE
ready4use_imports	ready4use::ready4use_imports()	ready4use	ready4use_imports		TRUE
ready4use_mapes	ready4use::ready4use_mapes()	ready4use	ready4use_mapes		TRUE
ready4use_dictionary	ready4use::ready4use_dictionary()	ready4use	ready4use_dictionary		TRUE
Ready4useFiles	ready4use::Ready4useFiles()	ready4use	Ready4useFiles		FALSE
Ready4useRaw	ready4use::Ready4useRaw()	ready4use	Ready4useRaw		FALSE
Ready4useProcessed	ready4use::Ready4useProcessed()	ready4use	Ready4useProcessed		FALSE
Ready4useArguments	ready4use::Ready4useArguments()	ready4use	Ready4useArguments		FALSE
Ready4useDyad	ready4use::Ready4useDyad()	ready4use	Ready4useDyad		FALSE
Ready4useIngest	ready4use::Ready4useIngest()	ready4use	Ready4useIngest		FALSE
Ready4useRepos	ready4use::Ready4useRepos()	ready4use	Ready4useRepos		FALSE
Ready4usePointer	ready4use::Ready4usePointer()	ready4use	Ready4usePointer		FALSE
Ready4useRecord	ready4use::Ready4useRecord()	ready4use	Ready4useRecord		FALSE
ScorzProfile	scorz::ScorzProfile()	scorz	ScorzProfile		FALSE
ScorzAqol6	scorz::ScorzAqol6()	scorz	ScorzAqol6		FALSE
ScorzAqol6Adol	scorz::ScorzAqol6Adol()	scorz	ScorzAqol6Adol		FALSE
ScorzAqol6Adult	scorz::ScorzAqol6Adult()	scorz	ScorzAqol6Adult		FALSE
ScorzEuroQol5	scorz::ScorzEuroQol5()	scorz	ScorzEuroQol5		FALSE
sf	sf::st_sf(sf::st_sfc())	sf	st_sf	sf::st_sfc()	FALSE
SpecificConverter	specific::SpecificConverter()	specific	SpecificConverter		FALSE
SpecificFixed	specific::SpecificFixed()	specific	SpecificFixed		FALSE
SpecificInitiator	specific::SpecificInitiator()	specific	SpecificInitiator		FALSE
SpecificMixed	specific::SpecificMixed()	specific	SpecificMixed		FALSE
SpecificModels	specific::SpecificModels()	specific	SpecificModels		FALSE
SpecificParameters	specific::SpecificParameters()	specific	SpecificParameters		FALSE
SpecificPredictors	specific::SpecificPredictors()	specific	SpecificPredictors		FALSE
SpecificPrivate	specific::SpecificPrivate()	specific	SpecificPrivate		FALSE
SpecificProject	specific::SpecificProject()	specific	SpecificProject		FALSE
SpecificResults	specific::SpecificResults()	specific	SpecificResults		FALSE
SpecificShareable	specific::SpecificShareable()	specific	SpecificShareable		FALSE
SpecificSynopsis	specific::SpecificSynopsis()	specific	SpecificSynopsis		FALSE
specific_models	specific::specific_models()	specific	specific_models		TRUE
specific_predictors	specific::specific_predictors()	specific	specific_predictors		TRUE
tbl_df	tibble::tibble()	tibble	tibble		FALSE
tbl_ts	tsibble::tsibble()	tsibble	tsibble		FALSE
TTUProject	TTU::TTUProject()	TTU	TTUProject		FALSE
TTUReports	TTU::TTUReports()	TTU	TTUReports		FALSE
TTUSynopsis	TTU::TTUSynopsis()	TTU	TTUSynopsis		FALSE
VicinityArguments	vicinity::VicinityArguments()	vicinity	VicinityArguments		FALSE
VicinityLocal	vicinity::VicinityLocal()	vicinity	VicinityLocal		FALSE
VicinityLocalProcessed	vicinity::VicinityLocalProcessed()	vicinity	VicinityLocalProcessed		FALSE
VicinityLocalRaw	vicinity::VicinityLocalRaw()	vicinity	VicinityLocalRaw		FALSE
VicinityLookup	vicinity::VicinityLookup()	vicinity	VicinityLookup		FALSE
VicinityMacro	vicinity::VicinityMacro()	vicinity	VicinityMacro		FALSE
VicinityMesoArea	vicinity::VicinityMesoArea()	vicinity	VicinityMesoArea		FALSE
VicinityMesoRegion	vicinity::VicinityMesoRegion()	vicinity	VicinityMesoRegion		FALSE
VicinityMicro	vicinity::VicinityMicro()	vicinity	VicinityMicro		FALSE
VicinityProfile	vicinity::VicinityProfile()	vicinity	VicinityProfile		FALSE
VicinitySpaceTime	vicinity::VicinitySpaceTime()	vicinity	VicinitySpaceTime		FALSE
vicinity_abbreviations	vicinity::vicinity_abbreviations()	vicinity	vicinity_abbreviations		TRUE
vicinity_identifiers	vicinity::vicinity_identifiers()	vicinity	vicinity_identifiers		TRUE
vicinity_mapes	vicinity::vicinity_mapes()	vicinity	vicinity_mapes		TRUE
vicinity_parameters	vicinity::vicinity_parameters()	vicinity	vicinity_parameters		TRUE
vicinity_points	vicinity::vicinity_points()	vicinity	vicinity_points		TRUE
vicinity_processed	vicinity::vicinity_processed()	vicinity	vicinity_processed		TRUE
vicinity_raw	vicinity::vicinity_raw()	vicinity	vicinity_raw		TRUE
vicinity_resolutions	vicinity::vicinity_resolutions()	vicinity	vicinity_resolutions		TRUE
vicinity_templates	vicinity::vicinity_templates()	vicinity	vicinity_templates		TRUE
vicinity_values	vicinity::vicinity_values()	vicinity	vicinity_values		TRUE
youthvars_aqol6d_adol	youthvars::youthvars_aqol6d_adol()	youthvars	youthvars_aqol6d_adol		TRUE
youthvars_chu9d_adolaus	youthvars::youthvars_chu9d_adolaus()	youthvars	youthvars_chu9d_adolaus		TRUE
youthvars_phq9	youthvars::youthvars_phq9()	youthvars	youthvars_phq9		TRUE
youthvars_bads	youthvars::youthvars_bads()	youthvars	youthvars_bads		TRUE
youthvars_gad7	youthvars::youthvars_gad7()	youthvars	youthvars_gad7		TRUE
youthvars_oasis	youthvars::youthvars_oasis()	youthvars	youthvars_oasis		TRUE
youthvars_scared	youthvars::youthvars_scared()	youthvars	youthvars_scared		TRUE
youthvars_k6	youthvars::youthvars_k6()	youthvars	youthvars_k6		TRUE
youthvars_k6_aus	youthvars::youthvars_k6_aus()	youthvars	youthvars_k6_aus		TRUE
youthvars_k10	youthvars::youthvars_k10()	youthvars	youthvars_k10		TRUE
youthvars_k10_aus	youthvars::youthvars_k10_aus()	youthvars	youthvars_k10_aus		TRUE
youthvars_sofas	youthvars::youthvars_sofas()	youthvars	youthvars_sofas		TRUE
YouthvarsDescriptives	youthvars::YouthvarsDescriptives()	youthvars	YouthvarsDescriptives		FALSE
YouthvarsProfile	youthvars::YouthvarsProfile()	youthvars	YouthvarsProfile		FALSE
YouthvarsSeries	youthvars::YouthvarsSeries()	youthvars	YouthvarsSeries		FALSE
MimicAlgorithms	MimicAlgorithms()	mimic	MimicAlgorithms		FALSE
MimicInputs	MimicInputs()	mimic	MimicInputs		FALSE
MimicRepos	MimicRepos()	mimic	MimicRepos		FALSE
MimicConfiguration	MimicConfiguration()	mimic	MimicConfiguration		FALSE

ready4class_constructor is another tibble based ready4 sub-module that summarises the desired features of the ready4 modules and sub-modules that you are authoring. An instance of ready4class_constructor is combined with a ready4fun_manifest sub-module to create a ready4class_manifest sub-module. Instances of ready4class_constructor are most efficiently created using the make_pt_ready4class_constructor function.

y <- make_pt_ready4class_manifest(ready4fun::ready4fun_manifest(),
                                  constructor_r3 = ready4class_constructor()) %>%
  ready4class_manifest()

Typical use

The most important method included in ready4class is the author method for the ready4class_manifest sub-module, that enhances the author method defined for the ready4fun_manifest so that consistently documented R package classes are also generated.

## Not run
author(y)

Examples

ready4class sub-modules and methods are not intended for independent use, but instead should be deployed as part of ready4pack R package authoring workflow.

Future documentation

It should be noted that some ready4class methods require files of a standardised format to be saved in specific sub-directories of the package data-raw directory. Detailed instructions on how to prepare these files are not yet available, but will be outlined in documentation to be released in 2022.

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.

Docs: Dissemating citable, documented and quality assured model module libraries

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

This below section renders a vignette article from the ready4pack 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)
library(ready4class)
library(ready4pack)

ready4pack is a toolkit for bundling collections of modules for computational health economic models authored with the ready4 framework as R packages that are:

Citable (with a Zenodo generated DOI and an algorithm generated CITATION file);
Community-minded (applying deprecation conventions supported by lifecycle);
Documented (applying a function self-documenting algorithm that extends sinew, deploying a GitHub pages hosted and pkgdown generated website and authoring PDF manuals stored in a GitHub Release via piggyback);
Internally consistent implementing automated checks to ensure consistency in naming conventions, etc;
Licensed (via a usethis generated GPL-3 license);
Quality assured (using continuous integration via GitHub actions and R-CMD-Check); and
Versioned (applying usethis version increments).

ready4pack extends ready4 framework tools for authoring module algorithms (ready4fun) and data structures (ready4class) and wraps functions from a number of third party R development workflow tools (such as devtools). ready4pack integrates these tools in a common workflow, while adding tools for authoring and documenting datasets to be shipped with model module R packages.

A combination of the ready4_pack_manifest class and author method are used to implement this workflow. This workflow has been used to author all public versions of the ready4 R packages available in the ready4 github repository.

Workflow

Manifest

The main class exported as part of ready4pack is readypack_manifest list based ready4 sub-module, that extends the ready4fun_manifest and ready4class_manifest sub-modules.

Typical usage

readypack_manifest sub-module is most efficiently created with the aid of the make_pt_ready4pack_manifest function and combines instances of the ready4fun_manifest and ready4class_constructor sub-modules.

x <- make_pt_ready4pack_manifest(ready4fun::ready4fun_manifest(),
                                 constructor_r3 = ready4class::ready4class_constructor()) %>%
  ready4pack_manifest()

The main method defined for readypack_manifest is author which extends the author method for ready4class_manifest to author a consistently documented R package.

## Not run
author(x)

Examples

Workflow example one

The program to author and document the ready4show package is relatively simple and authors:

the ready4show package CITATION, DESCRIPTION, LICENSE and README files;
all files in the ready4show package R directory;
the ready4show package website;
two versions of the ready4show package manual - a slimmed down version for end-users and a more detailed inventory of contents intended for developers;
an initial ready4show release for hosting supporting files, the creation of which will trigger archiving on Zenodo with a ready4show package DOI; and
an R-CMD-check continuous integration algorithm to be implemented each time a new version of ready4show is pushed to the main branch of the GitHub source code repository.

Workflow example two

The program to author and document the youthvars package is a bit more complex as it includes syntax to create package datasets. In addition to the package datasets, the algorithm creates content corresponding to the previous example, specifically:

the youthvars package CITATION, DESCRIPTION, LICENSE and README files;
all files in the youthvars package R directory;
the youthvars package website;
two versions of the youthvars package manual - a slimmed down version for end-users and a more detailed inventory of contents intended for developers;
an initial youthvars release for hosting supporting files, the creation of which will trigger archiving on Zenodo with a youthvars package DOI; and
an R-CMD-check continuous integration algorithm to be implemented each time a new version of youthvars is pushed to the main branch of the GitHub source code repository.

Future documentation

A more detailed guide to using ready4pack will be created in 2023.