### Modern API Usage Example in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Demonstrates the usage of the new, explicit API introduced in pins 1.0.0. It shows how to create a local board object and then use it with pin_write() to save data and pin_read() to retrieve it.

```R
board <- board_local()
board %>% pin_write(mtcars, "mtcars")
board %>% pin_read("mtcars")
```

--------------------------------

### R: Upload with named tags and correct syntax in pin_upload

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin-upload-download.md

Demonstrates the correct usage of `pin_upload` with additional arguments, specifically `tags`, which must be named. This example shows how to provide metadata during the upload process.

```r
pin_upload(board, path, "test", c("blue", "green"))
```

--------------------------------

### Google Cloud Storage Board Setup and Usage with pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Details the process of setting up and using a Google Cloud Storage (GCS) bucket as a pin storage backend with the pins R package. It covers authentication using `googleCloudStorageR`, creating boards with prefixes, writing and reading pins, and passing GCS-specific options.

```r
library(pins)
library(googleCloudStorageR)

# Authenticate (see googleCloudStorageR documentation)
gcs_auth(json_file = "service-account.json")

# Create board
board <- board_gcs(bucket = "my-gcs-bucket")

# With prefix
board <- board_gcs(
  bucket = "company-data",
  prefix = "analysis/"
)

# Write and read
board |> pin_write(results, "experiment-1")
board |> pin_read("experiment-1")

# Pass GCS-specific options
board |> pin_write(
  public_data,
  "open-dataset",
  predefinedAcl = "publicRead"
)
```

--------------------------------

### Create and Use a Temporary Pin Board in R

Source: https://github.com/rstudio/pins-r/blob/main/README.md

Demonstrates creating a temporary pin board using `board_temp()`, writing data to it with `pin_write()`, and reading it back with `pin_read()`. Temporary boards are automatically deleted, suitable for examples and testing.

```r
library(pins)

board <- board_temp()
board
#> Pin board <pins_board_folder>
#> Path:
#> '/var/folders/hv/hzsmmyk9393_m7q3nscx1slc0000gn/T/RtmpYCNIH0/pins-28a721e60d44'
#> Cache size: 0

board |> pin_write(head(mtcars), "mtcars")
#> Guessing `type = 'rds'`
#> Creating new version '20250903T205250Z-1a718'
#> Writing to pin 'mtcars'

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
```

--------------------------------

### YAML Board Metadata - GitHub Example with Attributes

Source: https://github.com/rstudio/pins-r/wiki/Metadata

Illustrates an extended board metadata file for a GitHub board, including additional attributes like name, rows, columns, description, and type for each dataset. These attributes enhance searchability and UI previews.

```yaml
- path: iris/data.csv
  name: iris
  rows: 150
  cols: 5
  description: This famous (Fisher's or Anderson's) iris data set gives the measurements
    in centimeters of the variables sepal length and width and petal length and width,
    respectively, for 50 flowers from each of 3 species of iris. The species are Iris
    setosa, versicolor, and virginica.
  type: table
- path: mtcars/data.csv
  name: mtcars
  rows: 32
  cols: 11
  description: The data was extracted from the 1974 Motor Trend US magazine, and comprises
    fuel consumption and 10 aspects of automobile design and performance for 32 automobiles
    (1973–74 models).
  type: table
  title: Motor Trend Car Road Tests
```

--------------------------------

### R: Use pin_versions with board and name

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin_versions.md

Demonstrates the correct usage of the `pin_versions` function in R. It shows how to provide both `board` and `name` arguments, as required by the modern API, and highlights the error that occurs when these arguments are omitted or swapped.

```R
pin_versions(name, board)
# Error in `pin_versions()`:
# ! Please supply `board` then `name` when working with modern boards
```

```R
pin_versions(board)
# Error in `pin_versions()`:
# ! Argument `name` is missing, with no default
```

--------------------------------

### YAML Board Metadata - Minimal Example

Source: https://github.com/rstudio/pins-r/wiki/Metadata

Defines the minimal structure for a board metadata file using YAML. It specifies the paths to the data files stored on the board. This is used for boards that do not natively support listing and searching pins.

```yaml
- path: iris/data.csv
- path: mtcars/data.csv
```

--------------------------------

### Install Development Version of pins in R

Source: https://github.com/rstudio/pins-r/blob/main/README.md

Installs the development version of the pins package from GitHub using the 'pak' package manager. This is useful for testing the latest features or bug fixes. Requires the 'pak' package to be installed first.

```r
# install.packages("pak")
pak::pak("rstudio/pins-r")
```

--------------------------------

### Azure Storage Board Configuration with pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Provides an example of configuring an Azure Blob Storage container as a pin storage backend using the pins R package. This involves setting up a connection to the blob container using SAS tokens and specifying a path within the container for pins.

