Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jessesadler/debvctrs

Tutorial for building S3 vectors with vctrs
https://github.com/jessesadler/debvctrs

r vctrs

Last synced: 20 days ago
JSON representation

Tutorial for building S3 vectors with vctrs

Host: GitHub
URL: https://github.com/jessesadler/debvctrs
Owner: jessesadler
License: other
Created: 2019-09-08T18:34:14.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2022-04-13T15:04:57.000Z (almost 3 years ago)
Last Synced: 2023-10-20T20:44:23.418Z (over 1 year ago)
Topics: r, vctrs
Language: R
Homepage:
Size: 89.8 KB
Stars: 30
Watchers: 3
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

jimsghstars - jessesadler/debvctrs - Tutorial for building S3 vectors with vctrs (R)

README

        # 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](https://www.jessesadler.com/slides/RStudio2020.pdf).

debvctrs is an example package to demonstrate the creation of new S3 vector classes using the [vctrs package](https://vctrs.r-lib.org). debvctrs is based on the more complete [debkeepr package](https://jessesadler.github.io/debkeepr) 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](https://testthat.r-lib.org).

## Installation

You can install debvctrs from GitHub with [remotes](https://remotes.r-lib.org):

``` r

# 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_decimal`type 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](https://vctrs.r-lib.org/articles/s3-vector.html#record-style-objects) 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](https://jessesadler.github.io/debkeepr/articles/debkeepr.html).

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](https://vctrs.r-lib.org/articles/s3-vector.html) 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](https://vctrs.r-lib.org)

    - The [S3 vectors vignette](https://vctrs.r-lib.org/articles/s3-vector.html) is particularly important for building an S3-vector class.

- [Hadley Wickham, Advanced R - Chapter 13: S3](https://adv-r.hadley.nz/s3.html#s3-methods)

- [Hadley Wickham, vctrs: Tools for making size and type consistent functions at RStudio::conf2019](https://resources.rstudio.com/rstudio-conf-2019/vctrs-tools-for-making-size-and-type-consistent-functions)

- [Earo Wang, A practical guide to vctrs-powered S3 programming](https://blog.earo.me/2019/11/03/practical-guide-to-s3/)