Syntax

library("ready4") 

Motivation

Transparency is one of the underpinning principles of open science. One way to improve the transparency of the ready4 model is to ensure that the programs implementing analyses using this model 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. By using a simple programming syntax that can be consistently used across all model analyses programs, ready4 can help ensure that readers need to contend with relatively few new concepts when reviewing analysis code.

Implementation

ready4 provides a simple syntax that can be consistently applied to all ready4 model modules. It does so by taking advantage of the polymorphism and abstraction features of Object Oriented Programing and R’s use of generic functions. Generic functions don’t obviously do anything by themselves - their most salient features are a name and a high level description of the type of task that any method using that name should perform. Whenever a method is defined for classes that use R’s S4 and S3 systems (the types used for ready4 model modules and sub-modules), it is assigned to the generic that is the best match for the algorithm it implements.

Finding ready4 Methods

A table that summarises the syntax used by ready4 model module methods, can be generated by web-scraping using make_methods_tb (which produces up to date results but can be a little slow to excecute) or alternatively be downloaded from a periodically updated database using get_methods_tb (which is quicker to implement, but may miss the most recent additions).

# Not run
# x <- make_methods_tb()

x <- get_methods_tb()

Core generics

ready4 includes a number of core generic functions which describe the main types of method to be implemented by ready4 model modules. Notably, the ready4 package does not define methods for any of these core generics. Instead, methods are defined for these generics in R packages that contain ready4 modules. A HTML table of the core generics bundled with ready4 and examples of methods that implement 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%") 

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 defines methods for each of these “slot” generics for the Ready4Module class. 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%")

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 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%")