```r
library(pins)
library(AzureStor)

# Blob storage
container <- blob_container(
  "https://myaccount.blob.core.windows.net/mycontainer",
  sas = "sv=2021-06-08&ss=b&srt=sco&sp=rwdlac..."
)
board <- board_azure(container, path = "pins")
```

--------------------------------

### Reading a Pin: Specifying Hash for Version Control

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin-read-write.md

Demonstrates how to read a specific version of a pin using the `hash` argument. It includes an example of the error encountered when the specified hash does not match the actual pin hash.

```r
b <- board_temp()
pin_write(b, mtcars, name = "mtcars", type = "rds")

```

```r
pin_read(b, "mtcars", hash = "ABCD")
```

--------------------------------

### R: Validate input for versions_keep

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin_versions.md

Provides examples of input validation for the `versions_keep` function in R. It demonstrates the specific error messages generated for invalid inputs, such as `NULL`, incorrect types for `n` or `days`, or supplying both `n` and `days`.

```R
versions_keep(NULL)
# Error in `versions_keep()`:
# ! Internal error: invalid result from pin_versions()
```

```R
versions_keep(Sys.time())
# Error in `versions_keep()`:
# ! Must supply exactly one of `n` and `days`
```

```R
versions_keep(Sys.time(), n = "a")
# Error in `versions_keep()`:
# ! `n` must be a single integer
```

```R
versions_keep(Sys.time(), days = "a")
# Error in `versions_keep()`:
# ! `days` must be a single integer
```

--------------------------------

### R: Deparse Board Configuration

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_folder.md

This function returns a character string representing the R code needed to recreate the specified board configuration. It's useful for saving or sharing board setups. The example shows deparsing a folder board.

```R
board_deparse(b)
```

--------------------------------

### Install pins Package in R

Source: https://github.com/rstudio/pins-r/blob/main/README.md

Installs the pins package from CRAN. This is the standard method for installing stable versions of R packages. Ensure you have a working R installation and internet connection.

```r
install.packages("pins")
```

--------------------------------

### Integrate Pins with Shiny for Reactive Data Updates

Source: https://context7.com/rstudio/pins-r/llms.txt

Provides an example of integrating the pins package with Shiny applications to create reactive data sources. It demonstrates using `pin_reactive_read` to automatically update data based on changes in the pin or manual refresh events triggered by user actions.

```r
library(pins)
library(shiny)

ui <- fluidPage(
  actionButton("refresh", "Refresh Data"),
  tableOutput("data")
)

server <- function(input, output, session) {
  board <- board_connect()

  # Reactive pin - updates when pin changes
  data <- pin_reactive_read(
    board,
    "team/live-data",
    interval = 60000  # Check every 60 seconds
  )

  output$data <- renderTable({
    data()
  })

  # Manual refresh
  observeEvent(input$refresh, {
    pin_reactive_invalidate(data)
  })
}

# shinyApp(ui, server)
```

--------------------------------

### R: Handle identical write errors with pin_write

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin_versions.md

Illustrates how the `pin_write` function in R provides informative error messages when attempting to write the same version of data twice. The `force_identical_write` argument is shown for scenarios where identical writes might be intended.

```R
pin_write(board, 1:10, "x")
pin_write(board, 1:10, "x", force_identical_write = TRUE)
# Error in `pin_store()`:
# ! The new version "20120304T050607Z-xxxxx" is the same as the most recent version.
# i Did you try to create a new version with the same timestamp as the last version?
```

--------------------------------

### R: Prune old versions with pin_versions_prune

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin_versions.md

Shows examples of using the `pin_versions_prune` function in R to remove old versions of a pin. It demonstrates how to specify the number of versions to keep (`n`) and the resulting messages for both successful pruning and when no old versions are found.

```R
pin_versions_prune(board, "x", n = 1)
# Deleting versions: 20130104T050607Z-xxxxx, 20130204T050607Z-yyyyy, 20130304T050607Z-zzzzz
```

```R
pin_versions_prune(board, "x", n = 1)
# No old versions to delete
```

--------------------------------

### Get R Pins Metadata

Source: https://context7.com/rstudio/pins-r/llms.txt

Explains how to retrieve metadata associated with a pin. This includes standard information like name, title, type, file details, hash, and creation date, as well as user-defined metadata and local cache information such as directory and version.

```r
library(pins)
board <- board_temp()
board |> pin_write(
  mtcars,
  "cars",
  title = "Motor Trend Cars",
  description = "Fuel efficiency data",
  tags = c("automotive", "mpg"),
  metadata = list(year = 1974, magazine = "Motor Trend")
)

# Retrieve metadata
meta <- board |> pin_meta("cars")

# Standard metadata
meta$name
meta$title
meta$type
meta$file
meta$file_size
meta$pin_hash
meta$created

# User metadata
meta$user

# Local metadata (cache location, version)
meta$local$dir
meta$local$version
```

--------------------------------

