Type:	Package
Title:	Pin, Discover, and Share Resources
Version:	1.4.1
Description:	Publish data sets, 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 "boards", including local folders (to share on a networked drive or with 'DropBox'), 'Posit Connect', 'AWS S3', and more.
License:	Apache License (≥ 2)
URL:	https://pins.rstudio.com/, https://github.com/rstudio/pins-r
BugReports:	https://github.com/rstudio/pins-r/issues
Depends:	R (≥ 3.6)
Imports:	cli, digest, fs, generics, glue, httr, jsonlite, lifecycle, magrittr, purrr (≥ 1.0.0), rappdirs, rlang (≥ 1.1.0), tibble, whisker, withr (≥ 2.4.3), yaml
Suggests:	archive, arrow, AzureStor, covr, data.table, datasets, filelock, gitcreds, googleCloudStorageR, googledrive, httr2, ids, knitr, Microsoft365R, mime, mockery, nanoparquet, openssl, paws.storage, qs, R.utils, rmarkdown, rsconnect, shiny, sodium, testthat (≥ 3.1.7), webfakes (≥ 1.2.0), xml2, zip
VignetteBuilder:	knitr
Config/Needs/website:	tidyverse/tidytemplate
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-04-30 01:40:13 UTC; juliasilge
Author:	Julia Silge [cre, aut], Hadley Wickham [aut], Javier Luraschi [aut], Posit Software, PBC [cph, fnd]
Maintainer:	Julia Silge <julia.silge@posit.co>
Repository:	CRAN
Date/Publication:	2025-04-30 02:30:06 UTC

pins: Pin, Discover, and Share Resources

Description

Publish data sets, 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 "boards", including local folders (to share on a networked drive or with 'DropBox'), 'Posit Connect', 'AWS S3', and more.

Author(s)

Maintainer: Julia Silge julia.silge@posit.co (ORCID)

Authors:

• Hadley Wickham hadley@posit.co (ORCID)

• Javier Luraschi jluraschi@gmail.com

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://pins.rstudio.com/

• https://github.com/rstudio/pins-r

• Report bugs at https://github.com/rstudio/pins-r/issues

Use an Azure storage container as a board

Description

Pin data to a container in Azure storage using the AzureStor package.

Usage

board_azure(
  container,
  path = "",
  n_processes = 10,
  versioned = TRUE,
  cache = NULL
)

Arguments

Details

You can create a board in any of the services that AzureStor supports: blob storage, file storage and Azure Data Lake Storage Gen2 (ADLSgen2).

Blob storage is the classic storage service that is most familiar to people, but is relatively old and inefficient. ADLSgen2 is a modern replacement API for working with blobs that is much faster when working with directories. You should consider using this rather than the classic blob API where possible; see the examples below.

board_azure() is powered by the AzureStor package, which is a suggested dependency of pins (not required for pins in general). If you run into errors when deploying content to a server like https://www.shinyapps.io or Connect, add requireNamespace("AzureStor") to your app or document for automatic dependency discovery.

Examples

if (requireNamespace("AzureStor")) {
  # Public access board
  url <- "https://pins.blob.core.windows.net/public-data"
  container <- AzureStor::blob_container(url)
  board <- board_azure(container)
  board %>% pin_read("mtcars")
}

## Not run: 
# To create a board that you can write to, you'll need to supply one
# of `key`, `token`, or `sas` to AzureStor::blob_container()
# First, we create a board using the classic Azure blob API
url <- "https://myaccount.blob.core.windows.net/mycontainer"
container <- AzureStor::blob_container(url, sas = "my-sas")
board <- board_azure(container, "path/to/board")
board %>% pin_write(iris)

# ADLSgen2 is a modern, efficient way to access blobs
# - Use 'dfs' instead of 'blob' in the account URL to use the ADLSgen2 API
# - Use the 'storage_container' generic instead of the service-specific
#   'blob_container'
# - We reuse the board created via the blob API above
adls_url <- "https://myaccount.dfs.core.windows.net/mycontainer"
container <- AzureStor::storage_container(adls_url, sas = "my-sas")
board <- board_azure(container, "path/to/board")
board %>% pin_list()
board %>% pin_read("iris")

## End(Not run)

Retrieve default cache path

Description

Retrieves the default path used to cache boards and pins. Makes use of rappdirs::user_cache_dir() for cache folders defined by each OS. Remember that you can set the cache location for an individual board object via the cache argument.

Usage

board_cache_path(name)

Arguments

Details

There are several environment variables available to control the location of the default pins cache:

• Use PINS_CACHE_DIR to set the cache path for only pins functions

• Use R_USER_CACHE_DIR to set the cache path for all functions that use rappdirs

On system like AWS Lambda that is read only (for example, only ⁠/tmp⁠ is writeable), set either of these to base::tempdir(). You may also need to set environment variables like HOME and/or R_USER_DATA_DIR to the session temporary directory.

Examples

# retrieve default cache path
board_cache_path("local")

# set with env vars:
withr::with_envvar(
  c("PINS_CACHE_DIR" = "/path/to/cache"),
  board_cache_path("local")
)
withr::with_envvar(
  c("R_USER_CACHE_DIR" = "/path/to/cache"),
  board_cache_path("local")
)

Use Posit Connect as board

Description

To use a Posit Connect board, you need to first authenticate. The easiest way to do so is using the RStudio IDE and choosing Tools - Global Options - Publishing - Connect, then following the instructions.

You can share pins with others in Posit Connect by changing the viewers of the document to specific users or groups. This is accomplished by opening the new published pin and then changing access under the settings tab. After you've shared the pin, it will be automatically available to others.

Usage

board_connect(
  auth = c("auto", "manual", "envvar", "rsconnect"),
  server = NULL,
  account = NULL,
  key = NULL,
  cache = NULL,
  name = "posit-connect",
  versioned = TRUE,
  use_cache_on_failure = is_interactive()
)

