This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Authoring ready4 modules

Tools from the ready4class, ready4 fun and ready4pack R packages streamline and standardise the authoring of ready4 modules.

1 - Authoring model data structures

The ready4class R package supports partially automated and standardised workflows for defining the data structures to be used in computational models.

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

Motivation

The ready4 model 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
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
POSIXt .POSIXct(NA_character\_) base .POSIXct NA_character\_ FALSE
dfidx dfidx::dfidx(dfidx()) dfidx dfidx dfidx() FALSE
Ready4Module ready4::Ready4Module() ready4 Ready4Module FALSE
Ready4Private ready4::Ready4Private() ready4 Ready4Private FALSE
Ready4Public ready4::Ready4Public() ready4 Ready4Public FALSE
sf sf::st_sf(sf::st_sfc()) sf st_sf sf::st_sfc() FALSE
tbl_df tibble::tibble() tibble tibble FALSE
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
ready4fun_badges ready4fun::ready4fun_badges() ready4fun ready4fun_badges TRUE
ready4fun_abbreviations ready4fun::ready4fun_abbreviations() ready4fun ready4fun_abbreviations TRUE
ready4fun_objects ready4fun::ready4fun_objects() ready4fun ready4fun_objects TRUE
ready4fun_functions ready4fun::ready4fun_functions() ready4fun ready4fun_functions TRUE
ready4fun_executor ready4fun::ready4fun_executor() ready4fun ready4fun_executor TRUE
ready4fun_description ready4fun::ready4fun_description() ready4fun ready4fun_description 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_manifest ready4fun::ready4fun_manifest() ready4fun ready4fun_manifest TRUE
ready4fun_dataset ready4fun::ready4fun_dataset() ready4fun ready4fun_dataset TRUE
ready4class_constructor ready4class::ready4class_constructor() ready4class ready4class_constructor TRUE
ready4class_pt_lup ready4class::ready4class_pt_lup() ready4class ready4class_pt_lup TRUE
ready4class_manifest ready4class::ready4class_manifest() ready4class ready4class_manifest TRUE
ready4pack_manifest ready4pack::ready4pack_manifest() ready4pack ready4pack_manifest TRUE
youthvars_aqol6d_adol youthvars::youthvars_aqol6d_adol() youthvars youthvars_aqol6d_adol 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_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
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
specific_models specific::specific_models() specific specific_models TRUE
specific_predictors specific::specific_predictors() specific specific_predictors TRUE
SpecificParameters specific::SpecificParameters() specific SpecificParameters FALSE
SpecificPrivate specific::SpecificPrivate() specific SpecificPrivate FALSE
SpecificShareable specific::SpecificShareable() specific SpecificShareable FALSE
SpecificResults specific::SpecificResults() specific SpecificResults FALSE
SpecificProject specific::SpecificProject() specific SpecificProject FALSE
SpecificInitiator specific::SpecificInitiator() specific SpecificInitiator FALSE
SpecificModels specific::SpecificModels() specific SpecificModels FALSE
SpecificPredictors specific::SpecificPredictors() specific SpecificPredictors FALSE
SpecificFixed specific::SpecificFixed() specific SpecificFixed FALSE
SpecificMixed specific::SpecificMixed() specific SpecificMixed FALSE
SpecificConverter specific::SpecificConverter() specific SpecificConverter FALSE
SpecificSynopsis specific::SpecificSynopsis() specific SpecificSynopsis FALSE
TTUSynopsis TTUSynopsis() TTU TTUSynopsis FALSE
TTUReports TTUReports() TTU TTUReports FALSE
TTUProject TTUProject() TTU TTUProject 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.

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.

2 - Authoring model algorithms

The ready4fun R package supports standardised approaches to code authoring that facilitate partial automation of the documenting of model algorithms.

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

Motivation

The ready4 youth mental health systems model is implemented using an object-oriented programming (OOP) approach. 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 (“functions”) of methods as part of code verification and model validation checks;
  • re-use functions when authoring new methods.

Therefore when authoring ready4 code libraries, it is important to ensure that “under the hood” code can be readily understood. Two ways for achieving this goal is to ensure that all functions (even those not intended for use by modeller end-users) are adequately documented and 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 a dataset of taxonomies and abbreviations to ensure standardised function code style and documentation. A copy of this dataset (dataset_ls) can be downloaded from a repository associated with the ready4 package using tools from the ready4use package package.

dataset_ls <- ready4use::Ready4useRepos(gh_repo_1L_chr = "ready4-dev/ready4",
                               gh_tag_1L_chr = "Documentation_0.0") %>%
  ingest(metadata_1L_lgl = F)

Function names begin with a meaningful verb

Consistent with a naming convention popular in the R development community, all ready4 framework functions 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 currently used by ready4 functions (excluding methods) are stored in element fn_types_lup of dataset_ls, the key features of which are reproduced below.

dataset_ls$fn_types_lup %>% 
  ready4fun_functions() %>%
  renew(filter_cdn_1L_chr = "!is_generic_lgl & !stringr::str_detect(fn_type_nm_chr, pattern = ' ')") %>%
  exhibit(select_int = 1:2,
          scroll_box_args_ls = list(width = "100%"))
Meaningful verbs
Verb Description
Add Updates an object by adding data to that object.
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.
Extract Extracts data from an object.
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 output.
Get Retrieves a pre-existing data object from memory, local file system or online repository.
Import Reads a data object in its native format and converts it to an R object.
Impute Imputes data.
Knit Knits a rmarkdown file
Launch Launches an application
Make Creates a new R object.
Plot Plots data
Predict Makes predictions from data using a specified statistical model.
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-speccified 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. The meaningful suffices currently used by to describe objects in the ready4 framework are stored in element seed_obj_type_lup of dataset_ls, the key features of which are reproduced below.

dataset_ls$seed_obj_type_lup %>% 
  ready4fun_objects() %>%
  exhibit(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 S3
r4 ready4 S4
rgx regular expression
s3 S3
s4 S4
sf simple features object
tb tibble

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 throughout the ready4 framework is maintained in the abbreviations_lup element of dataset_ls. The list of abbreviations is now quite extensive and continues to grow as the ready4 suite of software expands. The initial few entries of abbreviations_lup are reproduced below.

dataset_ls$abbreviations_lup %>% 
  head() %>%
  exhibit(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_chr_r4 ready4 S4 collection of character vectors of length one
1L_dbl double vector of length one

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.

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 will be released in 2022.

3 - Dissemating citable, documented and quality assured model module libraries

ready4 supports tools to streamline the testing, description and distribution of computational model modules.

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

ready4pack is a toolkit for authoring collections of modules for the ready4 youth mental health systems model and disseminating them 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 builds on both third party development workflow tools (such as devtools) and ready4 tools for authoring functions (ready4fun) and classes (ready4class). ready4pack integrates these tools in a common workflow, while adding tools for authoring and documenting R package datasets.

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:

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:

Future documentation

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