Usage

Install tgver from cran using:

install.packages("devtools")

You can also get the latest development from GitHub using devtools

devtools::install_github("tgve/tgver")

The package comes with the latest version of TGVE and should give you the version used in the package:

tgver::version
#> version 
#> "1.5.0"

That means, there is no need to do anything to run a clean instance of the TGVE ready to import data to using:

tgver::tgve_server()

The application can be served from a plumber instance which is pointed at the location of the TGVE instance initialized, or directly opening the HTML file in browsers. This also means we can embed the application in an Rmd file, using either of the two methods, when building the Rmd (thanks to knitr):

# open a static tgve
# tgver::tgve()
#
# or start a tgve instance before embedding it
# tgver::tgve_server()
# knitr::include_url("http://127.0.0.1:8000")
# or use the public one
knitr::include_url("https://tgve.github.io/app/")

The above instance pulls the instance and the data from a GitHub repository, which means it should load every time the Rmd output is viewed (provided it is a html_vignette). Thanks to the knitr::include_url function, it is safe to build within R packages offline, with the downside of the standard browser no connection error displayed. A good cause for embedding an instance of the TGVE in this R package would be the case of being offline/mobile.

On your local machine, and given the Rmarkdown output is set to rmarkdown::html_vignette, then you could do:

# setup a local instance
# tempdir() will disappear inside an Rmd
p = "~/Downloads"
tgver::setup(p)
# now the instance is at
tp = file.path(p, "tgve")
# we just need to pass the data/csv URL
# using `defaultURL` API
url = tgver::get_url(file.path(tp, "index.html"), defaultURL = 'https://raw.githubusercontent.com/tgve/example-data/main/utlas.geojson',
                   column = "long",
                   hideChartGenerator="true",
                   # In future R should assemble the json
                   viewport="{zoom:5.5,pitch:0,bearing:0}")
# now we have the app's main url
knitr::include_url(url)
# unlink(tp, recursive = TRUE)

If this Vignette is served either from CRAN or GitHub, the application at path in above chunk (tp) will not be available. So you must run it locally to see the application, the screenshot below was taken from such a run. Embedding the full instance in a HTML file is an open issue on the repository and we welcome your contributions if you can.

Also, please note that the “webview” within Rstudio Deb package version 1.4.1717 could fail to load even remote URLs using knitr::include_url, please click the “open in browser” to see the rendering from knitr.

Main functions

The package still has “WIP” label on, so we are still finalizing the main functionality of the package. However, as of (January 2022) it looks like to work with the TGVE, we need: (1) Setup function(s) and (2) Run functions.

The package does have a function called setup which does what it says on the help; it sets up an instance at a given directory. The second type of functions, so far, there are few functions that can be used but the main one is tgve which sets up and builds a static and “empty” instance at a tempdir. The similar function called tgve_server does exactly the same but serves the instance from a local server using plumber APIs.

Current important functions are:

1. explore_fs: OGC standard Simple Features and R package sf is an important class object to support. Though we will do all we can to not import sf due to underlying system dependencies.
2. explore_file: this makes sense given the API and functionality built into the TGVE and given that data scientists would want to quickly explore single files.
3. explore_dir: this is an ambitious function to develop. Current version tries to find two files and pass them to TGVE’s defaultURL and geographyURL as that is a use case of the TGVE.

Remote instance

The simplest way to use the TGVE is using an instance running at a local/remote server, using the URL “query parameter” based API variables provided. Therefore, we can simply run an instance such as the app instance as follows without doing anything else:

# tgve = "https://tgve.github.io/app/?"
# defaultURL = "https://raw.githubusercontent.com/tgve/example-data/main/casualties_100.geojson"
# url = paste0(tgve, "defaultURL=", defaultURL)
# knitr::include_url(url)
# or simply
knitr::include_url("https://tgve.github.io/app/?defaultURL=https://raw.githubusercontent.com/tgve/example-data/main/casualties_100.geojson&layerName=heatmap")

We grab the remote instance, but instead of its internal values, the URL parameters takes precedence. That means the value given as defaultURL is parsed by the TGVE. We can as easily use this in R’s built in “view” or “browse” commands, too.