Repository files navigation

The r-deckgl package makes the open-source JavaScript librarydeck.gl available within R via thehtmlwidgets package.

install.packages("deckgl")

You can install the latest version of r-deckgl from github with:

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

library(deckgl)

Create adeckgl instance:

deckgl()

Add a basemap:

deckgl() %>%  add_basemap()

Add any kind of layers:

# Grid layer exampledata("sf_bike_parking")props<-list(extruded=TRUE,cellSize=200,elevationScale=4,getPosition=~lng+lat,tooltip="Count: {{count}}")deckgl(zoom=11,pitch=45) %>%  add_basemap() %>%  add_grid_layer(data=sf_bike_parking,properties=props  )

Thedeckgl function creates the widget / renderer to which you addlayers and other configuration parameters:

rdeck<- deckgl(latitude=37.8,longitude=-122.45,zoom=12) %>%  add_grid_layer(data=data,properties=props  )

Due to the generic functionadd_layer any kind of layer defined in thedeck.gl LayerCatalogis supported. The layer type is chosen via theclass_name parameter,e. g.ScatterplotLayer orGeoJsonLayer. Usually you will not use thegeneric function but one of theadd_*_layer shortcuts instead:

# Generic functiondeckgl() %>%  add_layer("ArcLayer",id,data,properties)# Shortcut functiondeckgl() %>%  add_arc_layer(id,data,properties)

Thedata parameter can either be an url to fetch data from or a dataobject. In most cases you will pass an object of typedata.frame tothe layers. Use the formula syntax to define data accessors that deck.gluses to access the properties of the data object:

