The Turing Geovisualisation Engine (TGVE) is a web-based, interactive visual analytics tool for geospatial data analysis, built using R and JavaScript/React, that can be used as a complete server-client application or just as a front-end stand-alone application. 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). Additionally, techniques from geographic information science (GIScience) and related domains are used to implement automatic aggregation of temporal and spatial data.
npm package
note: the older versions released under https://www.npmjs.com/package/eatlas is deprecated.
This is a React Component ES Module that can be embedded in your React applications. To install in your project:
npm install @tgve/tgvejs
# or
yarn add @tgve/tgvejs
Then, for an example to import the TGVE package and use it as the main component in a React app, see the tgve/app
repo. Following is a snippet of ReactJS from that repo:
import React from 'react';
import Tgve from '@tgve/tgvejs';
function App() {
return (
<Tgve defaultURL={process.env.REACT_APP_DEFAULT_URL}/>
);
}
Configuration settings
TGVE supports separately-provided geography (in GeoJSON or Shapefile) and point data sources (in CSV). Other formats are not supported.
The following parameters can be passed to the TGVE app. Each parameter can be passed as an environment variable, with the exception of:
- leftSidebarContent
- data
For example: REACT_APP_GEOGRAPHY_URL
or when using TGVE as a component
<Tgve geographyURL="https://geo.com">
. For more on passing variables to a React app and
the REACT_APP_
prefix please see React docs.
They can also be passed to the TGVE as URL query parameters. For instance
localhost:3000?dark=false
.
-
data
: valid geojson object. This can be a component prop value, a URL query parameter or<script id="tgve-data" type="application/json">{geojson:object}</script>
as per standardscript
tag use. If a valid GeoJSON object is provided bothdefaultURL
andgeographyURL
will be ignored, which also meansgeographyColumn
would be ignored, too. -
defaultURL
: which returns a valid geojson object whenfetched
. It can be used to fetch CSVs which is converted togeojson
by TGVE after fetching. -
geographyURL
: which returns a validgeojson
dataset. If this variable is provided, data is fetched separately along withdefaultURL
, TGVE uses thegeographyColumn
to join them. TGVE does this on initialization and whenreset
button is pressed. -
geographyColumn
: a column name which is shared between data within thedefaultURL
andgeographyURL
or a mapping between the two. If a mapping is provided it must be in this format:defaultURLColumnName:geographyURLColumnName
. This is the joining column that will result in dynamically generatinggeojson
data for TGVE to consume. If a valid column name is not provided TGVE will attempt using the first matching column between the two files. If there is none, TGVE will load the geography data without the data. -
column
: if provided, and if the geometry is of particular type which would need a column, it would be used. Defaults on to the second column as often first column is assumed to be an ID of sort. -
select
: if provided, either as a string or a JSON object, it will be passed to thetgvejs
subsetting workflow. For now, only when the application is started. The format could be one ofselect={"key1": ["val1", "val2"]}
orselect=key1:val1,val2:key2:val3,val4
. For example:https://tgve.github.io/app/?select=ranking:45
in a dataset with a column namedranking
and its value being45
. -
layerName
: if provided, and if the given name is in the list of DeckGL layers supported by TGVE, will be passed to generate the layer with the name given. -
dark
: by defaultbaseui/baseweb
is set to dark, you can change the theme to other (e.g. light) -
leftSidebarContent
: is based on React standard children. This is where users can add their own UI and more, though this requires competent React concepts. A simple use would be to pass plain text description of data/project etc. -
viewport
: TGVE’s main functionality is to auto-adjust the viewport (see DeckGL docs). However, the initial viewport can be set using this JSON parameter. The default values are:{longitude: -1.6362, latitude: 53.8321, zoom: 10, pitch: 55, bearing: 0}
. Feel free to provide as little as you like, if any of these are missing, TGVE will draw them from these default values. -
hideChartGenerator
boolean value which would hide the sidebar component which generates charts from the data. -
hideCharts
boolean value which would hide all charts. This takes priority overhideChartGenerator
parameter. -
hideSidebar
boolean value which would hide the left sidebar.
None of the above values is necessary and in the current release “Add data” button allows loading data into eAtlas.
Callbacks
The TGVE has supports these callbacks from v1.5.1:
-
onViewStateChange
: afunction
to get theviewport
of the TGVE which is passed from DeckGL. The returned object is described in DeckGL's documentations here. It contains zoom level, location information (longitude, latitude etc), current camera view (bearing and pitch) and transition details like "transitionDuration". -
onStateChange
: afunction
to get aJSON
object which contains the select (filter) state of the TGVE. As the state of the app changes the provided function is called. The returned object contains an object calledselect
which contains columns selected (filtered) with values in an array like{select:{columnName: [value1, value2]}}
In light of the above callbacks, when data is loaded in TGVE via "Add data" button from the local machine (i.e via FileReader API), the TGVE will disable other data sources until "reset" button is pressed.
Shapefiles
For more about shapefiles please refer to this Wikipedia entry. The TGVE can read shapefiles if provided as a zip file using shapefile.js
. The package is used as external dependency, therefore, if you do use it make sure you have <script src="https://unpkg.com/shpjs@latest/dist/shp.js"></script>
in your React app's index.html
file. Then, just add the source as defaultURL=www.domain/shape.zip
.
Data and settings
As stated above, you can create a script
tag to pass data and above configurations as JSON
to where TGVE is being rendered; for example in an index.html
where the component is rendered like:
<!--notice the ID names-->
<script id="tgve-data" type="application/json">{'valid':'geojson'}</script>
<script id="tgve-settings" type="application/json">{'defaultURL':'https://raw.githubusercontent.com/layik/eatlas-data/main/casualties_100.geojson','dark':'false'}</script>
External dependenices
The package relies on Plotly to be available as window.Plotly
. You can satisify this dependency by adding Plotly in your HTML build where the package is used. For instance version 2.6.3
minifed:
<script src="https://cdn.plot.ly/plotly-2.6.3.min.js"></script>
If you are not sure, please see the app
repository.
Testing
The package follows create-react-app
testing kits and uses mainly
@testing-library/react
and jest
.
Run npm run test
.
Contributing
See:
Package Status
This package is part of ongoing research at the University of Leeds, is provided “as is” and is likely to be changed without warning to meet the research needs of the University.
Funding
The project is led by Dr Nik Lomax and Dr Roger Beecham and funded by the EPSRC via The Alan Turing Institute's AI for Science and Government Programme, grant number EP/T001569/1.