Motivation
The ready4 framework uses
an
object-oriented programming (OOP) approach to implement
computational health economic models. 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 of methods as part of code verification and model validation checks;
- re-use sub-components of existing methods when authoring new methods.
To help facilitate achieving these objectives, methods associated with ready4 modules can be de-composed into functions that can be used independent of ready4 modules. However, these functions need to be documented and will be easier to comprehend if they 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 taxonomy and abbreviation
datasets to ensure standardised function code style and documentation.
Function names begin with a meaningful verb
Consistent with a naming convention popular in the R development
community, all functions authored with the ready4 framework
need to 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 used in functions authored for a ready4 framework
model implementation can be retrieved using get_fn_types(),
which by default returns a dataset instance of the
ready4fun_functions submodule.
x <- get_fn_types(gh_repo_1L_chr = "ready4-dev/ready4")
class(x)## [1] "ready4fun_functions" "tbl_df" "tbl"
## [4] "data.frame"| Verb | Description |
|---|---|
| Add | Updates an object by adding new values to new or empty fields. |
| 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. |
| 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 object. |
| Get | Extracts data from an object. |
| Import | Reads a data object in its native format and converts it to an R object. |
| Impute | Imputes data. |
| Knit | Knits an RMD or Rmarkdown file. |
| Launch | Launches an R Shiny app. |
| Make | Creates a new R object. |
| Plot | Plots data. |
| Predict | Applies a model to make predictions. |
| 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-specified 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. Definitions of all
meaningful suffices used in functions authored for a ready4 framework
model implementation can be retrieved using
get_obj_types(), which by default returns a dataset
instance of the ready4fun_objects submodule.
y <- get_obj_types(gh_repo_1L_chr = "ready4-dev/ready4")
class(y)## [1] "ready4fun_objects" "tbl_df" "tbl"
## [4] "data.frame"| 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 submodule |
| r4 | ready4 module |
| 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 in a ready4 framework model implementation can be
retrieved using get_abbrs(), which by default returns a
dataset instance of the ready4fun_abbreviations
submodule.
## [1] "ready4fun_abbreviations" "tbl_df"
## [3] "tbl" "data.frame"| 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_dbl | double vector of length one |
| 1L_dbl_ls | list of double vectors of length one |
| 1L_dtm | date vector of length one |
| 1L_dtm_ls | list of date vectors of length one |
| 1L_fct | factor vector of length one |
| 1L_fct_ls | list of factor vectors of length one |
| 1L_int | integer vector of length one |
| 1L_int_ls | list of integer vectors of length one |
| 1L_lgl | logical vector of length one |
| 1L_lgl_ls | list of logical vectors of length one |
| 1L_rgx | regular expression vector of length one |
| 1L_rgx_ls | list of regular expression vectors of length one |
| 1Ls | length ones |
| 8d | 8 Dimension |
| 8ds | 8 Dimensions |
| abbr | abbreviation |
| abbrs | abbreviations |
| abs | absolute |
| abss | absolutes |
| addl | additional |
| addls | additionals |
| adol | adolescent |
| adol6d | Assessment of Quality of Life Six Dimension (Adolescent version) |
| adols | adolescents |
| alg | algorithm |
| algs | algorithms |
| altv | alternative |
| anlys | analysis |
| anlyss | analyses |
| aqol | Assessment of Quality of Life |
| aqol6d | Assessment of Quality of Life Six Dimension |
| aqol6dU | Assessment of Quality of Life Six Dimension Health Utility |
| arg | argument |
| args | arguments |
| arr | array |
| arr_ls | list of arrays |
| arr_r3 | ready4 submodule extension of array |
| arr_r3_ls | list of ready4 submodule extension of arrays |
| artl | article |
| artls | articles |
| att | attribute |
| atts | attributes |
| aus | Australia |
| AusACT | Meta data for processing ACT population projections. |
| AusHeadspace | Meta data for constructing Headspace Centre geometries. |
| AusLookup | Lookup tables for Australian geometry and spatial attribute data. |
The ready4fun_abbreviations submodule is searchable. It
is therefore possible to see if an abbreviation has been defined for an
existing word or phrase…
procure(z,"template")## # A tibble: 2 × 3
## short_name_chr long_name_chr plural_lgl
## <chr> <chr> <lgl>
## 1 tmpl template FALSE
## 2 tmpls templates TRUE…and to look-up the meaning of an abbreviation…
procure(z,"org",type_1L_chr = "extension")## # A tibble: 2 × 3
## short_name_chr long_name_chr plural_lgl
## <chr> <chr> <lgl>
## 1 org organisation FALSE
## 2 orgs organisations TRUE…or whether a potential abbreviation has already been defined.
procure(z,"org", type_1L_chr = "extension", what_1L_chr = "string")## [1] "org" "orgs"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.
x <- ready4fun_manifest()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.