Provides the "enrich" method to enrich list-like R objects with new, relevant components. The current version has methods for enriching objects of class 'family', 'link-glm', 'lm' and 'glm'. The resulting objects preserve their class, so all methods associated with them still apply. The package also provides the 'enriched_glm' function that has the same interface as 'glm' but results in objects of class 'enriched_glm'. In addition to the usual components in a `glm` object, 'enriched_glm' objects carry an object-specific simulate method and functions to compute the scores, the observed and expected information matrix, the first-order bias, as well as model densities, probabilities, and quantiles at arbitrary parameter values. The package can also be used to produce customizable source code templates for the structured implementation of methods to compute new components and enrich arbitrary objects.

Methods to enrich list-like R objects with extra components

Get the development version from github with

# install.packages("devtools")devtools::install_github("ikosmidis/enrichwith")

Suppose you developed a piece of statistical methodology that relies
on a component that a list-like R object `object_x`

of a certain class
could potentially have but doesn't.

The aim of **enrichwith** is to:

- produce customisable source code templates for the structured implementation of methods to compute new components
- provide generic methods for the easy enrichment of the object with those components

Specifically, once the methods for the components have been
implemented, `object_x`

can be enriched with the components
corresponding to the option `enrichment_option`

through the following simple call.

enrich(object_x, with = enrichment_option)

The main objectives of **enrichwith** is to allow users and developers to directly use the enrichment options that other developers have provided, minimising the need of adapting source code of others.

Objects of class `link-glm`

have as components functions to compute the link function (`linkfun`

), the inverse link function (`linkinv`

), and the 1st derivative of the link function (`mu.eta`

).

**enrichwith** comes with a built-in template with the methods for the enrichment of `link-glm`

objects with the 2nd and 3rd derivatives of the inverse link function.

The `get_enrichment_options`

method can be used to check what enrichment options are available for objects of class `link-glm`

.

library("enrichwith")standard_link <- make.link("probit")class(standard_link)# [1] "link-glm"get_enrichment_options(standard_link)# -------# Option: d2mu.deta# Description: 2nd derivative of the inverse link function# component compute_function# 1 d2mu.deta compute_d2mu.deta# -------# Option: d3mu.deta# Description: 3rd derivative of the inverse link function# component compute_function# 1 d3mu.deta compute_d3mu.deta# -------# Option: inverse link derivatives# Description: 2nd and 3rd derivative of the inverse link function# component compute_function# 1 d2mu.deta compute_d2mu.deta# 2 d3mu.deta compute_d3mu.deta# -------# Option: all# Description: all available options# component compute_function# 1 d2mu.deta compute_d2mu.deta# 2 d3mu.deta compute_d3mu.deta

According to the result of `get_enrichment_options`

, the object `standard_link`

can be enriched with the 2nd and 3rd derivative of the inverse
link function through the option "inverse link derivatives".

enriched_link <- enrich(standard_link, with = "inverse link derivatives")class(enriched_link)# [1] "link-glm"cat(format(enriched_link$d2mu.deta), sep = "\n")# function (eta)# {# -eta * pmax(dnorm(eta), .Machine$double.eps)# }cat(format(enriched_link$d3mu.deta), sep = "\n")# function (eta)# {# (eta^2 - 1) * pmax(dnorm(eta), .Machine$double.eps)# }

`enriched_link`

is now an "enriched" `link-glm`

object, which, as per the enrichment options above, has the extra components `d2mu.deta`

and `d3mu.deta`

, for the calculation of 2nd and 3rd derivatives of the inverse link function with respect to `eta`

, respectively.

The implemention of enrichment options is streamlined into 3 steps:

- Use
`create_enrichwith_skeleton`

to produce an enrichwith template. - Edit the
`compute_*`

functions by adding the specific code that calculates the components. - Finalise the documentation and/or include more examples.

The first step results in a template that includes all necessary
functions to carry out the enrichment. The second step is where the
user edits that template and implements the calculation of the
components that the object will be enriched with. Specifically, each
`compute_*`

function takes as input the object to be enriched and
returns the corresponding new component to be added to the object.

Everything else (for example, mapping between the enrichment options
and the components that the enriched object will have, checks that an
enrichment option exists, listing enrichment options, enriching the
object, and so on) is taken care of by the methods in **enrichwith**.

Developers can either put their **enrichwith** templates in their
packages or are welcome to contribute their template to
**enrichwith**, particularly if that extends core R objects.

- Fixed an issue with the example in ?enrich.glm
- Minor codebase imporvements
- Harmonised the output of the functions in the auxiliary_functions component of enriched
`glm`

objects - More detailed descriptions for the enrichment options for
`glm`

objects - Included a vignette on ohw bias-reduction for GLMs can be implemented using enriched
`glm`

objects

- First release