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.
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.
A table that summarises the latest ready4
syntax can be
ingested from a periodically updated database using
get_methods_tb
.
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.
Method | Purpose | Examples |
---|---|---|
author | Author and save files | 5 , 6, 7 , 16 , 17 |
characterize | Characterize model module data by generating (tabular) descriptive statistics | |
depict | Depict (plot) features of model module data | 13, 14 , 15 |
enhance | Enhance a model module by adding new elements | |
exhibit | Exhibit features of model module data by printing them to the R console | 2 , 5 , 6, 13 , 14 , 15 , 16 , 17 , 18 , 19 , 20 |
ingest | Ingest data | 1 , 2 , 3 , 6, 13 , 14 , 15 , 16 , 17 , 18 |
investigate | Investigate solutions to an inverse problem | 16 , 17 |
manufacture | Manufacture a new object | |
metamorphose | Metamorphose a model module to a model module of a different (non-inheriting) class | 17 |
procure | Procure items from a dataset | 5, 17 |
prognosticate | Prognosticate (make predictions) by solving a forward problem | |
ratify | Ratify that input or output data meet validity criteria | 13, 17 , 19 , 20 |
reckon | Reckon (calculate) a value | |
renew | Renew (update) values | 1 , 2 , 13, 14 , 15 , 16 , 17 , 19 , 20 |
share | Share data via an online repository | 1 , 13, 14 , 15 , 16 |
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.
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, 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, 14 , 17 , 19 , 20 |
shareSlot | Apply the share method to a model module slot |