board_rsconnect(
  auth = c("auto", "manual", "envvar", "rsconnect"),
  server = NULL,
  account = NULL,
  key = NULL,
  output_files = FALSE,
  cache = NULL,
  name = "posit-connect",
  versioned = TRUE,
  use_cache_on_failure = is_interactive()
)

Arguments

Public pins

If your Posit Connect instance allows it, you can share a pin publicly by setting the access type to all:

board %>% pin_write(my_df, access_type = "all")

(You can also do this in Posit Connect by setting "Access" to "Anyone - no login required")

Now anyone can read your pin through board_url():

board <- board_url(c(
  numbers = "https://pub.current.posit.team/public/great-numbers/"
))
board %>% pin_read("numbers")

You can find the URL of a pin with pin_browse().

HTML preview

When you write a pin to Posit Connect, a landing page is created and published together with the pin file. This HTML landing page shows a table preview for rectangular data, but you can opt out of the table preview:

board %>% pin_write(my_df, preview_data = FALSE)

See Also

Other boards: board_connect_url(), board_folder(), board_url()

Examples

## Not run: 
board <- board_connect()
# Share the mtcars with your team
board %>% pin_write(mtcars, "mtcars")

# Download a shared dataset
board %>% pin_read("timothy/mtcars")

## End(Not run)

Use a vector of Posit Connect vanity URLs as a board

Description

board_connect_url() lets you build up a board from individual vanity urls.

board_connect_url() is read only, and does not support versioning.

Usage

board_connect_url(
  vanity_urls,
  cache = NULL,
  use_cache_on_failure = is_interactive(),
  headers = connect_auth_headers()
)

connect_auth_headers(key = Sys.getenv("CONNECT_API_KEY"))

Arguments

Details

This board is a thin wrapper around board_url() which uses connect_auth_headers() for authentication via environment variable.

See Also

Other boards: board_connect(), board_folder(), board_url()

Examples

connect_auth_headers()

board <- board_connect_url(c(
    my_vanity_url_pin = "https://pub.current.posit.team/public/great-numbers/"
))

board %>% pin_read("my_vanity_url_pin")

Use a Databricks Volume as a board

Description

Pin data to a Databricks Volume

Usage

board_databricks(
  folder_url,
  host = NULL,
  prefix = NULL,
  versioned = TRUE,
  cache = NULL
)

Arguments

Authentication

board_databricks() searches for an authentication token in three different places, in this order:

• 'DATABRICKS_TOKEN' environment variable

• 'CONNECT_DATABRICKS_TOKEN' environment variable

• OAuth Databricks token inside the RStudio API

In most cases, the authentication will be a Personal Authentication Token ('PAT') that is saved as the 'DATABRICKS_TOKEN' environment variable. To obtain a 'PAT' see: Databricks personal access token authentication.

Details

• The functions in pins do not create a new Databricks Volume.

• board_databricks() is powered by the httr2 package, which is a suggested dependency of pins (not required for pins in general). If you run into errors when deploying content to a server like https://www.shinyapps.io or Connect, add requireNamespace("httr2") to your app or document for automatic dependency discovery.

Examples

## Not run: 
board <- board_databricks("/Volumes/my-catalog/my-schema/my-volume")
board %>% pin_write(mtcars)
board %>% pin_read("mtcars")

# A prefix allows you to have multiple independent boards in the same folder.
project_1 <- board_databricks(
  folder_url = "/Volumes/my-catalog/my-schema/my-volume",
  prefix = "project1/"
)
project_2 <- board_databricks(
  folder_url = "/Volumes/my-catalog/my-schema/my-volume",
  prefix = "project2/"
)

## End(Not run)

Deparse a board object

Description

Returns the R code that would recreate the board when re-run on another computer. Goal is to capture the location of the board, but not the authorisation, since (a) that would leak credentials and (b) in most deployment scenarios board auth will be read from env vars.

Usage

board_deparse(board, ...)

## S3 method for class 'pins_board_azure'
board_deparse(board, ...)

## S3 method for class 'pins_board_connect'
board_deparse(board, ...)

## S3 method for class 'pins_board_folder'
board_deparse(board, ...)

## S3 method for class 'pins_board_gcs'
board_deparse(board, ...)

## S3 method for class 'pins_board_kaggle_competition'
board_deparse(board, ...)

## S3 method for class 'pins_board_kaggle_dataset'
board_deparse(board, ...)

## S3 method for class 'pins_board_s3'
board_deparse(board, ...)

## S3 method for class 'pins_board_url'
board_deparse(board, ...)

Arguments

Value

A call.

Examples

## Not run: 
board <- board_connect()
# Generate code to access this board from elsewhere
board_deparse(board)

## End(Not run)

Use a local folder as board

Description

• board_folder() creates a board inside a folder. You can use this to share files by using a folder on a shared network drive or inside a DropBox.

• board_local() creates a board in a system data directory. It's useful if you want to share pins between R sessions on your computer, and you don't care where the data lives.

• board_temp() creates a temporary board that lives in a session specific temporary directory. It will be automatically deleted once the current R session ends. It's useful for examples and tests.

Usage

board_folder(path, versioned = FALSE)

board_local(versioned = FALSE)

board_temp(versioned = FALSE)

Arguments

See Also

Other boards: board_connect(), board_connect_url(), board_url()

Examples

# session-specific local board
board <- board_temp()

Use a Google Cloud Storage bucket as a board

Description

Pin data to a Google Cloud Storage bucket using the googleCloudStorageR package.

Usage

board_gcs(bucket, prefix = NULL, versioned = TRUE, cache = NULL)

Arguments

Authentication

board_gcs() is powered by the googleCloudStorageR package which provides several authentication options, as documented in its main vignette. The two main options are to create a service account key (a JSON file) or an authentication token; you can manage either using the gargle package.

Details

• The functions in pins do not create a new bucket. You can create a new bucket from R with googleCloudStorageR::gcs_create_bucket().

• You can pass arguments for googleCloudStorageR::gcs_upload such as predefinedAcl and upload_type through the dots of pin_write().