### R: Get Required Packages for a Board

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_folder.md

This function retrieves the necessary R packages required for a specified pin board. It's useful for ensuring all dependencies are met before performing board operations. The output is a character vector of package names, or an empty vector if no additional packages are needed.

```R
required_pkgs(board)
```

--------------------------------

### Local Folder Board Management with pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Shows how to set up and use a local folder as a storage backend for pins using the pins R package. This includes creating boards in specific directories, writing and reading pins, and utilizing system data directories for persistent storage.

```r
library(pins)

# Create board in a specific directory
board <- board_folder("~/shared-pins", versioned = TRUE)

# Write and read
board |> pin_write(mtcars, "cars")
board |> pin_read("cars")

# Perfect for network drives or Dropbox
board <- board_folder("~/Dropbox/team-pins")

# System data directory (persistent across sessions)
board <- board_local()
board |> pin_write(iris, "iris-cache")
```

--------------------------------

### Create Board Manifest for Read-Only Sharing

Source: https://context7.com/rstudio/pins-r/llms.txt

Explains how to create a board manifest file (`_pins.yaml`) which enables read-only sharing of a board via a URL. It demonstrates creating a folder board, writing pins to it, and then generating the manifest, allowing others to access the pins using `board_url`.

```r
library(pins)

# Create and populate a board
board <- board_folder("~/public-data")
board |> pin_write(mtcars, "cars")
board |> pin_write(iris, "flowers")
board |> pin_write(airquality, "weather")

# Write manifest file
board |> write_board_manifest()
#> Manifest file written to root folder of board, as `_pins.yaml`

# Now others can access via URL
# board_public <- board_url("https://example.com/public-data/")
# board_public |> pin_list()
# board_public |> pin_read("cars")
```

--------------------------------

### Create R Pins Boards

Source: https://context7.com/rstudio/pins-r/llms.txt

Demonstrates how to create different types of pin boards for storing and managing R objects. Supports temporary, persistent local, and system-level boards. Boards act as storage backends for pins.

```r
library(pins)

# Temporary board for examples (deleted when R session ends)
board <- board_temp()

# Persistent local board in a specific folder
board <- board_folder("~/my-pins")

# System-level local board (uses OS-specific data directory)
board <- board_local()

board
```

--------------------------------

### Search and Discover Pins using pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Demonstrates how to write, list, search, and check for the existence of pins using the pins R package. It covers basic operations like writing data to a temporary board and then listing, searching by keywords, and verifying pin presence.

```r
library(pins)
board <- board_temp()

# Write some pins with titles
board |> pin_write(mtcars, "cars", title = "Automotive fuel efficiency")
board |> pin_write(iris, "flowers", title = "Iris flower measurements")
board |> pin_write(airquality, "weather", title = "New York air quality")

# List all pins
board |> pin_list()
#> [1] "cars"    "flowers" "weather"

# Search for pins (searches name and title)
board |> pin_search()
#> # A tibble: 3 × 5
#>   name    type  title                          created             file_size
#>   <chr>   <chr> <chr>                          <dttm>              <fs::bytes>
#> 1 cars    rds   Automotive fuel efficiency     2025-10-13 12:00:00        1.62K
#> 2 flowers rds   Iris flower measurements       2025-10-13 12:00:01        3.45K
#> 3 weather rds   New York air quality           2025-10-13 12:00:02        2.88K

board |> pin_search("efficiency")
#> # A tibble: 1 × 5
#>   name type  title                      created             file_size
#>   <chr> <chr> <chr>                     <dttm>              <fs::bytes>
#> 1 cars  rds   Automotive fuel efficiency 2025-10-13 12:00:00       1.62K

# Check if a pin exists
board |> pin_exists("cars")
#> [1] TRUE
board |> pin_exists("missing")
#> [1] FALSE
```

--------------------------------

### Azure Board with Path Configuration in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Shows how to configure the Azure board using a `path` argument. This allows multiple boards to share the same container within Azure, providing more flexibility in storage management.

```R
board_azure(path = "your_path")
```

--------------------------------

### Generate Preview Data in R

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_bundle.md

This R code snippet demonstrates how to generate preview data for a data frame using the `rsc_bundle_preview_data` function. It shows how to include column metadata and options, and how to generate an empty preview when `preview` is set to `FALSE` or when the input is `NULL`.

```r
df <- data.frame(x = 1:2, y = c("a", "b"), stringsAsFactors = FALSE)
str(rsc_bundle_preview_data(df))
```

```r
str(rsc_bundle_preview_data(df, preview = FALSE))
```

```r
str(rsc_bundle_preview_data(NULL))
```

--------------------------------

### Create and Use URL Boards for Read-Only Access

Source: https://context7.com/rstudio/pins-r/llms.txt

