An R Interface to 'deck.gl'

Makes 'deck.gl' < https://deck.gl/>, a WebGL-powered open-source JavaScript framework for visual exploratory data analysis of large datasets, available within R via the 'htmlwidgets' package. Furthermore, it supports basemaps from 'mapbox' < https://www.mapbox.com/> via 'mapbox-gl-js' < https://github.com/mapbox/mapbox-gl-js>.


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

  • It is a known issue that the deckgl widget might not be visible in the viewer pane of RStudio. Just open it in your browser by clicking Show in new window and everything will be fine.
  • The documentation is work in progress. Please check also the examples as a starting point.
  • You do not need a mapbox api key to use this package. It is always optional to add a base map from mapbox to your widget.

Installation

You can install deckgl from github with:

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
  • The data parameter can either be an url to fetch data from or a data object. Furthermore, you can use get_data in conjunction with add_data to use a data file.
  • The properties parameter is a named list with names corresponding to the properties defined in the deckgl-api-reference for the given layer class. For the example above see the grid-layer-api-reference. In case the property is a data accessor (usually a function in the form of a lambda expression) just use the JS function in R to pass it to the layer object. In the example above this is done for the properties getPosition and getTooltip. It is also possible to pass properties as named arguments via the ... parameter. They are appended to the properties list. Same properties will be overwritten.

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

News

deckgl 0.1.8

  • Switched to deckgl.js 6.2.4

deckgl 0.1.7

  • Switched to deckgl.js 6.2.3
  • Added examples to r-docs for all add_*_layer functions
  • Added helper functions to run api-examples, not exported yet:
deckgl:::browse_api_examples()[1] %>%
  deckgl:::run_api_example()
deck

deckgl 0.1.6

  • Switched to deckgl.js 6.2.2
  • Added more examples
  • Added ... parameter to deckgl to pass optional parameters to the deck instance:
deckgl(
  zoom = 5,
  pickingRadius = 5,
  style = list(background = "black")
)
  • Added functions add_data and get_data to pass data objects as separate files:
deckgl() %>%
  add_data(bart_stations) %>%
  add_scatterplot(data = get_data(), properties = properties)

deckgl 0.1.5

  • Switched to deckgl.js 6.1.1
  • Added helper functions get_property and get_color_to_rgb_array:
properties <- list(
  getText = JS("data => data.text")
)
 
# equals
 
properties <- list(
  getText = get_property("text")
)
  • Refactored deckgl-api-reference examples for all core layers
  • Updated and added vignettes for core layers
  • Added LICENSE.note file

deckgl 0.1.4

  • Switched to deckgl.js 6.1.0
  • Added missing add_*_layer functions for all core layers including add_contour_layer (new in version 6.1.0)
  • Added helper functions encode_icon_atlas, icon_definition and default_icon_properties to set icons for the icon layer:
icon_properties <- list(
  iconAtlas = encode_icon_atlas(),
  iconMapping = list(marker = icon_definition()),
  getIcon = JS("d => 'marker'"),
  ...
)
  • Added on click event in shinyMode passing info.object and latLng back to R
  • Added arguments inititialViewState and views to deckgl widget. If views is not supplied, a single MapView is created.
  • Added more examples (see point-cloud-laz-indoor-scan.R example for how to use an OrbitView)

deckgl 0.1.3

  • Added a NEWS.md file to track changes to the package.
  • Added support for tooltips:
# Tooltip example for a grid layer
 
properties <- list(
  pickable = TRUE
  getTooltip = JS("object => `${object.position.join(', ')}\nCount: ${object.count}`")
  fixedTooltip = TRUE # show tooltip always on upper left corner,
  ...
)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.