Syntax

ready4 modules use a simple and consistent syntax.

This below section renders a vignette article from the ready4 library. You can use the following links to:

Motivation

Transparency is one of the underpinning principles of ethical modelling practice. One way to improve the transparency of computational health economic models (such as those we are developing in youth mental health) is to ensure that the programs implementing model analyses can be meaningfully inspected by readers with different levels of technical expertise. Even non-technical readers should be able to follow the high-level logic implemented by model algorithms. If multiple analysis programs are written using a common simplified syntax then reviewers of those programs need to contend with relatively fewer new concepts.

Implementation

ready4 provides a simple syntax that can be consistently applied to attach algorithms (methods) to model modules. It does so by taking advantage of the abstraction and polymorphism features of Object Oriented Programing and R’s use of generic functions. Generic functions don’t implement algorithms themselves - their most salient features are a name and a high level description of the type of task that any method associated with that generic should perform. Whenever a developer creates a method for classes that use R’s S4 and S3 systems (the types used for model modules and sub-modules), they can associate that method with the generic that has a description that is the best match for the algorithm being implemented.

Available generics

A table that summarises the latest ready4 syntax can be ingested from a periodically updated database using get_methods_tb.

Core generics

ready4 includes a number of core generic functions which describe the main types of method to be implemented by model modules. Notably, the ready4 package does not associate methods with any of these core generics. Instead, methods are associated with these generics in R packages of model modules. A HTML table of ready4’s core generics and examples of methods associated with each generic can be displayed using the print_methods function, using the return_1L_chr = "core" argument.

print_methods(x,
              return_1L_chr = "core",
              scroll_width_1L_chr = "100%") 
Method Purpose Examples
author Author and save files 5 , 6, 7 , 16 , 17
characterize Characterize data by generating (tabular) descriptive statistics
depict Depict (plot) features of a dataset 13, 14 , 15
enhance Enhance a dataset by adding new elements
exhibit Exhibit features of a dataset by printing them to the R console 2 , 5 , 6, 13 , 14 , 15 , 16 , 17 , 19 , 20
ingest Ingest data 1 , 2 , 3 , 5 , 6, 13 , 14 , 15 , 16 , 17
investigate Investigate solutions to an inverse problem 16 , 17
manufacture Manufacture a new object
metamorphose Metamorphose data from one model module (or sub-module) instance to an instance of a different model module or sub-module 17
procure Procure items from a dataset 17
prognosticate Prognosticate (make predictions) by solving a forward problem
ratify Ratify that a dataset meets validity criteria 13, 17 , 19 , 20
reckon Reckon (calculate) a value
renew Renew values in a dataset 1 , 2 , 5 , 13, 14 , 15 , 16 , 17 , 19 , 20
share Share data via an online repository 1 , 13, 14 , 15 , 16

Slot generics and methods

Each of the “core” generics also has a “slot” version, for use when applying a core method to a specified slot of a class. The ready4 package associated methods for each of these “slot” generics for the Ready4Module template. Two of these “slot” methods can also be used for additional purposes:

  • procureSlot is a “getter” method - its default behaviour is to return the value of a specified slot. If the argument use_procure_mthd_1L_lgl = T is included in the method call, procureSlot will instead apply the procure method to a specified slot.

  • renewSlot is a “setter” method - if any value other than “use_renew_mthd” (the default) is passed to the new_val_xx argument, that value will be assigned to the specified slot.

A HTML table of the slot generics bundled with ready4 can be displayed using the print_methods function, using the return_1L_chr = "slot" argument.

print_methods(x,
              return_1L_chr = "slot",
              scroll_width_1L_chr = "100%")
Method Purpose Examples
authorSlot Apply the author method to a model module slot
characterizeSlot Apply the characterize method to a model module slot
depictSlot Apply the depict method to a model module slot
enhanceSlot Apply the enhance method to a model module slot
exhibitSlot Apply the exhibit method to a model module slot 4, 17 , 19 , 20
ingestSlot Apply the ingest method to a model module slot
investigateSlot Apply the investigate method to a model module slot
manufactureSlot Apply the manufacture method to a model module slot
metamorphoseSlot Apply the metamorphose method to a model module slot
procureSlot Procure (get) data from a slot 4, 8 , 14 , 16 , 17
prognosticateSlot Apply the prognosticate method to a model module slot
ratifySlot Apply the ratify method to a model module slot
reckonSlot Apply the reckon method to a model module slot
renewSlot Apply the renew method to a model module slot 4, 8 , 14 , 17 , 19 , 20
shareSlot Apply the share method to a model module slot

Extended author generics

Finally, there are a small number of other generics that are more general extensions of the core functions. Currently, these extended generics are all variants on the author generics, with each one specifying the type of output to be authored by the method. The ready4 package does not include methods for any of these extended generics. A HTML table of the extended generics bundled with ready4 can be displayed using the print_methods function, using the return_1L_chr = "extended" argument.

print_methods(x,
              exclude_mthds_for_chr = "Ready4Module",
              return_1L_chr = "extended",
              scroll_width_1L_chr = "100%")
Method Purpose Examples
authorClasses Author and document classes
authorData Author and document datasets 4, 17
authorFunctions Author and document functions
authorReport Author and save a report 4
Last modified February 2, 2024: more tidy-ups of model export (11ef896)