pins

The pins package publishes data, models, and other R objects, making iteasy to share them across projects and with your colleagues. You can pinobjects to a variety of pin boards, including folders (to share on anetworked drive or with services like DropBox), RStudio Connect, AmazonS3, Azure storage and Microsoft 365 (OneDrive and SharePoint). Pins canbe automatically versioned, making it straightforward to track changes,re-run analyses on historical data, and undo mistakes.

pins 1.0.0 includes a new more explicit API and greater support forversioning. The legacy API (pin(), pin_get(), andboard_register()) will continue to work, but new features will only beimplemented with the new API, so we encourage you to switch to themodern API as quickly as possible. Learn more invignette("pins-update").

Installation

To try out the development version of pins (which will become pins 1.0.0when released), you’ll need to install from GitHub:

remotes::install_github("rstudio/pins")

If you discover this breaks any of your existing code, please let usknow then revert to thereleased version:

install.packages("pins")

Usage

To use the pins package, you must first create a pin board. A good placeto start is board_folder(), which stores pins in a directory youspecify. Here I’ll use a special version of board_folder() calledboard_temp() which creates a temporary board that’s automaticallydeleted when your R session ends. This is great for examples, butobviously you shouldn’t use it for real work!

library(pins)

board <- board_temp()
board
#> Pin board <pins_board_folder>
#> Path: '/tmp/RtmpxQu94x/pins-15f1d4a0c4d71'
#> Cache size: 0

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

board %>% pin_write(head(mtcars), "mtcars")
#> Guessing `type = 'rds'`
#> Creating new version '20210929T184444Z-f8797'

As you can see, the data saved as an .rds by default, but depending onwhat you’re saving and who else you want to read it, you might use thetype argument to instead save it as a csv, json, or arrow 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

A board on your computer is good place to start, but the real power ofpins comes when you use a board that’s shared with multiple people. Toget started, you can use board_folder() with a directory on a shareddrive or in dropbox, or if you use RStudioConnect you can useboard_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 yourpin:

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

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

The pins package also includes boards that allow you to share data onservices like Amazon’s S3 (board_s3()), Azure’s blob storage(board_azure()), and Microsoft SharePoint (board_ms365()). Learnmore in vignette("pins").