debvctrs

This tutorial package is meant to go along with my talk vctrs: Creating custom vector classes with the vctrs package at RStudio::conf 2020. Slides from the talk are available here.

debvctrs is an example package to demonstrate the creation of new S3 vector classes using the vctrs package. debvctrs is based on the more complete debkeepr package that integrates non-decimal currencies that use the tripartite system of pounds, shillings, and pence into R. This package is not meant for analytical use, though all aspects of the package work as expected and are fully tested using testthat.

Installation

You can install debvctrs from GitHub with remotes:

# install.packages("remotes")
remotes::install_github("jessesadler/debvctrs")

Usage

The debvctrs package demonstrates the process for creating two different types of S3-vector classes or types. The deb_decimaltype represents non-decimal currencies in decimalized form and is based on a double vector. It has two attributes: a unit attribute to record whether the values represent pounds, shillings, or pence and a bases attribute to determine the bases of the shillings and pence units. The deb_lsd type uses the record style to maintain the tripartite structure of non-decimal currencies. A record-style vector uses a list of equal-length vectors to designate the components that make up each vector. Like the deb_decimal type, deb_lsd has a bases attribute. For a more thorough introduction to the structure of the two classes and the use of the classes, see the description from the debkeepr package.

The R scripts for the package provide an order for constructing these two S3 vectors with vctrs. This tutorial is based on the S3 vignette from the vctrs package. It will be useful to work through this tutorial with the explanations from the vignette.

• 01: Construction of deb_decimal() and deb_lsd() classes
  • 01.1-decimal-class.R: Construction of deb_decimal class based on a double vector.
  • 01.2-lsd-class.R: Construction of deb_lsd class, a record-style vector.
  • 01.3-checks.R: Checks used in the construction of the two classes to provide more user-friendly error messages.
• 02-coercion.R: Implicit transformation of the class of vectors
  • A) Coercion for deb_decimal
  • B) Coercion for deb_lsd
  • C) Coercion between deb_decimal and deb_lsd
• 03-casting.R: Explicit transformation of the class of vectors
  • A) Casting for deb_decimal
  • B) Casting for deb_lsd
  • C) Casting between deb_decimal and deb_lsd
• 04-comparison-lsd.R: Only necessary to implement for record-style vector
  • A) Equality: ==, !=, unique(), anyDuplicated(), and is.na()
  • B) Comparison: <, <=, >=, >, min(), max(), and xtfrm()
• 05-mathematical-funcs.R: Only necessary to implement for record-style vector
  • A) Implemented Summary and Math group functions and other generics
  • B) Unimplemented functions
• 06-arithmetic-ops.R: Arithmetic operations
  • A) Arithmetic operations for deb_decimal
  • B) Arithmetic operations for deb_lsd
  • C) Arithmetic operations between deb_decimal and deb_lsd
• helper-convert-attr.R: Conversions of bases and unit attributes
  • A) Convert bases attribute
  • B) Convert unit attribute
• helper-normalize.R: Function to normalize non-decimal currency values
  • Normalization is central to integrating non-decimal currencies into R
• utils.R
  • An if else function implemented with vctrs that is used in the package
• debvctrs-package.R
  • Package documentation and documentation for vctrs parameters

Resources

• vctrs site
  • The S3 vectors vignette is particularly important for building an S3-vector class.
• Hadley Wickham, Advanced R - Chapter 13: S3
• Hadley Wickham, vctrs: Tools for making size and type consistent functions at RStudio::conf2019
• Earo Wang, A practical guide to vctrs-powered S3 programming