pins 1.0.0

Photo by Kelsey Knight on Unsplash

I’m delighted to announce that pins 1.0.0 is now available on CRAN. The pins package publishes data, models, and other R objects, making it easy to share them across projects and with your colleagues. You can pin objects to a variety of pin boards, including folders (to share on a networked drive or with services like DropBox), RStudio Connect, Amazon S3, and Azure blob storage. Pins can be versioned, making it straightforward to track changes, re-run analyses on historical data, and undo mistakes. Our users have found numerous ways to use this ability to fluently share and version data and other objects, such as automating ETL for a Shiny app.

You can install pins with:

install.packages("pins")

pins 1.0.0 includes a major overhaul of the API. The legacy API (pin(), pin_get(), board_register(), and friends) will continue to work, but new features will only be implemented with the new API, so we encourage you to switch to the modern API as quickly as possible. If you’re an existing pins user, you can learn more about the changes and how to update you code in vignette("pins-update").

Basics

To use the pins package, you must first create a pin board. A good place to start is board_folder(), which stores pins in a directory you specify. Here I’ll use a special version of board_folder() called board_temp() which creates a temporary board that’s automatically deleted when your R session ends. This is great for examples, but obviously you shouldn’t use it for real work!

library(pins)

board <- board_temp()
board
#> Pin board <pins_board_folder>
#> Path: '/tmp/RtmpLu2Bkx/pins-114af466104ab'
#> Cache size: 0

You can “pin” (save) data to a board with pin_write(). It takes three arguments: the board to pin to, an object, and a name:

board %>% pin_write(head(mtcars), "mtcars")
#> Guessing `type = 'rds'`
#> Creating new version '20211004T155644Z-f8797'
#> Writing to pin 'mtcars'

As you can see, the data saved as an .rds by default, but depending on what you’re saving and who else you want to read it, you might use the type argument to instead save it as a csv, json, arrow, or qs file.

You can later retrieve the pinned data with pin_read():

board %>% pin_read("mtcars")
#>                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
#> Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Sharing pins

A board on your computer is good place to start, but the real power of pins comes when you use a board that’s shared with multiple people. To get started, you can use board_folder() with a directory on a shared drive or using Dropbox, or if you use RStudio Connect you can use board_rsconnect():

board <- board_rsconnect()
#> Connecting to RSC 1.9.0.1 at <https://connect.rstudioservices.com>
board %>% pin_write(tidy_sales_data, "sales-summary", type = "rds")
#> Writing to pin 'hadley/sales-summary'

Then, someone else (or an automated Rmd report) can read and use your pin:

board <- board_rsconnect()
board %>% pin_read("hadley/sales-summary")

You can easily control who gets to access the data using the RStudio Connection permissions pane.

Other boards

As well as board_folder() and board_rsconnect(), pins 1.0.0 provides:

Future versions of the pins package are likely to include other backends as we learn from our users what would be most useful.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)