• board_gcs() is powered by the googleCloudStorageR package, which is a suggested dependency of pins (not required for pins in general). If you run into errors when deploying content to a server like https://www.shinyapps.io or Connect, add requireNamespace("googleCloudStorageR") to your app or document for automatic dependency discovery.

Examples

## Not run: 
board <- board_gcs("pins-testing")
board %>% pin_write(mtcars)
board %>% pin_read("mtcars")

# A prefix allows you to have multiple independent boards in the same pin.
board_sales <- board_gcs("company-pins", prefix = "sales/")
board_marketing <- board_gcs("company-pins", prefix = "marketing/")
# You can make the hierarchy arbitrarily deep.

# Pass arguments like `predefinedAcl` through the dots of `pin_write`:
board %>% pin_write(mtcars, predefinedAcl = "publicRead")

## End(Not run)

Use a Google Drive folder as a board

Description

Pin data to a folder in Google Drive using the googledrive package.

Usage

board_gdrive(path, versioned = TRUE, cache = NULL)

Arguments

Details

• The functions in pins do not create a new Google Drive folder. You can create a new folder from R with googledrive::drive_mkdir(), and then set the sharing for your folder with googledrive::drive_share().

• If you have problems with authentication to Google Drive, learn more at googledrive::drive_auth().

• board_gdrive() is powered by the googledrive package, which is a suggested dependency of pins (not required for pins in general). If you run into errors when deploying content to a server like https://www.shinyapps.io or Connect, add requireNamespace("googledrive") to your app or document for automatic dependency discovery.

Examples

## Not run: 
board <- board_gdrive("folder-for-my-pins")
board %>% pin_write(1:10, "great-integers", type = "json")
board %>% pin_read("great-integers")

## End(Not run)

Use kaggle datasets/competitions as a board

Description

These functions are no longer supported because of changes to the Kaggle API and will be removed in a future version of pins. We recommend that you use the Kaggle CLI instead.

board_kaggle_competition() allows you to treat a Kaggle competition like a read-only board, making it easy get the data on to your computer. board_kaggle_dataset() lets you upload and download files to and from a kaggle dataset. Data is only re-downloaded when it changes.

These boards work best with pin_download() and pin_upload() since pin_read() and pin_write() are not a good fit to the Kaggle model.

Usage

board_kaggle_competitions(username = NULL, key = NULL, cache = NULL)

## S3 method for class 'pins_board_kaggle_competition'
pin_search(
  board,
  search = NULL,
  sort_by = c("grouped", "prize", "earliestDeadline", "latestDeadline", "numberOfTeams",
    "recentlyCreated"),
  page = 1,
  user = NULL,
  ...
)

board_kaggle_dataset(username = NULL, key = NULL, cache = NULL)

## S3 method for class 'pins_board_kaggle_dataset'
pin_search(
  board,
  search = NULL,
  sort_by = c("hottest", "votes", "updated", "active"),
  page = 1,
  user = NULL,
  ...
)

## S3 method for class 'pins_board_kaggle_dataset'
pin_store(
  board,
  name,
  paths,
  metadata,
  versioned = NULL,
  ...,
  private = TRUE,
  license = "CC0-1.0"
)

Arguments

Examples

## Not run: 
board <- board_kaggle_competitions()
board

board %>% pin_meta("titanic")
paths <- board %>% pin_download("titanic")
paths
head(read.csv(paths[[1]]))
head(read.csv(paths[[2]]))

## End(Not run)
## Not run: 
board <- board_kaggle_dataset()

board %>% pin_search("cats")
board %>% pin_exists("rturley/pet-breed-characteristics")
board %>% pin_meta("rturley/pet-breed-characteristics")
board %>% pin_versions("rturley/pet-breed-characteristics")

board %>% pin_versions("imsparsh/animal-breed-cats-and-dogs")

## End(Not run)

Use a OneDrive or Sharepoint document library as a board

Description

Pin data to a folder in Onedrive or a SharePoint Online document library using the Microsoft365R package.

Usage

board_ms365(
  drive,
  path,
  versioned = TRUE,
  cache = NULL,
  delete_by_item = FALSE
)

Arguments

Details

Sharing a board in OneDrive (personal or business) is a bit complicated, as OneDrive normally allows only the person who owns the drive to access files and folders. First, the drive owner has to set the board folder as shared with other users, using either the OneDrive web interface or Microsoft365R's ms_drive_item$create_share_link() method. The other users then call board_ms365 with a drive item object in the path argument, pointing to the shared folder. See the examples below.

Sharing a board in SharePoint Online is much more straightforward, assuming all users have access to the document library: in this case, everyone can use the same call board_ms365(doclib, "path/to/board"). If you want to share a board with users outside your team, follow the same steps for sharing a board in OneDrive.

board_ms365() is powered by the Microsoft365R package, which is a suggested dependency of pins (not required for pins in general). If you run into errors when deploying content to a server like https://www.shinyapps.io or Connect, add requireNamespace("Microsoft365R") to your app or document for automatic dependency discovery.

Examples

## Not run: 
# A board in your personal OneDrive
od <- Microsoft365R::get_personal_onedrive()
board <- board_ms365(od, "myboard")
board %>% pin_write(iris)

# A board in OneDrive for Business
odb <- Microsoft365R::get_business_onedrive(tenant = "mytenant")
board <- board_ms365(odb, "myproject/board")

# A board in a SharePoint Online document library
sp <- Microsoft365R::get_sharepoint_site("my site", tenant = "mytenant")
doclib <- sp$get_drive()
board <- board_ms365(doclib, "general/project1/board")


## Sharing a board in OneDrive:
# First, create the board on the drive owner's side
board <- board_ms365(od, "myboard")

# Next, let other users write to the folder
# - set the expiry to NULL if you want the folder to be permanently available
od$get_item("myboard")$create_share_link("edit", expiry="30 days")

# On the recipient's side: find the shared folder item, then pass it to board_ms365
shared_items <- od$list_shared_items()
board_folder <- shared_items$remoteItem[[which(shared_items$name == "myboard")]]
board <- board_ms365(od, board_folder)

