In javierluraschi/pins: Pin, Discover and Share Resources

library(nomnoml)

A board is an storage location to store files for personal use, with your team, or publicly with the world. A board defines four operations to manage pins in any storage system: create, find, retrieve and remove. A board can be read-only if it only supports the retrieve and find operations.

```{nomnoml echo=FALSE, out.width='100%', out.height='240px'} [Pin]->[Create] [Create]->[Board] [Pin]<-[Find] [Find]<-[Board] [Pin]<-[Retrieve] [Retrieve]<-[Board] [Pin]->[Remove] [Remove]->[Board]

## Files

The defaul board in the `pins` package is a files-based; meaning, remote files are stored in the file system assigned to your R session. When using this from your personal computer, this defaults to a `pins` folder under the default home folder for your user.

```{nomnoml echo=FALSE, out.width='100%', out.height='160px'}
[R|
  [<note>library(pins)
    pin(iris, "iris")]
]-[File System|
  [<note>~/documents/
   ~/images/
   ~/pins/files/pins.yml
   ~/pins/files/iris.Rds
  ]
]

RStudio

RStudio Connect can be used to share pins within your organization, to use this feature you will need to configure a publishing account in RStudio.

```{nomnoml echo=FALSE, out.width='100%', out.height='140px'} [R| [library(pins) register_board("rstudio") pin(iris, "iris")] ]-[RStudio Connect| [iris]]

To make RStudio Connect your default board run:

```r
board_register("rstudio")

Once this board is active, pin() and pin_get() will default to use RStudio connect. For instance, we can retrieve the latest world news and pin them to RStudio Connect as follows:

library(xml2)
data.frame(title = xml_text(xml_find_all(read_xml("http://feeds.bbci.co.uk/news/rss.xml"), "///item/title/node()"))) %>%
  pin("worldnews", "A table with the latests world news from the BBC")

When using multiple publishing servers, you can specify an specific server through register_board("rstudio", "<server-name>").

When using pins within RMarkdown documents that you want to run at a given schedule, like rstudio-world-news.Rmd, you'll have to first retrieve your publishing secret credentials:

board_get("rstudio")$secret()

Followed by specifying that secret in register_board(), this can be securely accomplish by defining an environment variable secret with the contents from the previous step in RStudio Connect. Please treat your credentials with care!

register_board("rstudio", secret = Sys.getenv("secret"))

Kaggle

```{nomnoml echo=FALSE, out.width='100%', out.height='140px'} [R| [library(pins) register_board("kaggle") pin(iris, "iris")] ]-[Kaggle| [iris]]

## Other

If the boards that the `pins` package provides are not sufficient, say, you might want to store your pins in Google Drive; you can still implement custom boards by implementing a few S3 methods. It is advisable to create an R package that provides these methods, but you can also define them in a plain R script.

The following example creatse a simple folder-bard board; probably not suitable for real use cases since all your pins would be lost whenever the R session restarts; however, it's a simple example that you can use to start developing custom boards:

```r
board_initialize.folder <- function(board, ...) {
  if (!dir.exists("pins")) dir.create("pins")
  board
}

board_pin_create.folder <- function(board, path, name, description, type, metadata) {
  file.copy(path, file.path("pins", paste0(name, ".", type)))
  pin_get(name, board = board$name)
}

board_pin_get.folder <- function(board, name) {
  path <- dir("pins", name, full.names = T)
  attr(path, "pin_type") <- tools::file_ext(path)
  path
}

board_pin_find.folder <- function(board, text) {
  path <- dir("pins", text, full.names = T)
  names <- sapply(strsplit(basename(path), "\\."), function(e) e[1])
  types <- sapply(strsplit(basename(path), "\\."), function(e) e[2])
  empties <- rep("", length(types))

  data.frame(name = names, description = empties, type = types, metadata = empties, stringsAsFactors = F)
}

board_pin_create.folder <- function(board, name) {
  unlink(file.path("pins", name))
}