props<-list(getPosition=~lng+lat# ...)

An object of classsf is adata.frame with a geometry list-column. Set the layer prop thatfetches the geometry to the geometry list-column of yoursf object:

# Example: PolygonLayerprops<-list(getPolygon=~geometry# ...)

Withadd_source you can add a source to the widget that can be usedaccross layers:

data("bart_stations")deckgl() %>%  add_source("bart-stations",bart_stations) %>%  add_scatterplot_layer(source="bart-stations",getPosition=~lng+lat,# ...  ) %>%  add_text_layer(source="bart-stations",getPosition=~lng+lat,# ...  ) %>%  add_basemap()

Please note that you use the parametersource instead ofdata.

Layer properties are passed to theadd_*_layer functions either asnamed list by theproperties argument or as named parameters / keywordarguments via the... parameter. The names correspond to theproperties of the deck.gl counterparts. Therefore, please see thedeck.gl LayerCatalogto determine the available parameters for the used layer. You can alsopass a props list and keyword arguments together. Identical propertiesare overwritten by the latter ones.

GridLayerexample:

// JavaScript codeconstlayer=newGridLayer({id:"grid-layer",data:data,extruded:true,cellSize:200,elevationScale:4,getPosition:d=>[d.lng,d.lat]});

# Corresponding R code# using named argumentsdeck<- deckgl() %>%  add_grid_layer(id="grid-layer",data=data,extruded=TRUE,cellSize=200,elevationScale=4,getPosition=~lng+lat  )# ... using a named props listprops<-list(cellSize=200,extruded=TRUE,# ...)deckgl() %>%  add_grid_layer(data=data,properties=props  )

According to the style conventions in R,camelCased parameters indeck.gl can also be passed assnake_cased parameters in R. Forexample,getPosition can be passed to deck.gl asget_position:

deckgl() %>%  add_grid_layer(get_position=~lng+lat,cell_size=200,# ...  )

Use the formula syntax to define data accessors:

props<-list(getPosition=~lng+lat# js: d => [d.lng, d.lat]getFillColor=~color# js: d => d.color# ...)

The example above assumes that your data contains the columnslng,lat andcolor.

It is also possible to pass JavaScript code by using theJS functionin R:

props<-list(getColor= JS("d => d.capital ? [140, 10, 10] : [60, 10, 10]")# ...)

In deck.gl colors are represented by[r, g, b, a] arrays. In R you canpass hex color codes or color names to all color props of theadd_*_layer functions. They are automatically converted to therequired format:

deckgl() %>%  add_grid_layer(colorRange=RColorBrewer::brewer.pal(6,"Blues"),# ...  )

The tooltip for a layer can be set via thetooltip parameter. You caneither pass a single template string or a list with the followingproperties (see alsouse_tooltip):

• html: A template string that will be set as theinnerHTML of thetooltip.
• style: AcssText string that will modefiy the default style ofthe tooltip.

The tooltip string is a so called “mustache” template in which variablenames are identified by the double curly brackets that surround them.The variable names available to the template are given by deck.gl’spickingInfo.objectand vary by layer.

ArcLayerexample:

data("bart_segments")props<-list(getWidth=12,getSourcePosition=~from_lng+from_lat,getTargetPosition=~to_lng+to_lat,getSourceColor="yellow",getTargetColor="orange",tooltip= use_tooltip(html="{{from_name}} to {{to_name}}",style="background: steelBlue; border-radius: 5px;"  ))deckgl(zoom=9.5,pitch=35) %>%  add_arc_layer(data=bart_segments,properties=props) %>%  add_basemap()

Seemustache.js for a completesyntax overwiew.

Controls are displayed as overlays on top of the map / deck. Usually youcan set the position and the style of the control. The most basiccontrol is a simple text box:

deckgl() %>%  add_basemap() %>%  add_control(html="Plain Base Map",pos="top-right",style="background: steelblue; color: white"  )

You can add an instance of theace editor in JSONmode to the map by usingadd_json_editor:

deckgl() %>%  add_grid_layer(# ...  ) %>%  add_json_editor()

This allows you to change your layer props on the fly. You can togglethe visibility of the editor by pressing “e”.

Withadd_legend you can add a custom legend to your widget:

deckgl() %>%  add_basemap() %>%  add_legend(colors= c("yellow","orange"),labels= c("Cake","Icecream"),title="Sweets"  )

In most cases, you will create the legend automatically using a palettefunction:

data_column<-1:10pal<-scales::col_bin("Blues",data_column,bins=5)deckgl() %>%  add_basemap() %>%  add_legend_pal(pal,title="Blues")

By default,add_basemap adds acartobasemapto the widget.

To use basemaps frommapbox it isrecommended that you store your API access token in an environmentvariable calledMAPBOX_API_TOKEN:

# If not set globally#Sys.setenv(MAPBOX_API_TOKEN = "xyz")deckgl() %>%  add_mapbox_basemap("mapbox://styles/mapbox/light-v9")

You can run theAPIexamplesfrom theadd_*_layer functions withexample(add_*_layer):

example(add_grid_layer)

With therenderDeckgl anddeckglOutput functions you can user-deckgl in shiny applications:

library(shiny)library(deckgl)backend<-function(input,output) {output$rdeck<- renderDeckgl({    deckgl() %>%      add_grid_layer(data=sf_bike_parking,getPosition=~lng+lat,cellSize=400,pickable=TRUE      ) %>%    add_basemap()  })}frontend<- fluidPage(  deckglOutput("rdeck"))shinyApp(frontend,backend)

To update adeckgl instance usedeckgl_proxy in combination withupdate_deckgl.

Furthermore, theonclick event sends deck.gl’spicking infoobjectto your shiny application and updates the corresponding input in theform ofinput$widget_id_onclick. For example, if the widget id isrdeck, you can access thepickingInfo object withinput$rdeck_onclick:

backend<-function(input,output) {# ...  observeEvent(input$rdeck_onclick, {info<-input$rdeck_onclick    print(info$object)  })}

The JavaScript library of r-deckgl useswebpack as module bundler. Therefore, youneednode.js to build the module. All JavaScriptcode is located in thejavascript/src folder and test components go tojavascript/src/test-components.

Install deps and build the library from inside thejavascript folderwith:

npm installnpm run build

To spin up thewebpack-dev-server run:

npm run start

• r-deckgl pkgdown Site
• ExampleScripts
• deck.gl JavaScript APIReference

If thedeckgl widget is not visible in the viewer pane of RStudio,just open it in your browser by clicking “Show in new window” andeverything will be fine.