## End(Not run)

Custom Boards

Description

Usage

board_pin_create(board, path, name, metadata, ...)

board_initialize(board, ...)

board_browse(board, ...)

board_desc(board, ...)

board_pin_get(board, name, ...)

board_pin_remove(board, name, ...)

board_pin_find(board, text, ...)

board_pin_versions(board, name, ...)

Arguments

Details

Family of functions meant to be used to implement custom boards extensions, not to be used by users.

Board registry (legacy API)

Description

The legacy pins API uses a board registry, where you first register a board then refer to it by name in calls to pin functions.

Usage

board_register(board, name = NULL, cache = NULL, versions = NULL, ...)

board_register_rsconnect(
  name = "rsconnect",
  server = NULL,
  account = NULL,
  key = NULL,
  output_files = FALSE,
  cache = NULL,
  ...
)

board_deregister(name, ...)

board_default()

board_list()

board_get(name)

Examples

# legacy API
board_register_local("myboard", cache = tempfile())
pin(mtcars, board = "myboard")
pin_get("mtcars", board = "myboard")

# modern API (not available for all boards)
board <- board_temp()
board %>% pin_write(mtcars)
board %>% pin_read("mtcars")

Use an S3 bucket as a board

Description

Pin data to an S3-compatible storage bucket, such as on Amazon's S3 service, MinIO, or Digital Ocean, using the paws.storage package.

Usage

board_s3(
  bucket,
  prefix = NULL,
  versioned = TRUE,
  access_key = NULL,
  secret_access_key = NULL,
  session_token = NULL,
  credential_expiration = NULL,
  profile = NULL,
  region = NULL,
  endpoint = NULL,
  cache = NULL
)

Arguments

Authentication

board_s3() is powered by the paws package which provides a wide range of authentication options, as documented at https://github.com/paws-r/paws/blob/main/docs/credentials.md. In brief, there are four main options that are tried in order:

• The access_key and secret_access_key arguments to this function. If you have a temporary session token, you'll also need to supply session_token and credential_expiration. (Not recommended since your secret_access_key will be recorded in .Rhistory)

• The AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY env vars. (And AWS_SESSION_TOKEN and AWS_CREDENTIAL_EXPIRATION env vars if you have a temporary session token)

• The AWS shared credential file, ⁠~/.aws/credentials⁠:

  [profile-name]
  aws_access_key_id=your AWS access key
  aws_secret_access_key=your AWS secret key
  

  The "default" profile will be used if you don't supply the access key and secret access key as described above. Otherwise you can use the profile argument to use a profile of your choice.

• Automatic authentication from EC2 instance or container IAM role.

See the paws documentation for more unusual options including getting credentials from a command line process, picking a role when running inside an EC2 instance, using a role from another profile, and using multifactor authentication.

Details

• The functions in pins do not create a new bucket. You can create a new bucket from R with paws.

• Some functions like pin_list() will work for an S3 board, but don't return useful output.

• You can pass arguments for paws.storage::s3_put_object such as Tagging and ServerSideEncryption through the dots of pin_write(). (Note that these are separate from pin_write() arguments like tags.)

• You can use board_s3() with S3-compatible object storage on non-AWS platforms such as MinIO and Digital Ocean. For this type of object storage, use the full URL (including scheme like ⁠https://⁠) of the storage endpoint.

• board_s3() is powered by the paws.storage package, which is a suggested dependency of pins (not required for pins in general). If you run into errors when deploying content to a server like https://www.shinyapps.io or Connect, add requireNamespace("paws.storage") to your app or document for automatic dependency discovery.

Examples

## Not run: 
board <- board_s3("pins-test-hadley", region = "us-east-2")
board %>% pin_write(mtcars)
board %>% pin_read("mtcars")

# A prefix allows you to have multiple independent boards in the same pin.
board_sales <- board_s3("company-pins", prefix = "sales/")
board_marketing <- board_s3("company-pins", prefix = "marketing/")
# You can make the hierarchy arbitrarily deep.

# Pass S3 arguments like `Tagging` through the dots of `pin_write`:
board %>% pin_write(mtcars, Tagging = "key1=value1&key2=value2")


## End(Not run)

Test Board

Description

Usage

board_test(board, exclude = list(), suite = c("default", "versions"))

Arguments

Details

Tests a particular board, useful only when creating new boards.

Use a vector of URLs as a board

Description

board_url() lets you build up a board from individual urls or a manifest file.

board_url() is read only.

Usage

board_url(
  urls,
  cache = NULL,
  use_cache_on_failure = is_interactive(),
  headers = NULL
)

Arguments

Details

The way board_url() works depends on the type of the urls argument:

• Unnamed character scalar, i.e. a single URL to a manifest file: If the URL ends in a /, board_url() will look for a ⁠_pins.yaml⁠ manifest. If the manifest file parses to a named list, versioning is supported. If it parses to a named character vector, the board will not support versioning.

• Named character vector of URLs: If the URLs end in a /, board_url() will look for a data.txt that provides metadata for the associated pin. The easiest way to generate this file is to upload a pin version directory created by board_folder(). Versioning is not supported.

• Named list, where the values are character vectors of URLs and each element of the vector refers to a version of the particular pin: If a URL ends in a /, board_url() will look for a data.txt that provides metadata. Versioning is supported.

Using a vector of URLs can be useful because pin_download() and pin_read() will be cached; they'll only re-download the data if it's changed from the last time you downloaded it (using the tools of HTTP caching). You'll also be protected from the vagaries of the internet; if a fresh download fails, you'll get the previously cached result with a warning.

Using a manifest file can be useful because you can serve a board of pins and allow collaborators to access the board straight from a URL, without worrying about board-level storage details. Some examples are provided in vignette("using-board-url").

Authentication for board_url()

The headers argument allows you to pass authentication details or other HTTP headers to the board, such as for a Posit Connect vanity URL that is not public (see board_connect_url()) or a private GitHub repo.

gh_pat_auth <- c(
  Authorization = paste("token", "github_pat_XXXX")
)
board <- board_url(
  "https://raw.githubusercontent.com/username/repo/main/path/to/pins",
  headers = gh_pat_auth
)

board %>% pin_list()

See Also

Other boards: board_connect(), board_connect_url(), board_folder()

Examples

github_raw <- function(x) paste0("https://raw.githubusercontent.com/", x)

## with a named vector of URLs to specific pins:
b1 <- board_url(c(
  files = github_raw("rstudio/pins-r/main/tests/testthat/pin-files/"),
  rds = github_raw("rstudio/pins-r/main/tests/testthat/pin-rds/"),
  raw = github_raw("rstudio/pins-r/main/tests/testthat/pin-files/first.txt")
))

b1 %>% pin_read("rds")
b1 %>% pin_browse("rds", local = TRUE)

b1 %>% pin_download("files")
b1 %>% pin_download("raw")

## with a manifest file:
b2 <- board_url(github_raw("rstudio/pins-r/main/tests/testthat/pin-board/"))
b2 %>% pin_list()
b2 %>% pin_versions("y")

Cache management

Description

Most boards maintain a local cache so that if you're reading a pin that hasn't changed since the last time you read it, it can be rapidly retrieved from a local cache. These functions help you manage that cache.

• cache_browse(): open the cache directory for interactive exploration.

• cache_info(): report how much disk space each board's cache uses.

• cache_prune(): delete pin versions that you haven't used for days (you'll be asked to confirm before the deletion happens).

