vctrs v0.1.0

0

Monthly downloads

0th

Percentile

Vector Helpers

Defines new notions of prototype and size that are used to provide tools for consistent and well-founded type-coercion and size-recycling, and are in turn connected to ideas of type- and size-stability useful for analyzing function interfaces.

Readme

vctrs

Travis build
status Coverage
status lifecycle

There are three main goals to the vctrs package, each described in a vignette:

  • To propose vec_size() and vec_type() as alternatives to length() and class(); vignette("type-size"). These definitions are paired with a framework for type-coercion and size-recycling.

  • To define type- and size-stability as desirable function properties, use them to analyse existing base function, and to propose better alternatives; vignette("stability"). This work has been particularly motivated by thinking about the ideal properties of c(), ifelse(), and rbind().

  • To provide a new vctr base class that makes it easy to create new S3 vectors; vignette("s3-vector"). vctrs provides methods for many base generics in terms of a few new vctrs generics, making implementation considerably simpler and more robust.

vctrs is a developer focused package. Understanding and extending vctrs requires some effort from developers, but should be invisible to most users. It’s our hope that having an underlying theory will mean that users can build up an accurate mental model without explicitly learning the theory. vctrs will typically be used by other packages, making it easy for them to provide new classes of S3 vectors that are supported throughout the tidyverse (and beyond). For that reason, vctrs has few dependencies.

Installation

vctrs is not currently on CRAN. Install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("r-lib/vctrs")

Usage

library(vctrs)

# Prototypes
str(vec_type_common(FALSE, 1L, 2.5))
#>  num(0)
str(vec_cast_common(FALSE, 1L, 2.5))
#> List of 3
#>  $ : num 0
#>  $ : num 1
#>  $ : num 2.5

# Sizes
str(vec_size_common(1, 1:10))
#>  int 10
str(vec_recycle_common(1, 1:10))
#> List of 2
#>  $ : num [1:10] 1 1 1 1 1 1 1 1 1 1
#>  $ : int [1:10] 1 2 3 4 5 6 7 8 9 10

Motivation

The original motivation for vctrs from two separate, but related problems. The first problem is that base::c() has rather undesirable behaviour when you mix different S3 vectors:

# combining factors makes integers
c(factor("a"), factor("b"))
#> [1] 1 1

# combing dates and date-times give incorrect values
dt <- as.Date("2020-01-1")
dttm <- as.POSIXct(dt)

c(dt, dttm)
#> [1] "2020-01-01"    "4321940-06-07"
c(dttm, dt)
#> [1] "2019-12-31 18:00:00 CST" "1969-12-31 23:04:22 CST"

This behaviour arises because c() has dual purposes: as well as it’s primary duty of combining vectors, it has a secondary duty of stripping attributes. For example, ?POSIXct suggests that you should use c() if you want to reset the timezone.

The second problem is that dplyr::bind_rows() is not extensible by others. Currently, it handles arbitrary S3 classes using heuristics, but these often fail, and it feels like we really need to think through the problem in order to build a principled solution. This intersects with the need to cleanly support more types of data frame columns including lists of data frames, data frames, and matrices.

Functions in vctrs

Name Description
vctrs-conditions Custom conditions for vctrs package
vec_duplicate Find duplicated values
vec_equal Test if two vectors are equal
vec_size Number of observations
fields Tools for accessing the fields of a record.
unspecified A 1d vector of unspecified type
vec_slice Get or set observations in a vector
%<-% Destructuring assignment
%0% Default value for empty vectors
obj_print print() and str() generics.
partial_frame Partially specify columns of a data frame
vec_arith Arithmetic operations
vec_compare Compare two vectors
vec_cast Cast a vector to specified type
vec_math Mathematical operations
vec_bind Combine many data frames into one data frame
s3_register Register a method for a suggested dependency
vec_c Combine many vectors into one vector
vec_na Create a missing vector
vec_unique Find and count unique values
vec_assert Assert an argument has known prototype and/or size
vec_list_cast Cast a list to vector of specific type
vec_match Find matching observations across vectors
vec_ptype_full Vector type as a string
vec_proxy_compare Comparison proxy
vec_proxy_equal Equality proxy
vec_recycle Vector recycling
vctrs-package vctrs: Vector Helpers
vec_count Count unique values in a vector
vec_data Extract underlying data
vec_type Find the prototype of a set of vectors
vec_type2.tbl_df Find the common type for a pair of vector types
new_partial Partial type
new_list_of Create list_of subclass
new_rcrd rcrd (record) S3 class
list_of list_of S3 class for homogenous lists
new_vctr vctr (vector) S3 class
new_data_frame Data frame class
new_date Date, date-time, and duration S3 classes
new_factor Factor/ordered factor S3 class
dims Vector dimensions
No Results!

Vignettes of vctrs

Name
s3-vector.Rmd
stability.Rmd
type-size.Rmd
No Results!

Last month downloads

Details

License GPL-3
URL https://github.com/r-lib/vctrs
BugReports https://github.com/r-lib/vctrs/issues
VignetteBuilder knitr
Encoding UTF-8
Language en-GB
LazyData true
RoxygenNote 6.1.1
NeedsCompilation yes
Packaged 2018-11-19 14:40:32 UTC; hadley
Repository CRAN
Date/Publication 2018-11-29 17:10:03 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/vctrs)](http://www.rdocumentation.org/packages/vctrs)