Package {rDeckgl}

rDeckgl: R Bindings to 'Deck.gl'

Description

Provides R bindings for 'deck.gl', a 'WebGL' framework for rendering large interactive spatial and tabular visualizations. The package supplies 'htmlwidgets' and 'shiny' bindings, supports 'DuckDB'-backed data hydration, and bundles the JavaScript assets needed to render 'deck.gl' specifications from R.

Acknowledgements

Developed in the Dries Lab at Boston University. This work was supported by the Dries Lab and the Boston University Undergraduate Research Opportunities Program (UROP).

Author(s)

Maintainer: Timur Rizvanov timurr@bu.edu

Authors:

• Edward C. Ruiz ecr7407@gmail.com

• Ruben Dries rubendries@gmail.com [reviewer]

Other contributors:

• Dries Lab (Host laboratory and funding source) [funder]

• Boston University (Undergraduate Research Opportunities Program (UROP)) [funder]

See Also

Useful links:

• https://github.com/TiRizvanov/rDeckgl

• Report bugs at https://github.com/TiRizvanov/rDeckgl/issues

Export a DuckDB query to Arrow IPC bytes via ADBC

Description

Uses the ADBC driver (adbcdrivermanager) to execute a query and capture the result as raw Arrow IPC stream bytes. This preserves GeoArrow extension metadata automatically in DuckDB >= 1.5.

Usage

.adbc_query_to_ipc_bytes(con, query)

Arguments

Value

Raw vector of Arrow IPC stream bytes, or NULL on failure.

Render a Deck.gl visualization

Description

Creates an interactive deck.gl visualization from a JSON or YAML specification. Supports server-side data hydration via DuckDB for efficient data handling.

Usage

deckgl(
  spec,
  specType = c("auto", "json", "yaml"),
  data = NULL,
  con = NULL,
  data_transport = c("auto", "file", "inline"),
  data_dir = NULL,
  width = NULL,
  height = NULL
)

Arguments

Details

A 'type = "duckdb"' data node with 'format = "arrow"' never materialises query rows in R. DuckDB writes the result straight to a binary file using the first method that succeeds: 'COPY ... (FORMAT ARROWS)' when the community 'nanoarrow' DuckDB extension can be loaded, otherwise Arrow record-batch streaming through 'arrow::write_ipc_stream()', otherwise 'COPY ... (FORMAT PARQUET)'. With 'data_transport = "file"' that file is written into 'data_dir' and the node carries a relative '__arrow_url' (or '__parquet_url'); with '"inline"' its bytes are base64-encoded into the widget as '__arrow' (or '__parquet'). Either way the node records the method in '__export_method' ('"copy_arrows"', '"record_batch_stream"' or '"copy_parquet"'). Extensions are never installed on a user-supplied 'con'; only 'LOAD nanoarrow' is attempted.

In the browser, standard layers such as 'ScatterplotLayer' bind such a table as binary attributes rather than row objects when 'getPosition', 'getFillColor' and 'getRadius' are plain column references, for example '"@@=[x, y]"', '"@@=[x, y, 0]"', '"@@=[r, g, b]"' and '"@@=radius"' (or 'list(fields = c("x", "y"))'). Constant colours and radii stay plain props. Any other accessor that references row fields makes the layer fall back to row objects, with a console warning naming the accessor.

Value

An htmlwidget that renders the Deck.gl visualization.

Examples

if (interactive()) {
  # Simple scatterplot with inline data
  spec <- list(
    `@type` = "DeckGL",
    initialViewState = list(
      longitude = -122.4,
      latitude = 37.76,
      zoom = 12,
      pitch = 0,
      bearing = 0
    ),
    layers = list(
      list(
        `@type` = "ScatterplotLayer",
        id = "scatterplot",
        data = list(
          type = "duckdb",
          query = "SELECT lon, lat, radius FROM points"
        ),
        getPosition = "@=[lon, lat]",
        getRadius = "@=radius",
        getFillColor = c(255, 0, 0)
      )
    )
  )

  data <- list(
    points = data.frame(
      lon = c(-122.4, -122.45, -122.35),
      lat = c(37.76, 37.78, 37.74),
      radius = c(100, 150, 200)
    )
  )

  deckgl(spec = spec, data = data)
}

Shiny output for Deck.gl widget

Description

Use this in the UI to create a placeholder for the Deck.gl visualization.

Usage

deckglOutput(outputId, width = "100%", height = "400px")

Arguments

Value

A Shiny output binding for use in the UI.

Examples

if (interactive()) {
  library(shiny)
  library(rDeckgl)

  ui <- fluidPage(
    deckglOutput("myDeckgl", height = "600px")
  )

  server <- function(input, output, session) {
    output$myDeckgl <- renderDeckgl({
      deckgl(spec = my_spec, data = my_data)
    })
  }

  shinyApp(ui, server)
}

Render a ggsql query as a Deck.gl visualization

Description

'ggsql()' lets you describe a Deck.gl visualization using the ggsql dialect (VISUALIZE / DRAW / PLACE / SCALE / LABEL / SETTING) instead of the native Deck.gl spec. The parser is shared with rMosaic; this entry point compiles for the Deck.gl rendering path, which is the right choice for spatial layers (polygons, hex grids, big point clouds, GeoArrow data).

Usage

ggsql(sql, data = NULL, con = NULL, width = NULL, height = NULL, ...)

Arguments

Value

An htmlwidget produced by [deckgl()].

See Also

[deckgl()].

Hydrate Deck.gl DuckDB data references

Description

Recursively walks a Deck.gl specification and replaces 'type = "duckdb"' data nodes with concrete result sets queried via the provided connection.

Usage

hydrate_deckgl_spec(
  spec,
  con,
  list_col_metadata = NULL,
  data_transport = c("auto", "file", "inline"),
  data_dir = NULL
)

Arguments

Value

A hydrated list that is safe to JSON-encode for Deck.gl.

Shiny render function for Deck.gl

Description

Use this in the server to render the Deck.gl visualization to the output.

Usage

renderDeckgl(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A Shiny render function for use in the server.

Examples

if (interactive()) {
  library(shiny)
  library(rDeckgl)

  ui <- fluidPage(
    deckglOutput("myDeckgl")
  )

  server <- function(input, output, session) {
    output$myDeckgl <- renderDeckgl({
      spec <- list(
        `@type` = "DeckGL",
        initialViewState = list(longitude = -122.4, latitude = 37.76, zoom = 12),
        layers = list(
          list(
            `@type` = "ScatterplotLayer",
            id = "points",
            data = list(type = "duckdb", query = "SELECT * FROM points"),
            getPosition = "@=[lon, lat]",
            getRadius = 100,
            getFillColor = c(255, 0, 0)
          )
        )
      )
      deckgl(spec = spec, data = list(points = data.frame(lon = -122.4, lat = 37.76)))
    })
  }

  shinyApp(ui, server)
}