In general, there's no real harm to deleting the cached pins, as they'll be re-downloaded as needed. The one exception is legacy_local() which mistakenly stored its pinned data in the cache directory; do not touch this directory.

Usage

cache_browse()

cache_info()

cache_prune(days = 30)

Arguments

Azure board (legacy API)

Description

To use Microsoft Azure Storage as a board, you'll need an Azure Storage account, an Azure Storage container, and an Azure Storage key.

Usage

legacy_azure(
  container = Sys.getenv("AZURE_STORAGE_CONTAINER"),
  account = Sys.getenv("AZURE_STORAGE_ACCOUNT"),
  key = Sys.getenv("AZURE_STORAGE_KEY"),
  cache = NULL,
  name = "azure",
  ...
)

board_register_azure(
  name = "azure",
  container = Sys.getenv("AZURE_STORAGE_CONTAINER"),
  account = Sys.getenv("AZURE_STORAGE_ACCOUNT"),
  key = Sys.getenv("AZURE_STORAGE_KEY"),
  cache = NULL,
  path = NULL,
  ...
)

Arguments

Examples

## Not run: 
# the following example requires an Azure Storage key
board_register_azure(
  container = "pinscontainer",
  account = "pinsstorage",
  key = "abcabcabcabcabcabcabcabcabcab=="
)

## End(Not run)

Remote "data.txt" board (legacy API)

Description

Usage

legacy_datatxt(
  url,
  headers = NULL,
  cache = NULL,
  needs_index = TRUE,
  browse_url = url,
  index_updated = NULL,
  index_randomize = FALSE,
  path = NULL,
  versions = FALSE,
  name = NULL,
  ...
)

board_register_datatxt(url, name = NULL, headers = NULL, cache = NULL, ...)

Arguments

Details

Use board that for a website that uses the data.txt specification. A data.txt file is a YAML that provides some basic metadata about a directory of files.

Examples

# register website board using datatxt file
board_register_datatxt(
  url = "https://datatxt.org/data.txt",
  name = "txtexample",
  cache = tempfile()
)

# find pins
pin_find(board = "txtexample")

DigitalOcean board (legacy API)

Description

Usage

legacy_dospace(
  space = Sys.getenv("DO_SPACE"),
  key = Sys.getenv("DO_ACCESS_KEY_ID"),
  secret = Sys.getenv("DO_SECRET_ACCESS_KEY"),
  datacenter = Sys.getenv("DO_DATACENTER"),
  cache = NULL,
  host = "digitaloceanspaces.com",
  name = "dospace",
  ...
)

board_register_dospace(
  name = "dospace",
  space = Sys.getenv("DO_SPACE"),
  key = Sys.getenv("DO_ACCESS_KEY_ID"),
  secret = Sys.getenv("DO_SECRET_ACCESS_KEY"),
  datacenter = Sys.getenv("DO_DATACENTER"),
  cache = NULL,
  host = "digitaloceanspaces.com",
  path = NULL,
  ...
)

Arguments

Details

To use DigitalOcean Spaces as a board, you first need an DigitalOcean space and a storage key. You can sign-up and create those at digitalocean.com.

Examples

## Not run: 
# the following example requires a DigitalOcean Spaces API key
board <- legacy_dospace(bucket = "s3bucket")

## End(Not run)

Google Cloud board (legacy API)

Description

Usage

legacy_gcloud(
  bucket = Sys.getenv("GCLOUD_STORAGE_BUCKET"),
  token = NULL,
  cache = NULL,
  name = "gcloud",
  ...
)

board_register_gcloud(
  name = "gcloud",
  bucket = Sys.getenv("GCLOUD_STORAGE_BUCKET"),
  token = NULL,
  cache = NULL,
  path = NULL,
  ...
)

Arguments

Details

To use a Google Cloud Storage board, you first need a Google Cloud Storage account, a Google Storage bucket, and an access token or the Google Cloud SDK properly installed and configured. You can sign-up and create these from https://console.cloud.google.com

Examples

## Not run: 
# the following example requires the Google Cloud SDK to be configured
board <- legacy_gcloud(container = "gcloudcontainer")

## End(Not run)

GitHub board (legacy API)

Description

Usage

legacy_github(
  repo,
  branch = NULL,
  token = NULL,
  path = "",
  host = "https://api.github.com",
  name = "github",
  cache = NULL,
  ...
)

board_register_github(
  name = "github",
  repo = NULL,
  branch = NULL,
  token = NULL,
  path = "",
  host = "https://api.github.com",
  cache = NULL,
  ...
)

