An R Interface to deck.gl

CRAN_Status_Badge Travis-CI Build Status Project Status: Active – The project has reached a stable, usable state and is being actively developed.

Deckgl for R makes the open-source JavaScript library deck.gl available within R via the htmlwidgets package.

Notes

Installation

You can install deckgl from github with:

# install.packages("devtools")
devtools::install_github("crazycapivara/deckgl")

Quickstart

Just check if everything is fine:

library(deckgl)

does_it_work()
#> You should see a text layer telling you that it works.

# Or in case you do have an api token from mapbox ...
does_it_work("yourSuperSecretApiToken")
#> Output should be the same as above but rendered on top of a base map from mapbox.

Show some sample data:

# Pass 'data = NULL' to load some sample data for the hexagon layer
deckgl() %>%
  add_hexagon_layer(data = NULL) %>%
  add_mapbox_basemap("yourSuperSecretApiToken") # optional

Usage

Create a deckgl widget:

deckgl()

Add a base map from mapbox (optional):

Sys.setenv(MAPBOX_API_TOKEN = "yourSuperSecretApiToken")

deckgl() %>%
  add_mapbox_basemap(style = "mapbox://styles/mapbox/dark-v9")

Add any kind of layers:

# Grid layer example

sample_data <- paste0(
  "https://raw.githubusercontent.com/",
  "uber-common/deck.gl-data/",
  "master/website/sf-bike-parking.json"
)

properties <- list(
  pickable = TRUE,
  extruded = TRUE,
  cellSize = 200,
  elevationScale = 4,
  getPosition = JS("data => data.COORDINATES"),
  getTooltip = JS("object => object.count")
)

deckgl(zoom = 11, pitch = 45) %>%
  add_grid_layer(data = sample_data, properties = properties) %>%
  add_mapbox_basemap() # optional

Layers

Due to the generic function add_layer any kind of layer defined in the deckgl-api-reference is supported. The type of layer is chosen via the class_name parameter, e. g. ScatterplotLayer or GeoJsonLayer. Usually you will not use the generic function but one of the add_*_layer shortcut functions instead:

# Generic function
deckgl() %>% add_layer("ArcLayer", "arc-layer", data, properties)

# Shortcut function
deckgl() %>% add_arc_layer("arc-layer", data, properties)

Run examples

You can run the api-examples from the add_*_layer functions with example(add_*_layer). For the IconLayer it looks like this:

# Sys.setenv(MAPBOX_API_TOKEN = "yourSuperSecretApiToken")
example(add_icon_layer)

Concept

Deckgl for R stays as close as possible to the JavaScript api so that usually all parameters of its JavaScript pendants are supported. Therefore, you need to check the deckgl-api-reference of the JavaScript framework to get information about the parameters you can pass to the R-functions mostly as named lists or named arguments (... parameter). Use the JS function if you need to pass any kind of JavaScript code, as it is the case for data accessors.

GridLayer api-example:

// JavaScript code

const layer = new GridLayer({
  id: "grid-layer",
  data: data,
  extruded: true,
  cellSize: 200,
  elevationScale: 4,
  getPosition: d => d.COORDINATES,
});
# Corresponding R code

deck <- deckgl() %>%
  add_grid_layer(
    id = "grid-layer",
    data = data,
    extruded = TRUE,
    cellSize = 200,
    elevationScale = 4,
    getPosition = JS("d => d.COORDINATES")
  )

In this example all properties are passed as named arguments.

You can test your R code like this:

properties <- list(
  extruded = TRUE,
  cellSize = 200,
  elevationScale = 4,
  getPosition = get_property("COORDINATES")
)

htmlwidgets:::toJSON2(properties, pretty = TRUE)
#> {
#>   "extruded": true,
#>   "cellSize": 200,
#>   "elevationScale": 4,
#>   "getPosition": "data => data.COORDINATES"
#> }

Documentation