# Apply Model Modules Using A Simple And Consistent Syntax

    library(ready4)

## Motivation

To be used in health economic analyses, model modules need to be called using a programming syntax. Ideally that syntax should be relatively simple, with the name and description of each command reliably communicating the category of operations it performs.

## Implementation

`ready4` provides a simple syntax that is used by all model modules developed with the `ready4` framework.

## Use

A table that itemises `ready4` commands along with examples of how these commands are used can be ingested from a periodically updated database using `get_methods_tb`. In the below example we will search for examples of where that syntax has been used by modules from the readyforwhatsnext model. The value supplied to the `gh_repo_1L_chr` argument specifies the repository in which a dataset of readyforwhatsnext module libraries is stored.

    x <- get_methods_tb(gh_repo_1L_chr = "ready4-dev/ready4")

### Core commands

A HTML table of `ready4`’s core commands and examples of the use of each command 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 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

### Applying commands to module “slots”

Each of the “core” commands also has a “slot” version, which applies the command to a specified slot (a named element of a module). 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 slot commands and relevant examples 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, 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 | Renew (set) the values of data in a module slot | 4, 14 , 17 , 19 , 20
shareSlot | Apply the share method to a model module slot |

### Extended commands

Finally, there are a small number of other commands that are more general extensions of the core commands. Currently, these extended commands are all variants on the `author` command, with each extension specifying the type of output to be authored by the method. 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