---
title: "Introducing tgver"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introducing tgver}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# What is TGVE?
The Turing Geovisualisation Engine (TGVE) is a web-based, interactive visual analytics tool for geospatial data analysis, built using R & React. The visual views and interaction mechanisms designed into the tool is underpinned by empirically-informed guidelines around visualization design and techniques from Geographic Information Science (GIScience).

# tgver R package
The package's main aims are outlined in the README on the package's GitHub space. As the package grows, these aims may also grow and expand as we research better ways of interactive geospatial data analysis and visualization.

## Usage
As the package is not on CRAN yet, get it from GitHub using `devtools`
```{r install, eval=FALSE}
devtools::install_github("tgve/tgver")
```

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

```{r version}
tgver::version
```

That means, there is no need to do anything to run a clean instance of the TGVE ready to import data to using:
```{r tgve, eval=FALSE}
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`):
```{r embed, out.width="100%"}
# 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:

```{r build, eval=FALSE}
# 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`.

```{r buildoffline, echo=FALSE, out.width="100%"}
if(!curl::has_internet()) {
  warning("Rmd was rendered with no connection!")
} else {
  knitr::include_graphics("https://user-images.githubusercontent.com/408568/142702067-003e98d8-a0a0-4e23-85ad-b875434da518.png")
}
```

## 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.
3. `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`](https://tgve.github.io/app/) instance as follows without doing anything else:

```{r, out.width="100%"}
# 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.