Arguments

Details

To use a GitHub board, you'll need to set up authentication, following the instructions at https://happygitwithr.com/https-pat.html#https-pat.

Large Files

A GitHub repo only supports files under 25MB in size (100MB in theory but there is additional overhead when using the GitHub API). To store large files, GitHub recommends storing them using GitHub Releases which support up to 2GB files, which is what pins uses. You don't need to do anything extra as this will happen behind the scenes, but don't be surprised if pins creates releases in your repo.

Examples

## Not run: 
# the following example requires a GitHub API key
board <- legacy_github("owner/repo")

## End(Not run)

Kaggle board (legacy API)

Description

Usage

legacy_kaggle(token = NULL, name = "kaggle", ...)

board_register_kaggle(name = "kaggle", token = NULL, cache = NULL, ...)

Arguments

Details

These functions are no longer supported because of changes to the Kaggle API and will be removed in a future version of pins. We recommend that you use the Kaggle CLI instead.

To use a Kaggle board, you need to first download a token file from your account.

Sharing

When working in teams, you might want to share your pins with others. For You can do by adding users or making the dataset public on Kaggle's website.

Once you share with specific users, they can follow the same steps to register a Kaggle board which allows them to download and upload pins

Examples

## Not run: 
# the following example requires a Kaggle API token
board <- legacy_kaggle(token = "path/to/kaggle.json")

pin_find("crowdflower", board = board)

# names starting with c/ are competitions
pin_get("c/crowdflower-weather-twitter", board = board)

## End(Not run)

Local board (legacy API)

Description

legacy_local() powers board_register_local(), which allows you to access local pins created in earlier versions of the pins package. For new pins, we recommend that you transition to board_local() which supports the new pins API.

legacy_temp() creates a legacy board in a temporary location, for use in tests and examples.

Usage

legacy_local(path = NULL, name = "local", versions = FALSE)

board_register_local(name = "local", cache = NULL, ...)

legacy_temp(name = "temp", ...)

Arguments

Examples

## Not run: 
# Old api
pin(data.frame(x = 1:3), "test")
pin_get("test")

# New api
board <- board_local()
board %>% pin_write(data.frame(x = 1:3), "test")
board %>% pin_read("test")

## End(Not run)

S3 board (legacy API)

Description

To use an Amazon S3 Storage board, you need an Amazon S3 bucket and a user with enough permissions to access the S3 bucket. You can sign-up and create those at https://aws.amazon.com/. Note that it can take a few minutes after you've created it before a bucket is usable.

See board_s3() for a modern version of this legacy board.

Usage

legacy_s3(
  bucket = Sys.getenv("AWS_BUCKET"),
  key = Sys.getenv("AWS_ACCESS_KEY_ID"),
  secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"),
  cache = NULL,
  region = NULL,
  host = "s3.amazonaws.com",
  name = "s3",
  ...
)

board_register_s3(
  name = "s3",
  bucket = Sys.getenv("AWS_BUCKET"),
  key = Sys.getenv("AWS_ACCESS_KEY_ID"),
  secret = Sys.getenv("AWS_SECRET_ACCESS_KEY"),
  cache = NULL,
  host = "s3.amazonaws.com",
  region = NULL,
  path = NULL,
  ...
)

Arguments

Examples

## Not run: 
# the following example requires an Amazon S3 API key
board <- legacy_s3(bucket = "s3bucket")

## End(Not run)

Create a new board

Description

Create a new board

Usage

new_board(board, api, cache, ...)

new_board_v0(board, name, cache = NULL, versions = FALSE, ...)

new_board_v1(board, cache, versioned = FALSE, ...)

Arguments

Pin a resource (legacy API)

Description

Usage

pin(x, name = NULL, description = NULL, board = NULL, ...)

Arguments

Details

Pins the given resource locally or to the given board.

pin() allows you to cache remote resources and intermediate results with ease. When caching remote resources, usually URLs, it will check for HTTP caching headers to avoid re-downloading when the remote result has not changed.

This makes it ideal to support reproducible research by requiring manual instruction to download resources before running your R script.

In addition, pin() still works when working offline or when the remote resource becomes unavailable; when this happens, a warning will be triggered but your code will continue to work.

pin() stores data frames in two files, an R native file (RDS) and a 'CSV' file. To force saving a pin in R's native format only, you can use pin(I(data)). This can improve performance and size at the cost of making the pin unreadable from other tools and programming languages.

Examples

# old API
board_register_local(cache = tempfile())
pin(mtcars)
pin_get("mtcars")

# new api
board <- board_local()
board %>% pin_write(mtcars)
board %>% pin_read("mtcars")

Browse source of a pin

Description

pin_browse() navigates you to the home of a pin, either on the internet or on your local file system.

Usage

pin_browse(board, name, version = NULL, local = FALSE)

Arguments

Examples

board <- board_temp(versioned = TRUE)
board %>% pin_write(1:10, "x")
board %>% pin_write(1:11, "x")
board %>% pin_write(1:12, "x")

board %>% pin_browse("x", local = TRUE)

Create Pin Name

Description

Creates a pin name from an character expression generated with deparse(substitute(x)).

Usage

pin_default_name(x, board)

Arguments

Delete a pin

Description

Delete a pin (or pins), removing it from the board

Usage

pin_delete(board, names, ...)

Arguments

Examples

board <- board_temp()
board %>% pin_write(1:5, "x")
board %>% pin_write(mtcars)
board %>% pin_write(runif(1e6), "y")
board %>% pin_list()

board %>% pin_delete(c("x", "y"))
board %>% pin_list()

Upload and download files to and from a board

Description

This is a lower-level interface than pin_read() and pin_write() that you can use to pin any file, as opposed to any R object. The path returned by pin_download() is a read-only path to a cached file: you should never attempt to modify this file.

Usage

pin_download(board, name, version = NULL, hash = NULL, ...)

pin_upload(
  board,
  paths,
  name = NULL,
  ...,
  title = NULL,
  description = NULL,
  metadata = NULL,
  tags = NULL,
  urls = NULL
)