Shows how to create read-only boards using URLs. This includes connecting to a single manifest file, a named vector of URLs, a named list with versions, reading from GitHub repositories, and using authentication headers for private servers or Posit Connect public pins.

```r
library(pins)

# Single manifest file
board <- board_url("https://example.com/pins/")

# Named vector of URLs
board <- board_url(c(
  cars = "https://example.com/data/cars.csv",
  weather = "https://example.com/data/weather.json"
))

# Named list with versions
board <- board_url(list(
  dataset = c(
    "https://example.com/data/v1/",
    "https://example.com/data/v2/",
    "https://example.com/data/v3/"
  )
))

# Read from GitHub
github_url <- function(path) {
  paste0("https://raw.githubusercontent.com/", path)
}
board <- board_url(c(
  penguins = github_url("user/repo/main/data/penguins.csv"),
  iris = github_url("user/repo/main/data/iris.rds")
))
board |> pin_read("penguins")

# With authentication headers
board <- board_url(
  "https://private-server.com/pins/",
  headers = c(Authorization = "Bearer token123")
)

# Posit Connect public pins
board <- board_url(
  "https://connect.example.com/content/abc123/",
  headers = connect_auth_headers()
)
```

--------------------------------

### Posit Connect Board Configuration and Usage with pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Details how to connect to and use a Posit Connect server as a pin storage backend with the pins R package. It covers automatic and manual authentication methods, writing, reading, and searching pins, as well as sharing pins publicly.

```r
library(pins)

# Automatic authentication (uses RStudio IDE settings or env vars)
board <- board_connect()
#> Connecting to Posit Connect 2024.08.0 at <https://connect.example.com>

# Write a pin (fully qualified name includes username)
board |> pin_write(mtcars, "cars-analysis")
#> Writing to pin 'julia/cars-analysis'

# Read a pin (from yourself or others)
board |> pin_read("julia/cars-analysis")
board |> pin_read("hadley/sales-data")

# Share publicly
board |> pin_write(public_data, "open-dataset", access_type = "all")

# Manual authentication
board <- board_connect(
  auth = "manual",
  server = "https://connect.example.com",
  key = Sys.getenv("CONNECT_API_KEY")
)

# Environment variable authentication
Sys.setenv(
  CONNECT_SERVER = "https://connect.example.com",
  CONNECT_API_KEY = "your-api-key-here"
)
board <- board_connect(auth = "envvar")

# Search across all pins on server
board |> pin_search("sales")
```

--------------------------------

### Configuring Headers for `board_url` with pins-r

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_url.md

Illustrates the correct and incorrect ways to specify headers when using the `board_url()` function. Proper header configuration is necessary for authenticated access or custom settings.

```r
board_url(c(x = "foo"), headers = list(auth = "x"))
```

```r
board_url(c(x = "foo"), headers = "my_api_key")
```

--------------------------------

### Registering a Board in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Details the improved functionality of `board_register()` when called directly. Standardization of cache paths across all computations enhances its reliability and predictability.

```R
board_register()
```

--------------------------------

### Implement Caching and Hash Verification for Pins

Source: https://context7.com/rstudio/pins-r/llms.txt

Explains how the pins package uses caching and hash verification to optimize data retrieval and storage. It demonstrates how writing identical data multiple times is skipped due to hash matching, and how to force a write or verify hashes during reading.

```r
library(pins)
board <- board_temp()

# First write - pin is created
board |> pin_write(mtcars, "cars")
#> Creating new version...

# Second write with same data - skipped
board |> pin_write(mtcars, "cars")
#> The hash of pin 'cars' has not changed.
#> Your pin will not be stored.

# Force write even if identical
board |> pin_write(mtcars, "cars", force_identical_write = TRUE)
#> Creating new version...

# Verify hash when reading
meta <- board |> pin_meta("cars")
board |> pin_read("cars", hash = meta$pin_hash)

# Hash mismatch throws error
# board |> pin_read("cars", hash = "wrong-hash")
#> Error: Specified hash 'wrong-hash' doesn't match pin hash
```

--------------------------------

### Browse Pins using pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Illustrates how to browse pins using the pins R package, including opening the pin's location in a file browser or web browser. This is useful for inspecting pin content locally or accessing remote pin locations.

```r
library(pins)
board <- board_temp(versioned = TRUE)
board |> pin_write(mtcars, "cars")

# Open pin location in file browser/web browser
board |> pin_browse("cars", local = TRUE)
#> Opens the local cache directory

# For remote boards, browse to the web interface
# board |> pin_browse("cars", local = FALSE)
```

--------------------------------

### Download and Upload Files with Temporary Boards

Source: https://context7.com/rstudio/pins-r/llms.txt

Illustrates advanced features for managing files without directly reading them into R objects. This includes downloading files from a board to a local cache and uploading arbitrary local files to a board. It uses a temporary board for these operations.

