DOCSEARCHbyAlgolia
Submit Docs

vctrs R Package

repository·main·Indexed 43 days ago

https://github.com/r-lib/vctrs

A developer-focused R package providing a framework for robust size-recycling, type-coercion, and the creation of new S3 vector classes. It introduces tools like vec_size(), vec_ptype(), vec_size_common(), and vec_cast_common() to improve the stability and predictability of vector operations across the tidyverse and other R ecosystems.

Tokens
1.7K
Snippets
9
Records
10
Agent score
55%

What's inside vctrs

  1. Core concepts of vctrs: Size, Type, and S3 Vectors

    main

    The vctrs package is designed for developers building R packages, specifically focusing on three pillars:

    1. Size and Type Stability: It proposes vec_size() and vec_ptype() as more robust alternatives to length() and class(). These functions are used within a framework for size-recycling and type-coercion.
    2. Stability Analysis: It defines size- and type-stability as desirable properties for functions (e.g., improving upon the behavior of c(), ifelse(), and rbind()).
    3. S3 Vector Construction: It provides a new vctr base class that simplifies the creation of new S3 vectors. By implementing a few new vctrs generics, developers can provide robust implementations for many base R generics.

    While vctrs is a developer-focused package, its goal is to provide an underlying theory that makes vector operations predictable and consistent across the tidyverse and other ecosystems.

  2. Get detailed reverse dependency failure info with revdepcheck

    main

    To obtain more detailed information regarding failures for specific packages (e.g., bayesdfa, ClustAssess, CytoML, flowWorkspace, h3o, loon.shiny, NanoMethViz, rshift, sift, or Signac), use the revdepcheck::cloud_details() function.

    revdepcheck::cloud_details(, "package_name")

  3. Install vctrs

    main

    You can install the stable version of vctrs from CRAN or the development version using pak.

    # Install stable version from CRAN
install.packages("vctrs")

# Install development version using pak
# install.packages("pak")
pak::pak("r-lib/vctrs")

  4. Troubleshoot vec_restore dispatch errors with sf objects

    main

    In some workflows involving ggplot2 and sf, vctrs::vec_c() may trigger a dispatch error during vec_restore. This typically occurs when vctrs::vec_restore_dispatch attempts to restore an object (like an sfc object from the sf package) and fails during the sf::st_sfc call. This is often seen in the backtrace when ggplot2 calls vec_c to combine layers or collections.

    # Error context seen in APCI (1.0.8)
vctrs::vec_c(points, lines, others, collections)
# Leads to: sf:::vec_restore.sfc(x = x, to = to)

  5. Troubleshoot the error: `x` must be a list, not a list matrix

    main

    This error occurs when a function (often via dplyr::bind_rows or list_flatten) calls vctrs::obj_check_list(x) and receives a list matrix instead of a standard list. This is a known breaking change/issue affecting several downstream packages when they interact with vctrs or dplyr internals.

    Affected Packages (Examples):

    • feisr (in detrend and feis functions)
    • merTools (in REsim function)
    • crane (in various tbl_ tests)

    Common Backtrace Pattern:

    1. vctrs::obj_check_list(x)
    2. vctrs:::stop_non_list_type(x, y, z)
    3. dplyr:::list_flatten(dots, fn = is_flattenable)
    4. dplyr::bind_rows(...)
    Error in `list_flatten()`:
! `x` must be a list, not a list matrix.

  6. Troubleshoot bayesdfa installation: missing rstantools

    main

    When installing bayesdfa (version 1.3.4) via Devel or CRAN, installation may fail if the rstantools package is not present in the environment. The error manifests as: Error in loadNamespace(x) : there is no package called ‘rstantools’.

    # Error observed during installation
Error in loadNamespace(x) : there is no package called ‘rstantools'

  7. Troubleshoot incompatible type errors in vctrs

    main

    When using functions like vctrs::list_unchop(), you may encounter errors if the elements being combined cannot be cast to the target prototype type. A common error signature is:

    Error in vctrs::list_unchop(ret, ptype = vctrs::vec_ptype(x)): Can't convert x[[1]] <double> to <character>.

    This indicates a type mismatch between the existing prototype and the new data being introduced. This error is surfaced through the vctrs_error_cast and vctrs_error_incompatible_type error classes.

    # Example of the error pattern seen in orderly (2.0.0)
vctrs::list_unchop(ret, ptype = vctrs::vec_ptype(x))
# Error: Can't convert `x[[1]]` <double> to <character>.

  8. Troubleshoot h3o and rshift installation: Cargo lock file version mismatch

    main

    Packages h3o (0.3.0) and rshift (3.1.2) that utilize Rust components may fail during compilation. The error occurs when the Cargo.lock file version is incompatible with the installed Rust toolchain. Specifically, lock file version 4 requires -Znext-lockfile-bump.

    error: failed to parse lock file at: .../Cargo.lock

Caused by:
  lock file version 4 requires `-Znext-lockfile-bump`
make: *** [Makevars:26: rust/target/release/libh3o.a] Error 101
ERROR: compilation failed for package ‘h3o’

  9. Troubleshoot loon.shiny installation: missing dependencies

    main

    Installation of loon.shiny (1.0.4) fails if required dependencies are not available in the R library. The error indicates that loon and loon.ggplot are required but cannot be found.

    * checking package dependencies ... ERROR
Packages required but not available: 'loon', 'loon.ggplot'

  10. Use vctrs for size and type operations

    main

    The vctrs package provides functions to determine common sizes, common prototypes, and perform common type casting across multiple vectors.

    Common Size and Recycling

    Use vec_size_common() to find the common size of multiple vectors, and vec_recycle_common() to recycle vectors to a common size.

    Common Prototypes and Casting

    Use vec_ptype_common() to find the common prototype (type) of multiple vectors, and vec_cast_common() to cast vectors to a common type.

    library(vctrs)

# Sizes
vec_size_common(1, 1:10)
#> [1] 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

# Prototypes
vec_ptype_common(FALSE, 1L, 2.5)
#> numeric(0)

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