vctrs v0.0.0.9000

0

Monthly downloads

0th

Percentile

Vector Helpers

Functions that help you work with vectors, particularly numeric. Provides a full set of summary, cumulative, rolling, and vectorised functions for both R and C.

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

Vignettes of vctrs

Name
arithmetic.Rmd
base-classes.Rmd
double-dispatch.Rmd
extending-vctrs.Rmd
function-types.Rmd
proxies.Rmd
s3-base.Rmd
s3-proxy.Rmd
s3-vector.Rmd
size.Rmd
stability.Rmd
theory.Rmd
type-size.Rmd
type.Rmd
vctrs-vs-base.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
Roxygen list(markdown = TRUE)
RoxygenNote 6.1.0

Include our badge in your README

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