```r
library(pins)
board <- board_temp()

# Download files without reading into R
local_files <- board |> pin_download("dataset")
local_files
#> [1] "/tmp/pins-cache/dataset/data.csv"
#> [2] "/tmp/pins-cache/dataset/readme.txt"

# Upload arbitrary files
files <- c("model.pkl", "config.json", "weights.h5")
board |> pin_upload(files, "ml-model")

# Read later
board |> pin_download("ml-model")
```

--------------------------------

### R: Browse Pin (with and without local option)

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_folder.md

Demonstrates browsing for a pin on a board. The first attempt shows an error when a remote URL is not available. The second attempt, using `local = TRUE`, successfully shows the local path to the pin. This highlights how to access pin information locally.

```R
pin_browse(b, "x")
```

```R
pin_browse(b, "x", local = TRUE)
```

--------------------------------

### Environment Variable Authentication for Posit Connect Server

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_server.md

This function attempts to authenticate to a Posit Connect server using environment variables. It will error if the necessary environment variables (CONNECT_SERVER, CONNECT_API_KEY) are not found. Providing empty strings for server and key also results in an error if the API key is missing.

```r
rsc_server("envvar")
```

```r
rsc_server("envvar")
```

```r
rsc_server("envvar", server = "", key = "")
```

--------------------------------

### Deparsing Board Configuration for RSConnect in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Illustrates the `board_deparse()` function, which is now more reliable in generating runnable code when used in conjunction with `board_rsconnect()`, simplifying the process of recreating board configurations.

```R
board_deparse()
```

--------------------------------

### Writing Board Manifest File in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Illustrates the use of `write_board_manifest()` to create a `_pins.yaml` file. This file records all pins and their versions in the root directory of a board, but it is not applicable to read-only boards.

```R
write_board_manifest()
```

--------------------------------

### Google Cloud Storage Board in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Shows how to create and use a new board specifically for Google Cloud Storage. This function allows users to manage pins stored in GCS buckets.

```R
board_gcs()
```

--------------------------------

### Legacy Azure Board Functionality in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Confirms that the `legacy_azure()` function is operational again, allowing users to utilize the legacy Azure board functionality.

```R
legacy_azure()
```

--------------------------------

### Improved Path Expansion for Pin Upload in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Notes an improvement in `pin_upload()` regarding path expansion, making it more robust in handling file paths specified for uploads.

```R
pin_upload(board, path)
```

--------------------------------

### Browsing a Specific Pin in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Demonstrates the use of `pin_browse()`, which replaces `board_browse()`. This function directs the user to a specific pin, whether it's the original online source or the local cached version.

```R
pin_browse(board, name)
```

--------------------------------

### Check Authentication Method

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_server.md

This function attempts to find an appropriate authentication method. It will throw an error if no suitable method can be determined, detailing the reasons such as missing server/key for manual auth, missing environment variables, or no registered rsconnect accounts.

```r
check_auth()
```

--------------------------------

### R: Print Board Information

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_folder.md

Displays a summary of the pin board, including its type, path, and cache size. This is helpful for understanding the configuration and current state of a board. The function `board_folder` is specifically shown here.

```R
board_folder(path)
```

--------------------------------

### Download Data (R)

Source: https://context7.com/rstudio/pins-r/llms.txt

Illustrates how to download a pinned dataset in CSV format for users who prefer working with Excel.

```r
board |> pin_download("analysis-results")
```

--------------------------------

### R: Successful file upload with pin_upload and name guessing

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin-upload-download.md

Shows a successful execution of `pin_upload` where a temporary file is created and uploaded. The function automatically guesses the name from the file path and provides feedback on creating a new version.

```r
path <- fs::file_touch(fs::path_temp("test.txt"))
pin_upload(board, path)
```

--------------------------------

### R: Write Pin and Observe Versioning Messages

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_folder.md

This snippet illustrates the `pin_write` function, showing how it generates messages indicating the creation of new versions or replacement of existing ones. It demonstrates the versioning capabilities of the pins package when writing data. The `type = "rds"` argument specifies the file format.

```R
pin_write(b, 1:5, "x", type = "rds")
```

```R
pin_write(b, 1:6, "x", type = "rds")
```

```R
pin_write(b, 1:7, "x", type = "rds")
```

--------------------------------

### Manage R Pins Versions

Source: https://context7.com/rstudio/pins-r/llms.txt

Details how to manage versions of pins, especially useful with versioned boards. This includes listing all available versions, reading a specific historical version, pruning old versions to save space, deleting specific versions, and deleting an entire pin.

```r
library(pins)
board <- board_temp(versioned = TRUE)

# Create multiple versions
board |> pin_write(data.frame(x = 1:5), "numbers")
board |> pin_write(data.frame(x = 2:6), "numbers")
board |> pin_write(data.frame(x = 3:7), "numbers")

# List all versions
versions <- board |> pin_versions("numbers")
versions

# Read a specific version
old_data <- board |> pin_read("numbers", version = versions$version[[3]])

# Delete old versions (keep last 2)
board |> pin_versions_prune("numbers", n = 2)

# Delete a specific version
board |> pin_version_delete("numbers", version = "20251013T120002Z-m9n0o")

# Delete entire pin
board |> pin_delete("numbers")
```

