vctrs v0.1.0
Monthly downloads
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 
There are three main goals to the vctrs package, each described in a vignette:
To propose
vec_size()
andvec_type()
as alternatives tolength()
andclass()
;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 ofc()
,ifelse()
, andrbind()
.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
[](http://www.rdocumentation.org/packages/vctrs)