Arguments

Value

pin_download() returns a character vector of file paths; pin_upload() returns the fully qualified name of the new pin, invisibly.

Examples

board <- board_temp()

board %>% pin_upload(system.file("CITATION"))
path <- board %>% pin_download("CITATION")
path
readLines(path)[1:5]

Determine if a pin exists

Description

Determine if a pin exists

Usage

pin_exists(board, name, ...)

Arguments

Fetch/store a pin

Description

These are low-level functions that power pin_read(), pin_write(), pin_upload(), and pin_download(). They are needed primarily for folks developing new board types, and should not generally be called directly.

Usage

pin_fetch(board, name, version = NULL, ...)

pin_store(board, name, paths, metadata, versioned = NULL, x = NULL, ...)

Arguments

Value

pin_fetch() is called primarily for its side-effect of downloading remote pins into the local cache. It returns the same data as pin_meta. pin_store() is called for its side-effect of uploading a local file to a remote board. It invisibly returns the fully qualified pin name.

Examples

board <- board_temp()

board %>% pin_upload(system.file("CITATION"))
path <- board %>% pin_download("CITATION")
path
readLines(path)[1:5]

Search for pins (legacy API)

Description

Usage

pin_find(
  text = NULL,
  board = NULL,
  name = NULL,
  extended = FALSE,
  metadata = FALSE,
  ...
)

Arguments

Details

Search for pins in legacy boards.

Examples

pin_find("cars")
# ->
board <- board_local()
board %>% pin_search("cars")

Retrieve a pin (legacy API)

Description

Usage

pin_get(
  name,
  board = NULL,
  cache = TRUE,
  extract = NULL,
  version = NULL,
  files = FALSE,
  signature = NULL,
  ...
)

Arguments

Details

Retrieves a pin by name from the local or given board.

pin_get() retrieves a pin by name and, by default, from the local board. You can use the board parameter to specify which board to retrieve a pin from. If a board is not specified, it will use pin_find() to find the pin across all boards and retrieve the one that matches by name.

Examples

# define temporary board
board <- legacy_temp()
pin(mtcars, board = board)

# retrieve the mtcars pin
pin_get("mtcars", board = board)

Retrieve pin metadata (legacy API)

Description

Usage

pin_info(
  name,
  board = NULL,
  extended = TRUE,
  metadata = TRUE,
  signature = FALSE,
  ...
)

Arguments

Details

Retrieve metadata for pins in legacy boards.

Examples

# old API
board_register_local(cache = tempfile())
pin(mtcars)
pin_info("mtcars", "local")

# new API
board <- board_temp()
board %>% pin_write(mtcars)
board %>% pin_meta("mtcars")

List all pins

Description

List names of all pins in a board. This is a low-level function; use pin_search() to get more data about each pin in a convenient form.

Usage

pin_list(board, ...)

Arguments

Value

A character vector

Examples

board <- board_temp()

board %>% pin_write(1:5, "x")
board %>% pin_write(letters, "y")
board %>% pin_write(runif(20), "z")

board %>% pin_list()

Custom Pins

Description

Family of functions meant to be used to implement custom pin extensions, not to be used by users.

Usage

pin_load(path, ...)

board_pin_store(
  board,
  path,
  name,
  pin_metadata,
  extract = TRUE,
  retrieve = TRUE,
  zip = FALSE,
  cache = TRUE,
  metadata = NULL,
  custom_metadata = NULL,
  ...
)

Arguments

Pin Logging

Description

Log message for diagnosing the pins package.

Usage

pin_log(...)

Arguments

Retrieve metadata for a pin

Description

Pin metadata comes from three sources:

• Standard metadata added by pin_upload()/pin_write(). This includes:

  • ⁠$name⁠ - the pin's name.

  • ⁠$file⁠ - names of files stored in the pin.

  • ⁠$file_size⁠ - size of each file.

  • ⁠$pin_hash⁠ - hash of pin contents.

  • ⁠$type⁠ - type of pin: "rds", "csv", etc

  • ⁠$title⁠ - pin title

  • ⁠$description⁠ - pin description

  • ⁠$tags⁠ - pin tags

  • ⁠$urls⁠ - URLs for more info on pin

  • ⁠$created⁠ - date this (version of the pin) was created

  • ⁠$api_version⁠ - API version used by pin

• Metadata supplied by the user, stored in ⁠$user⁠. This is untouched from what is supplied in pin_write()/pin_upload() except for being converted to and from to YAML.

• Local metadata generated when caching the pin, stored in ⁠$local⁠. This includes information like the version of the pin, and the path its local cache.

Usage

pin_meta(board, name, version = NULL, ...)

Arguments

Value

A list.

Examples

b <- board_temp()
b %>% pin_write(head(mtcars), "mtcars", metadata = list("Hadley" = TRUE))

# Get the pin
b %>% pin_read("mtcars")
# Get its metadata
b %>% pin_meta("mtcars")
# Get path to underlying data
b %>% pin_download("mtcars")

# Use tags instead
b %>% pin_write(tail(mtcars), "mtcars", tags = c("fuel-efficiency", "automotive"))
b %>% pin_meta("mtcars")

Reactive Pin (legacy API)

Description

Usage

pin_reactive(name, board, interval = 5000, session = NULL, extract = NULL)

Arguments

Details

Creates a pin that reacts to changes in the given board by polling pin_get(), useful when used from the shiny package.

Wrap a pin in a reactive expression

Description

pin_reactive_read() and pin_reactive_download() wrap the results of pin_read() and pin_download() into a Shiny reactive. This allows you to use pinned data within your app, and have the results automatically recompute when the pin is modified.

Usage

pin_reactive_read(board, name, interval = 5000)

pin_reactive_download(board, name, interval = 5000)

Arguments

Examples

