Methods to Enrich R Objects with Extra Components

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', 'glm' and 'betareg'. 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.


CRAN_Status_Badge Travis-CI Build Status Coverage Status

Methods to enrich list-like R objects with extra components

Rationale

When I develop a piece of statistical methodology it is not uncommon that it depends on functionality or quantities that a list-like core R object object_x of a certain class could have but doesn't. An example is objects of class link-glm which only provide up to the the first derivatives of the link function. It is also not uncommon that the functionality or quantities that I need are hard-coded in another package in the R ecosystem. Prominent examples include implementations of gradients of the log-likelihood and information matrices for specific model classes.

In such cases, I either contact the developers and ask them to provide a generic which I can then use, or copy some of the code and adopt it to what I'm doing. Both options can be rather time-consuming, and particularly the latter is rarely bug-free.

I believe that

  • users and developers should have direct access to useful functionality and quantities in the R ecosystem, epsecially if these include implementations of complex statistical quantities

  • quantities and functionality that are specific to a list-like object_x should be components of object_x

The above motivated me to develop the enrichwith R package that allows object_x to be enriched with components corresponding to the option enrichment_option through the following simple call

enrich(object_x, with = enrichment_option)

The call is inspired by Donald Knuth's literare programing paradigm.

Purpose and objective

The main objective of enrichwith is to allow users and developers to directly use the enrichment options that other developers have provided, through a clean interface, minimising the need to adopt source code of others.

The purpose of enrichwith is to provide:

  • useful enrichment options for core R objects, including objects of class lm, glm, link-glm and family (see, for example, ?enrich.glm)

  • methods for producing customisable source code templates for the structured implementation of methods to compute new components (see ?enrichwith and ?create_enrichwith_skeleton)

  • generic methods for the easy enrichment of the object with those components (see, for example, ?enrich and ?get_enrichment_options)

Vignettes

The vignettes illustrate the enrichwith functionality through comprehensive, step-by-step case studies. These also include illustrations from recent research of mine on methods for statistical learning and inference.

Installation

Get the development version from github with

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

Examples

link-glm objects

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 inverse 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] "enriched_link-glm" "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.

family objects

News

enrichwith 0.1

Bug fixes

New functionality

  • enrich.family can return 4th derivatives of the a function and other characteristics of the exponential family
  • enrich method for betareg objects (enrichment options with scores, information, bias and simulate)

Other improvements, updates and additions

  • Documentation updates
  • Added vignette for enrich.family including a description of the exponential family

enrichwith 0.05

Bug fixes

  • Fixed bug when passing a vector of options in the with argument of enrich methods
  • Fixed a bug that would return wrong results if the bias function was passed a named vectors

New functionality

Other improvements, updates and additions

  • Added d,p,q and enriched_glm in the vignette
  • Documentation updates

enrichwith 0.04

Bug fixes

  • p,q,d model: if data is missing then the model frame is used
  • Fixed error message in qmodel

New functionality

  • Added get_dmodel_function, get_pmodel_function, get_qmodel_function
  • enriched_glm can now be used to fit GLMs and get objects that are enriched with auxiliary functions and other components when compared to their glm counterparts

Other improvements, updates and additions

  • Fixed typos in ?enrich.family
  • Added documentation for get_dmodel_function.glm, get_pmodel_function.glm, get_qmodel_function.glm

enrichwith 0.03

Bug fixes

  • Took care of aliasing in bias calculations
  • Names of score and bias components do not get a prefix anymore
  • Fixed a bug on argument of information function (part of the "auxiliary functions" enrichment option)
  • Fixed a bug when testing the simulation methods

New functionality

  • Provide enrich capabilities for lm objects
  • Score functions (?get_score_function) now accept contributions = TRUE for getting score contributions
  • Provide the get_*_function convenience methods (e.g. get_score_function, get_information_function, get_bias_function)
  • Provide the dmodel, pmodel, qmodel auxiliary functions for glm objects, to compute d, p, q based on a supplied data frame

Other improvements, updates and additions

  • Various codebase improvements
  • Various documentation improvements
  • New vignette for enriching glm objects
  • Updated README file

enrichwith 0.02

  • Fixed an issue with the example in ?enrich.glm
  • Minor codebase improvements
  • 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 how bias-reduction for GLMs can be implemented using enriched glm objects

enrichwith 0.01

  • First release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("enrichwith")

0.1 by Ioannis Kosmidis, 3 months ago


https://github.com/ikosmidis/enrichwith


Browse source code at https://github.com/cran/enrichwith


Authors: Ioannis Kosmidis [aut, cre]


Documentation:   PDF Manual  


GPL-2 | GPL-3 license


Suggests whisker, SuppDists, brglm, ggplot2, knitr, rmarkdown


Imported by brglm2.

Depended on by mbrglm.


See at CRAN