--------------------------------

### Legacy GitHub Board Functionality in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Confirms that the `legacy_github()` function is operational again, allowing users to utilize the legacy GitHub board functionality.

```R
legacy_github()
```

--------------------------------

### R: Create and Delete Pins

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect.md

These functions handle the creation and deletion of pins on a board. `rsc_content_create` takes the board, pin name, and content (e.g., a list) as arguments. `rsc_content_delete` takes the board and pin name. Errors are raised if the pin already exists during creation or if the pin is not found during deletion.

```r
rsc_content_create(board, "test-1", list())
# Error in `rsc_check_status()`:
# ! Posit Connect API failed [409]
# * An object with that name already exists.

rsc_content_delete(board, "test-1")
# Error in `rsc_content_find()`:
# ! Can't find pin called "test-1"
# i Use `pin_list()` to see all available pins in this board
```

--------------------------------

### R: Error listing versions on unversioned board

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_url.md

Shows the error that occurs when attempting to list versions of a pin on a board that does not support versioning, using `pin_versions`. This error signifies that the accessed board is not configured for version tracking.

```R
pin_versions(board, "x")
```

--------------------------------

### YAML Pin Metadata - Extended Table Type with Column Details

Source: https://github.com/rstudio/pins-r/wiki/Metadata

Presents an comprehensive YAML metadata file for a 'table' type pin, including multiple file paths, row and column counts, and detailed column descriptions. This enhances UI features like data previews and column inspection.

```yaml
path:
- data.csv
- data.rds
rows: 150
cols: 5
columns:
  Sepal.Length: numeric
  Sepal.Width: numeric
  Petal.Length: numeric
  Petal.Width: numeric
  Species: factor
type: table
```

--------------------------------

### Manual Posit Connect Server Authentication

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_server.md

This function allows manual authentication to a Posit Connect server by providing the server URL and an API key. The authentication token is hidden in output for security reasons.

```r
server <- rsc_server_manual("http://example.com", "SECRET")
server$auth
```

```r
str(list(1, server$auth, 2))
```

--------------------------------

### AWS S3 Board Configuration and Operations with pins R Package

Source: https://context7.com/rstudio/pins-r/llms.txt

Explains how to configure and use an AWS S3 bucket as a pin storage backend using the pins R package. It includes connecting to S3 buckets, specifying prefixes, writing pins with S3-specific options, and performing management tasks like listing and deleting pins.

```r
library(pins)

# Connect to S3 bucket
board <- board_s3(
  bucket = "my-data-bucket",
  region = "us-east-1"
)

# With prefix for organization
board <- board_s3(
  bucket = "company-data",
  prefix = "analytics/",
  region = "us-west-2"
)

# Write with S3-specific options
board |> pin_write(
  model_results,
  "ml-predictions",
  ServerSideEncryption = "AES256",
  Tagging = "project=ml&environment=prod"
)

# Manual authentication
board <- board_s3(
  bucket = "my-bucket",
  access_key = Sys.getenv("AWS_ACCESS_KEY_ID"),
  secret_access_key = Sys.getenv("AWS_SECRET_ACCESS_KEY"),
  region = "us-east-1"
)

# With temporary session token
board <- board_s3(
  bucket = "my-bucket",
  access_key = "ASIAXXX",
  secret_access_key = "xxx",
  session_token = "FwoGZXIvYXd...",
  region = "us-east-1"
)

# List pins and manage versions
board |> pin_list()
board |> pin_versions("ml-predictions")
board |> pin_delete("old-pin")
```

--------------------------------

### Reactive Pin Reading and Downloading in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Shows the `pin_reactive_read()` and `pin_reactive_download()` functions, which replace `pin_reactive()`. These are used for reactive data access and downloads from pins.

```R
pin_reactive_read(board, name)
```

```R
pin_reactive_download(board, name)
```

--------------------------------

### Connect to and Use a Posit Connect Board in R

Source: https://github.com/rstudio/pins-r/blob/main/README.md

Connects to a Posit Connect server using `board_connect()`, then writes data to a pin named 'sales-summary' with type 'rds'. Another user can then read this pin using the same board connection.

```r
board <- board_connect()
#> Connecting to Posit Connect 2024.08.0 at <https://pub.current.posit.team>
board |> pin_write(tidy_sales_data, "sales-summary", type = "rds")
#> Writing to pin 'hadley/sales-summary'

board <- board_connect()
board |> pin_read("hadley/sales-summary")
```

--------------------------------

### Register Posit Connect Server (rsconnect)

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_server.md

