geoplumber is an R package which enables data scientists and developers in general to develop scalable geospatial web applications. It is work in progress, and right now we consider it an R powered web application “framework”. It utilizes plumber, which was designed for creating web APIs with R which is Swagger compliant. It supports React frontends at present (it may support other frontend frameworks such as VueJS in the future) and geographic data, building on sf.
It can be installed with the following command as it is not yet on CRAN:
devtools::install_github("ATFutures/geoplumber")
#> the latest dev versionUsage
- For more detailed introduction see the vignette
To create a new web application:
library(geoplumber)
gp_create("my_app")This will create a my_app folder at your current working directory. Suppose you started an R session from a folder with path /Users/ruser/, you will have /Users/ruser/my_app on your machine.
You can then build the new project
You can then serve endpoints and front end with: gp_plumb() # provide custom port if you wish, default is 8000
Then visit localhost:8000 to see your app.
Example (1) reproducible web app
library(geoplumber)
d <- file.path(tempdir(), "gp")
gp_create(d)
#> Creating directory: /var/folders/z7/l4z5fwqs2ksfv22ghh2n9smh0000gp/T//Rtmpee0Wxd/gp
#> To build/run app, set working directory to: /var/folders/z7/l4z5fwqs2ksfv22ghh2n9smh0000gp/T//Rtmpee0Wxd/gp
#> Standard output from create-react-app works.
#> You can run gp_ functions from directory: /var/folders/z7/l4z5fwqs2ksfv22ghh2n9smh0000gp/T//Rtmpee0Wxd/gp
#> To build the front end run: gp_build()
#> To run the geoplumber app: gp_plumb()
#> Happy coding.
setwd(d)
ps <- gp_plumb()
#> WARNING:
#> Looks like geoplumber was not built, serveing API only.
#> To serve the front end run gp_build() first.
Sys.sleep(1) # needed on automated build machines :)
ps
#> PROCESS 'R', running, pid 24807.
require(RCurl)
#> Loading required package: RCurl
webpage <- getURL("http://localhost:8000")
webpage <- readLines(tc <- textConnection(webpage)); close(tc)
tail(webpage)
#> [1] " <p>build missing</p>" " </div>"
#> [3] "</div>" ""
#> [5] "</body>" "</html>"
ps$kill()
#> [1] TRUE
# should fail
# getURL("http://localhost:8000")Example (2)
Serve the geoplumber::traffic dataset (data.frame) at a “/api/data” endpoint, and view it on the front end.
The traffic dataset is from CDRC at University of Leeds which is traffic data locations for the larger traffic dataset.
To achive this copy the following endpoint/API to the clipboard of your machine. If you like to understand the function, you need to learn plumber package.
#' Serve geoplumber::traffic from /api/data
#' @get /api/data
get_traffic <- function(res) {
geojson <- geojsonsf::sf_geojson(geoplumber::traffic)
res$body <- geojson
res
}Then run (re-copied into clipboard just in case):
setwd("my_app")
old_clip <- clipr::read_clip()
# adding above to clipboard
clipr::write_clip(c(
"#' Serve geoplumber::traffic from /api/data",
"#' @get /api/data",
"get_traffic <- function(res) {",
" geojson <- geojsonsf::sf_geojson(geoplumber::traffic)",
" res$body <- geojson",
" res",
"}"
))
gp_endpoint_from_clip()
clipr::write_clip(old_clip)This has now added a new endpoint at: /api/data. To consume it, we can simply run:
setwd("my_app")
gp_add_geojson("/api/data")You can now see the data by running:
Or in the following “export” function a basic leaflet map using the “headless” gp_map funciton:
# cd into a geoplumber app
setwd("my-app/")
library(geoplumber)
# view a dataset such as the `traffic` sf object bundled
t <- gp_map(geoplumber::traffic, browse_map = FALSE,
height = "320px", width = "90%")
# use includeHTML for markdown
htmltools::includeHTML(t)You can also now see the raw JSON dataset at http://localhost:8000/api/data, and on a map on a browser view the map at http://localhost:8000.
Example (3)
We would like to see default University of Leeds uni_poly grow/shrink using sf::st_buffer() function. Here is a reproducible example (please take a look at the default plumber.R file in your my_app project):
gp_create(tolower(tempdir()))
setwd(tolower(tempdir()))
gp_is_wd_geoplumber()
gp_add_slider(
min = 0.001,
max = 0.01,
step = 0.001
)
gp_change_file(
path = "src/Welcome.js",
what = '<GeoJSONComponent fetchURL={"http://localhost:8000/api/uol?grow=" + this.state.sliderInput} />
',
pattern = '<GeoJSONComponent fetchURL="http://localhost:8000/api/uol" />',
replace = TRUE,
verbose = TRUE
)Run the project (this time at tempdir() location) by:
Now you can see:
geoplumber::uni_poly grow/shrinking using sf::st_buffer function on server side.
geoplumber stack
We have worked with Shiny and plumber and we consider ourselves experienced in ReactJS, too. In order to put together a web application powered at the backend with R and React at the front-end, there is a lot of setup and boilerplate to put together. This would be also correct for other front end stack such as Angular or VueJS.
Currently geoplumber uses Facebook’s create-react-app (CRA) npm package to deal with underlying app management (including building and running) to keep you up to date with updates. geoplumber will generally provide detailed installation instructions for all required npm packages, but if not, the following are minimally required:
Front end
Once the geoplumber app my_app has been created. It will have a create-react-app directory structure with an extra R folder to hold the backend R code. The React components, as they are in CRA apps, are in the src folder and ready to be customised and developed for your own purposes. So, a React developer could run npm start on the root directory and run the built in CRA development server which is what gp_plumb_front() does too.
npm packages used
The following are included by default, the versions are just from old .Rmd file. geoplumber updates these as the package is developed. Feel free to replace it with your own .json package definer as and when.
knitr::kable(data)| package | Usage |
|---|---|
| create-react-app | main package to manage front end |
| prop-types | React propTypes |
| react | React main |
| react-dom | React DOM |
| react-bootstrap | bootstrapZ |
| leaflet | current default web mapping library |
| react-leaflet | React wrapper around leaflet above |
| react-leaflet-control | React map control |
| react-router | React router (RR) |
| react-router-dom | React dom for RR |
| react-scripts | main package to manage front end |
| react-test-renderer | test suite |
| enzyme | test suite |
| enzyme-adapter-react-16 | test suite adapter for React |
| sinon | test suite |
Showcase
An example application is deployed at www.geoplumber.com. It showcases some zone and flow data using both LeafletJS and MapboxGL both in React. The application is dockerised automating the production and deployment.
End-points
R package plumber comes with a default end-point for documenting the API using Swagger. This is also available from geoplumber’s /__swagger__/ path.
We follow a pattern of /api/ before the end-points and without for other URL’s. A new web app will have /api/helloworld and you can curl it: