Package Overview
What is rTARDIS?
rTARDIS - Terrains And Routes Directed In Spacetime - is an
R package for analysing distances and routes in spatially heterogeneous
and potentially temporally varying geographic spaces. It was initially
developed to be Google Maps for palaeobiologists, although it is
applicable in any domains where complex geographic connectivity or
temporal changes in those connections are important to the biological
question at hand.
rTARDIS uses raster datasets, which are widely available
for modern and palaeogeographic spaces, to quantify connectivity between
geographic locations. Cells in a raster are represented as nodes in a
geospatial graph, with their interconnections forming edges in that
graph, and edge weights describing the difficulty of moving between
cells. This makes rTARDIS more similar to the R package
gdistance, compared to packages like
sfnetworks, grainscape or
geonetwork which use vector representations of specific
geographic features to construct a geospatial graph instead. The
principle of the geospatial graph, however, is what underlies any
mapping and routing software, from Google Maps to ArcGIS Spatial
Analyst.
Together, what distinguishes rTARDIS within this
ecosystem of geospatial graph packages are: 1. the option for hexagonal
re-gridding to optimise spatial representation at global scales; 2.
principled connectivity schemes for fragmented geographic spaces; 3.
weighting of graph edges by factors other than geographic distance, and;
4. the capacity to link graphs through time.
Rectangular and hexagonal grids
Any rTARDIS workflow will begin with a raster or set of
rasters in longitude-latitude projection, with most operations supported
by the terra R package. Rasters are intuitive to work with
and are appropriate to use at smaller geographic scales where the
geometry of a given area is locally Euclidean (i.e., planar). They can
also be used at global scales for convenience, but incur a major bias.
As the Earth is a sphere, the assumption of Euclidean space breaks down
as raster grids cover ever greater extents of the Earth’s surface and so
a rectangular cell at the equator no longer covers the same area as a
cell closer to the poles, as shown by the plot of relative cell area
below.
rARDIS addresses the spherical domain problem by
resampling rasters to the hexagonal grid system defined by Uber’s H3
library, using the h3jsr R package. Hexagonal cells reduce
distortion of area, providing a more faithful representation of
geographic space at the poles compared to the equator. Hexagonal
sampling can even improve memory efficiency at global scales by reducing
the number of cells required to represent polar regions, although they
can also be used at smaller spatial scales too. Rectangular and
hexagonal grids have a number of commonalities and differences which
affect how rTARDIS uses them to represent locations in
geographic space, as outlined below.
For a rectangular grid, rTARDIS assumes connections
between between orthogonally and diagonally adjacent cells (variously
named king’s, 8-degree or Moore adjacency) in contrast to
orthogonal-only adjacency (a.k.a. rook’s, 4-degree or von Neumann
adjacency). By geometric necessity, orthogonal neighbours lie slightly
closer to the focal cell than diagonal neighbours. In a hexagonal grid,
each cell has six neighbours instead, all equally distant from the focal
cell, with the exception of the 12 pentagonal cells in the grid where
five equidistant neighbours are present.
Rectangular grids can take any resolution. Hexagonal grids (not just
those from H3), however, are constrained to particular resolutions
according to their degree of tessellation (resolutions 3 and 4 shown
below as an example). As such (and as with resampling of any kind),
hexagonal re-gridding approximates the original rectangular data and may
induce sampling artefacts, particularly if a coarser resolution is used.
H3 offers 15 resolution levels, with finest (15) offering ~1 metre
resolution.
A rectangular grid as defined by terra (the
SpatRaster class) consists of contiguous grid cells in
row-major order (i.e., the top left cell is cell 1, the one immediately
to its right is cell 2, and so forth). By contract, there is no clear
basis for ordering cells from H3 based on their spatial position. At
local scales the cells will form a staggered row and column structure,
but this breaks down at global scales. As such, cell order is not
spatially intuitive, although in practice this does not matter to how
rTARDIS works. Cell ordering for the two grid systems is
displayed below in dark to light colours.
Masking, linking and weighting
In some cases, we might assume that all locations in a grid should be
accessible and will become nodes in the graph. In reality, many
locations should actually be made inaccessible. For example if we are
considering the movement of a terrestrial species across the Earth, then
ocean cells should be designated inaccessible, as shown in the
bathymetry and island plots below. In this instance, an input raster can
be masked using standard terra functions so that those
cells will not be converted to graph nodes. Masking is beneficial not
just to ensure geographic realism, but also to reduce the memory size of
the resultant graph.
gdistance also permits masking of rasters. A consequence
of masking, however, is that it may produce ‘islands’ of cells
completely isolated from other parts of geographic space. In some cases,
we may wish for movement to be restricted in this way. In other cases,
however, evidence may tell us that movement across masked regions
genuinely occurred. The initial colonisation of the Pacific islands, for
example, is incontrovertible evidence that humans traversed the oceans
even though we are a terrestrial species.
rTARDIS addresses the problem of island disconnection
with functions which link isolated patches of grid cells using different
geometric principles. These links are represented as vectors using
terra’s SpatVector class and included as edges in resulting
geospatial graph, in addition to the edges between adjacent, unmasked
cells in the grid. This approach is similar to that offered by the
grainscape R package, although this package ultimately
converts patches of raster cells to single graph nodes, then determines
their linkage across masked space. See vignette Building
Landscapes for full guidance on how to construct geographic spaces
from raster data.
By default, the edges in a rTARDIS geospatial graph
correspond to the geographic distances between grid cells, as in
gdistance. These are calculated as great circle distances,
additionally adjusted for changes in elevation between cells provided
that rasters with elevation data are used for graph construction. We
may, however, expect factors other than geographic distance to control
how we move through a given geographic space. Besides rasters
representing elevation above/below sea level, one could also supply data
on properties like climate, ocean currents, or vegetation. A custom
(user-written) weighting function can then be used to change the cost of
movement through geographic space according to those alternative
properties, also like gdistance (see vignette
Geographic Distance and Re-weighting).
Geographic space through time
In some cases, we can assume that the structure of geographic space
does not change relative to the processes taking place within it. In
other cases, however, that structure may change through a variety of
different processes. Over smaller timescales, this could be something as
simple as deforestation altering the distribution of habitat space over
several decades. Over geological timescales, however, we could instead
experience massive modification of geographic space due to changes in
sea level, continental position, or climatically favourable areas.
rTARDIS accommodates these cases by taking a set of
rasters that record the same geographic space at different points in
time, converting each raster to its own geospatial graph, then layering
graphs and linking their geographically homologous locations through
time. Often, homologous locations will also remain constant with the
geographic frame of reference. Palaeobiologists, however, have to
contend with a major process which breaks this assumption - continental
drift. As such, rTARDIS can calculate how raster locations
shift between graph layers according to various plate rotation models
(see vignette Palaeogeography Quick Guide), supported by the
palaeoverse R package and gplates Web
API.
Distances and routes
Once we’ve specified the architecture and connectivity of our
geographic space, rTARDIS offers a range of functions for
measuring distances and routes within that space. Geometric structures
like isochrones, shortest paths or minimum spanning trees can be
constructed from sets of target points.
#> Linking geog [1/1]
#> Building graph
#> Checking point [1/2]Checking point [2/2]
#> Initialising graph
#> Running pathsRunning paths [1/1]
#> Summarising
Functions are mostly designed for scripting, but a few also have
wrappers to allow a user to interactively edit or query properties of a
landscape. The full range of functions offered will be covered in later
vignettes.