This function is used to register a Posit Connect server using an existing rsconnect account configuration. Errors occur if no servers are registered or if multiple servers match the provided criteria, requiring disambiguation.

```r
rsc_server_rsconnect()
```

--------------------------------

### Write and Read Data in Multiple Formats (R)

Source: https://context7.com/rstudio/pins-r/llms.txt

Demonstrates how to write a dataset in multiple formats (RDS, CSV, JSON, Parquet) using the pins package and then read it back in a specific format (RDS).

```r
board |> pin_write(
  results,
  "analysis-results",
  type = c("rds", "csv", "json", "parquet")
)

board |> pin_read("analysis-results", type = "rds")
```

--------------------------------

### Updating Board URL for Manifest Files in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Demonstrates how `board_url()` has been updated to handle versions that are recorded using a manifest file, improving the management of pinned data.

```R
board_url()
```

--------------------------------

### Validating URL Formats for `board_url` with pins-r

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_url.md

Demonstrates the error conditions for providing invalid URL formats to the `board_url()` function. This ensures correct configuration of data boards.

```r
board_url(c("foo", "bar"))
```

```r
board_url(list("a", 1:2))
```

```r
board_url(1:10)
```

--------------------------------

### R: Deparse Board Configuration

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect.md

This function takes a board object and returns its deparsed representation, showing the arguments that would be used to recreate it. This is useful for understanding and reproducing board configurations.

```r
board_deparse(board)
```

--------------------------------

### Pin Download and Upload with File Paths in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Explains the `pin_download()` and `pin_upload()` functions, which operate on file paths instead of R objects. These functions serve as lower-level alternatives to `pin_read()` and `pin_write()` and address type instability issues found in older functions.

```R
pin_download(board, name, path)
```

```R
pin_upload(board, path, name)
```

--------------------------------

### Connect to Azure Storage (ADLSgen2 and File Storage)

Source: https://context7.com/rstudio/pins-r/llms.txt

Demonstrates how to connect to Azure Data Lake Storage Gen2 and Azure File Storage using the pins R package. It shows how to create a board object for each storage type and perform write/read operations. The `n_processes` argument can control parallel transfers.

```r
library(pins)

# ADLSgen2 (modern, faster API)
container <- storage_container(
  "https://myaccount.dfs.core.windows.net/mycontainer",
  key = Sys.getenv("AZURE_STORAGE_KEY")
)
board <- board_azure(container, path = "team-pins")

# Azure file storage
fileshare <- file_share(
  "https://myaccount.file.core.windows.net/myshare",
  key = Sys.getenv("AZURE_STORAGE_KEY")
)
board <- board_azure(fileshare, path = "analysis")

# Write and read
board |> pin_write(model, "production-model")
board |> pin_read("production-model")

# Control parallel transfers
board <- board_azure(container, n_processes = 20)
```

--------------------------------

### Handling Connect Usernames in Messages in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Reports a fix in how Connect usernames are handled across various outputs, including messages and previews, ensuring consistent and correct display.

```R
# No specific function call, relates to internal handling
```

--------------------------------

### Searching for Pins in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Explains the `pin_search()` function, which replaces `pin_find()`. Its capabilities are more limited compared to its predecessor due to revised assumptions about board structures.

```R
pin_search(board, text)
```

--------------------------------

### Configure Error Handling and Caching on Failure

Source: https://context7.com/rstudio/pins-r/llms.txt

Shows how to configure error handling and caching behavior when connecting to data sources. The `use_cache_on_failure` option allows the package to fall back to the last cached version of a pin if a network connection fails, providing a warning instead of an error.

```r
library(pins)

# Board with cache fallback on network failure
board <- board_connect(use_cache_on_failure = TRUE)

# If connection fails, uses last cached version with warning
# board |> pin_read("critical-data")
#> Warning: Failed to connect to Posit Connect; using cached version

# In production, disable cache fallback for clear errors
board <- board_connect(use_cache_on_failure = FALSE)
```

--------------------------------

### Pin Write with Type and Metadata in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Highlights the `type` and `metadata` arguments in the `pin_write()` function. The `type` argument allows selection of serialization methods, balancing speed, generality, and interoperability, while `metadata` enables arbitrary data storage.

```R
pin_write(board, data, name, type = "auto", metadata = list())
```

--------------------------------

### R: Deprecate and Replace `board_rsconnect` with `board_connect`

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect.md

Demonstrates the deprecation of the `board_rsconnect()` function in pins version 1.1.0 and its replacement with `board_connect()`. This function is used to establish a connection to a board, typically for Posit Connect. The new function accepts an `auth` argument, defaulting to 'envvar'.

```r
board <- board_rsconnect()
# Error: ! `board_rsconnect()` was deprecated in pins 1.1.0 and is now defunct.
# i Please use `board_connect()` instead.

board <- board_connect(auth = "envvar")
```

