Quickly Evaluate Captured Side Effects

The purrr package allows you to capture the side effects (errors, warning, messages and other output) of functions using safely() and quietly(). Using collateral, you can quickly see which elements of a list (or list-column) returned results, which threw errors and which returned warnings or other output.

Automatically map complex operations safely or quietly, and quickly see the captured side effects.

The collateral package extends the power of purrr::safely() and purrr::quietly(), providing variants of map()map_safely() and map_quietly()—that automatically apply the appropriate function wrapper and print the resulting output nicely.

This is especially useful for tidy workflows: you can nest() a data frame, apply a complex operation (such as building a regression model or building and saving a plot) to each group and quickly see which groups need to be inspected in more detail:


We'll submit to CRAN soon, but for now, use devtools to install collateral:



test =
  # tidy up and trim down for the example
  mtcars %>%
  rownames_to_column(var = "car") %>%
  as_data_frame() %>%
  select(car, cyl, disp, wt) %>%
  # spike some rows in cyl == 4 to make them fail
  mutate(wt = dplyr::case_when(
    wt < 2 ~ -wt,
    TRUE ~ wt)) %>%
  # nest and do some operations quietly()
  nest(-cyl) %>%
  mutate(qlog = map_quietly(data, ~ log(.$wt)))
#> # A tibble: 3 x 4
#>     cyl data              qlog
#>   <dbl> <list>            <collat>
#> 1     6 <tibble [7 x 3]>  R O _ _
#> 2     4 <tibble [11 x 3]> R O _ W
#> 3     8 <tibble [14 x 3]> R O _ _

Example of styled  output

collateral uses pillar to style output, so supported terminals will also color the output! Properly styling knitted output is still on the to-do list, though.

If you're a fan of iterating over two or more inputs in lockstep, then map2() and pmap() variants are also provided:

  • map2_safely(),
  • map2_quietly(),
  • pmap_safely(), and
  • pmap_quietly().

collateral also provides tally_*() and has_() functions to help you filter or summarise your side effects, as well as a summary() mehod. If you haven't used a list-column workflow before, take a look at the vignette to see how it's done!


If you have a problem with collateral, please don't hesitate to file an issue or get in touch with me!


collateral 0.4.1

  • Added a NEWS.md file to track changes to the package.

collateral 0.4

  • Added has_*() functions for use with dplyr:filter().
  • Altered the tally_*() functions to use has_*() and the summary() methods to use tally_*().

collateral 0.3

  • Added tally_*() functions for use with dplyr::summarise().

collateral 0.2

  • Added summary() methods to report the count of types of side effects in a column.
  • Added a pkgdown site
  • Add a sick hex sticker!

collateral 0.1

  • Improved documentation
  • Lowered R version dependency

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.4.2 by James Goldie, 5 months ago

https://rensa.co/collateral/index.html, https://github.com/rensa/collateral

Report a bug at https://github.com/rensa/collateral/issues

Browse source code at https://github.com/cran/collateral

Authors: James Goldie [aut, cre]

Documentation:   PDF Manual  

GPL-3 | file LICENSE license

Imports purrr, crayon, methods, pillar

Suggests dplyr, knitr, magrittr, rmarkdown, tidyverse

See at CRAN