if (FALSE) {
  library(shiny)
  ui <- fluidPage(
    tableOutput("table")
  )

  server <- function(input, output, session) {
    board <- board_local()
    data <- pin_reactive_read(board, "shiny", interval = 1000)
    output$table <- renderTable(data())
  }
  shinyApp(ui, server)
}

Read and write objects to and from a board

Description

Use pin_write() to pin an object to board, and pin_read() to retrieve it.

Usage

pin_read(board, name, version = NULL, hash = NULL, ...)

pin_write(
  board,
  x,
  name = NULL,
  ...,
  type = NULL,
  title = NULL,
  description = NULL,
  metadata = NULL,
  versioned = NULL,
  tags = NULL,
  urls = NULL,
  force_identical_write = FALSE
)

Arguments

Details

pin_write() takes care of the details of serialising an R object to disk, controlled by the type argument. See pin_download()/pin_upload() if you want to perform the serialisation yourself and work just with files.

Value

pin_read() returns an R object read from the pin; pin_write() returns the fully qualified name of the new pin, invisibly.

Examples

b <- board_temp(versioned = TRUE)

b %>% pin_write(1:10, "x", description = "10 numbers")
b

b %>% pin_meta("x")
b %>% pin_read("x")

# Add a new version
b %>% pin_write(2:11, "x")
b %>% pin_read("x")

# Retrieve an older version
b %>% pin_versions("x")
b %>% pin_read("x", version = .Last.value$version[[1]])
# (Normally you'd specify the version with a string, but since the
# version includes the date-time I can't do that in an example)

Delete a pin (legacy API)

Description

Usage

pin_remove(name, board = NULL)

Arguments

Details

Deletes pins from a legacy board.

Examples

# old API
board_register_local(cache = tempfile())
pin(mtcars)
pin_remove("mtcars")

# new API
board <- board_local()
board %>% pin_write(mtcars)
board %>% pin_delete("mtcars")

Search for pins

Description

The underlying search method depends on the board, but most will search for text in the pin name and title.

Usage

pin_search(board, search = NULL, ...)

Arguments

Value

A data frame that summarises the metadata for each pin. Key attributes (name, type, description, created, and file_size) are pulled out into columns; everything else can be found in the meta list-column.

Examples

board <- board_temp()

board %>% pin_write(1:5, "x", title = "Some numbers")
board %>% pin_write(letters[c(1, 5, 10, 15, 21)], "y", title = "My favourite letters")
board %>% pin_write(runif(20), "z", title = "Random numbers")

board %>% pin_search()
board %>% pin_search("number")
board %>% pin_search("letters")

List, delete, and prune pin versions

Description

• pin_versions() lists available versions a pin.

• pin_versions_prune() deletes old versions.

• pin_version_delete() deletes a single version.

Usage

pin_versions(board, name, ...)

pin_version_delete(board, name, version, ...)

pin_versions_prune(board, name, n = NULL, days = NULL, ...)

Arguments

Value

A data frame with at least a version column. Some boards may provided additional data.

Examples

board <- board_temp(versioned = TRUE)

board %>% pin_write(data.frame(x = 1:5), name = "df")
board %>% pin_write(data.frame(x = 2:6), name = "df")
board %>% pin_write(data.frame(x = 3:7), name = "df")

# pin_read() returns the latest version by default
board %>% pin_read("df")

# but you can return earlier versions if needed
board %>% pin_versions("df")

ver <- pin_versions(board, "df")$version[[1]]
board %>% pin_read("df", version = ver)

# delete all versions created more than 30 days ago
board %>% pin_versions_prune("df", days = 30)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

generics

required_pkgs

magrittr

%>%

Determine required packages for a pins board

Description

Determine required packages for a pins board

Usage

## S3 method for class 'pins_board_azure'
required_pkgs(x, ...)

## S3 method for class 'pins_board_connect'
required_pkgs(x, ...)

## S3 method for class 'pins_board_databricks'
required_pkgs(x, ...)

## S3 method for class 'pins_board_gcs'
required_pkgs(x, ...)

## S3 method for class 'pins_board_gdrive'
required_pkgs(x, ...)

## S3 method for class 'pins_board_ms365'
required_pkgs(x, ...)

## S3 method for class 'pins_board_s3'
required_pkgs(x, ...)

## S3 method for class 'pins_board'
required_pkgs(x, ...)

Arguments

Value

A character vector of package names required to use the board.

Examples

required_pkgs(board_temp())

Write board manifest file to board's root directory

Description

A board manifest file records all the pins, along with their versions, stored on a board. This can be useful for a board built using, for example, board_folder() or board_s3(), then served as a website, such that others can consume using board_url(). The manifest file is not versioned like a pin is, and this function will overwrite any existing ⁠_pins.yaml⁠ file on your board. It is your responsibility as the user to keep the manifest up to date.

Some examples are provided in vignette("using-board-url").

Usage

write_board_manifest(board, ...)

Arguments

Details

This function is not supported for read-only boards. It is called for the side-effect of writing a manifest file, ⁠_pins.yaml⁠, to the root directory of the board. (This will not work in the unlikely event that you attempt to create a pin called "_pins.yaml".)

The behavior of the legacy API (for example, pin_find()) is unspecified once you have written a board manifest file to a board's root directory. We recommend you only use write_board_manifest() with modern boards.

Value

The board, invisibly

Examples

board <- board_temp()
pin_write(board, mtcars, "mtcars-csv", type = "csv")
pin_write(board, mtcars, "mtcars-json", type = "json")

write_board_manifest(board)

# see the manifest's format:
fs::path(board$path, "_pins.yaml") %>% readLines() %>% cat(sep = "\n")

# if you write another pin, the manifest file is out of date:
pin_write(board, 1:10, "nice-numbers", type = "json")

# you decide when to update the manifest:
write_board_manifest(board)

Write a manifest YAML file for a board

Description

This is a low-level function that powers write_board_manifest(). It is needed primarily for folks developing new board types, and should not generally be called directly.

Usage

write_board_manifest_yaml(board, manifest, ...)

Arguments

Value

write_board_manifest_yaml() is called for its side-effect of writing a manifest YAML file.