Create consistent metadata for pins
In pins: Pin, Discover and Share Resources

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

The metadata argument in pins is flexible and can hold any kind of metadata that you can formulate as a list(). In some situations, you may want to read and write with consistent customized metadata; you can create functions to wrap pin_write() and pin_read() for your particular use case.

To see a different approach for when you want to write and read whole file(s) in a customized way, see vignette("managing-custom-formats").

We'll begin by creating a temporary board for demonstration:

library(pins)

board <- board_temp()

A function to store factors

Say you want to store a factor as JSON together with the levels of the factor in the metadata. We can write a function wrapping pin_write() that creates the standardized metadata we are interested in and writes it in a consistent way.

pin_write_factor_json <- function(board, 
                                  x, 
                                  name, 
                                  title = NULL, 
                                  description = NULL, 
                                  metadata = list(), 
                                  versioned = NULL, 
                                  tags = NULL, 
                                  ...) {
  if (!is.factor(x)) rlang::abort("`x` is not a factor")
  factor_levels <- levels(x)
  metadata <- modifyList(metadata, list(factor_levels = factor_levels))
  pin_write(
    board = board, 
    x = x, 
    name = name, 
    type = "json", 
    title = title, 
    description = description, 
    metadata = metadata,
    ...
  )
}

We can use this new function to write a pin as JSON with our specific metadata:

ten_letters <- factor(sample(letters, size = 10), levels = letters)
board %>% pin_write_factor_json(ten_letters, "letters-as-json")

A function to read factors

It's possible to read this pin using the regular pin_read() function, but the object we get is no longer a factor!

board %>% pin_read("letters-as-json")

Instead, we can also write a special function for reading, to reconstruct the factor including its levels:

pin_read_factor_json <- function(board, name, version = NULL, hash = NULL, ...) {
  ret <- pin_read(board = board, name = name, version = version, hash = hash, ...)
  meta <- pin_meta(board = board, name = name, version = version, ...)
  factor(ret, levels = meta$user$factor_levels)
}

board %>% pin_read_factor_json("letters-as-json")

Examples of using consistent metadata

How are these approaches used in real projects?

The vetiver package wraps pins functions to write and read model binaries together with their metadata, including an renv lockfile.
You can record version control information such as Git commit and SHA as pin metadata.
You can create data lineage or data governance metadata appropriate to your use case.