--------------------------------

### Read Pin Data in R

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_connect_bundle.md

This R code snippet demonstrates how to connect to a pins board and read a specific pin. It requires the 'pins' library and assumes authentication is handled via environment variables.

```r
library(pins)
board <- board_connect(auth = "envvar")
pin_read(board, "TEST/test")
```

--------------------------------

### YAML Pin Metadata - Table Type Pin

Source: https://github.com/rstudio/pins-r/wiki/Metadata

Demonstrates the recommended YAML structure for a 'table' type pin, explicitly setting the 'type' argument. This ensures the pin is imported as a data frame rather than a raw file.

```yaml
path: data.csv
type: table
```

--------------------------------

### Listing Pins in a Board in R

Source: https://github.com/rstudio/pins-r/blob/main/NEWS.md

Illustrates the `pin_list()` function, used to retrieve a list of all pins currently present within a specified board.

```R
pin_list(board)
```

--------------------------------

### Write R Data to Pins

Source: https://context7.com/rstudio/pins-r/llms.txt

Shows how to write R objects, such as data frames, to a pin board. Supports automatic type detection, explicit type specification (e.g., 'rds', 'csv', 'json'), and adding metadata like title, description, tags, and custom key-value pairs. Versioned boards automatically create new versions for each write operation.

```r
library(pins)
board <- board_temp(versioned = TRUE)

# Pin a data frame with automatic type detection
board |> pin_write(mtcars, "cars-data")

# Pin with explicit type and metadata
board |> pin_write(
  mtcars,
  name = "cars-analysis",
  type = "csv",
  title = "Motor Trend Car Road Tests",
  description = "1974 Motor Trend data on fuel consumption",
  tags = c("automotive", "fuel-efficiency"),
  metadata = list(source = "1974 Motor Trend Magazine", author = "Henderson and Velleman")
)

# Pin in multiple formats simultaneously
board |> pin_write(iris, "iris-data", type = c("rds", "csv", "json"))

# Check what's on the board
board |> pin_list()
```

--------------------------------

### Reading a Pin: Error Handling for Non-existent Files

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin-read-write.md

Demonstrates an error scenario when attempting to read a pin that was not properly uploaded. It highlights the specific error message indicating that the pin cannot be automatically read and suggests checking if the pin is specified as a full path or a URL with a trailing slash.

```r
pin_read(board, "test")
```

--------------------------------

### Accessing Metadata for an Unversioned Pin with pins-r

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/board_url.md

Illustrates the error when trying to access version-specific metadata for a pin that is not versioned. This clarifies the requirements for versioned pins.

```r
pin_meta(board, "x", version = "x")
```

--------------------------------

### Manage Pin Versions and Prune Old Data

Source: https://context7.com/rstudio/pins-r/llms.txt

Details version control features for pins, allowing multiple versions of the same pin to be stored. It shows how to prune older versions based on the number of versions or a time window, and how to delete specific old versions.

```r
library(pins)
board <- board_temp(versioned = TRUE)

# Write multiple versions
for (i in 1:10) {
  board |> pin_write(data.frame(x = i:(i+4)), "data")
  Sys.sleep(0.1)
}

# Keep only last 3 versions
board |> pin_versions_prune("data", n = 3)
#> Deleting versions: ...

# Keep versions from last 30 days
board |> pin_versions_prune("data", days = 30)

# Delete specific old version
versions <- board |> pin_versions("data")
board |> pin_version_delete("data", versions$version[[5]])
```

--------------------------------

### Pin Write: Automatic Name and Type Generation

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin-read-write.md

Shows how `pin_write` automatically generates a name and infers the type when not explicitly provided. It also demonstrates the error raised when `name` is not supplied for an expression.

```r
b <- board_temp()
pin_write(b, mtcars)

```

```r
pin_write(b, data.frame(x = 1))
```

--------------------------------

### Writing a Pin: Input Validation Errors

Source: https://github.com/rstudio/pins-r/blob/main/tests/testthat/_snaps/pin-read-write.md

Illustrates various input validation errors that can occur when using the `pin_write` function. It covers incorrect types for `board`, `name`, and `type` arguments, as well as issues with `metadata`, `tags`, and `urls`.

```r
pin_write(mtcars)

```

```r
pin_write(board, mtcars, name = 1:10)

```

```r
pin_write(board, mtcars, name = "mtcars", "json")

```

```r
pin_write(board, mtcars, name = "mtcars", type = "froopy-loops")

```

```r
pin_write(board, mtcars, name = "mtcars", metadata = 1)

```

```r
pin_write(board, mtcars, title = "title", tags = list(a = "a"))

```

```r
pin_write(board, mtcars, title = "title", urls = list(a = "a"))

```

```r
pin_write(board, mtcars, title = "title", metadata = c("tag1", "tag2"))

```