Package 'traveltime'

Calculate travel time

Description

Calculate the travel time from a set of points over a friction surface.

Usage

calculate_travel_time(
  friction_surface,
  points,
  filename = NULL,
  overwrite = FALSE
)

Arguments

friction_surface	A SpatRaster friction surface layer with in resistance units. See Details.
points	A two-column matrix, data.frame, (including tibble types) with longitude (x) in the first column and latitude (y) in the second, or a SpatVector, in the same coordinate reference system as friction_surface. Points that fall outside friction_surface are dropped with a warning; if none fall within it, an error is raised.
filename	character. Output file name with extension suitable for terra::writeRaster. If NULL (default), output will be returned in memory
overwrite	logical. If TRUE filename is overwritten.

Details

Implements methods from Weiss et al. 2018, 2020 to calculate travel time from given locations over a friction surface.

Over large areas this function can require significant RAM and will be slow.

Pre-prepared walking or motorised friction surfaces can be obtained with?get_friction_surface. User can also provide their own friction surface. This surface but must be in resistance units (1/conductance), e.g. minutes/meter. See Van Etten 2017.

Note on this implementation: as of package version 1. Earlier versions of this package used the raster and gdistance packages. These dependencies have been removed and now instead rely exclusively on terra for spatial data handling. The two approaches use the same cost model (eight-direction movement, edge cost distance * mean(friction)) and produce effectively the same result. terra::costDist() computes true geodesic inter-cell distances, so the new approach is more accurate than the old gdistance's distance approximation away from the equator (the results are identical at the equator and for projected coordinate systems). The remaining difference is a boundary convention at the origins: gdistance includes half of the starting cell's own friction when leaving a point, whereas terra::costDist measures cost to the border of the origin cells and omits it. This appears as a small, near-constant offset (about half a cell of friction) close to the origin points. See data-raw/costdist_migration_comparison.md in the package source for the full comparison.

Citations:

D. J. Weiss, A. Nelson, C. A. Vargas-Ruiz, K. Gligoric, S., Bavadekar, E. Gabrilovich, A. Bertozzi-Villa, J. Rozier, H. S. Gibson, T., Shekel, C. Kamath, A. Lieber, K. Schulman, Y. Shao, V. Qarkaxhija, A. K. Nandi, S. H. Keddie, S. Rumisha, P. Amratia, R. Arambepola, E. G. Chestnutt, J. J. Millar, T. L. Symons, E. Cameron, K. E. Battle, S. Bhatt, and P. W. Gething. Global maps of travel time to healthcare facilities. (2020) Nature Medicine. https://doi.org/10.1038/s41591-020-1059-1

D. J. Weiss, A. Nelson, H.S. Gibson, W. Temperley, S. Peedell, A. Lieber, M. Hancher, E. Poyart, S. Belchior, N. Fullman, B. Mappin, U. Dalrymple, J. Rozier, T.C.D. Lucas, R.E. Howes, L.S. Tusting, S.Y. Kang, E. Cameron, D. Bisanzio, K.E. Battle, S. Bhatt, and P.W. Gething. A global map of travel time to cities to assess inequalities in accessibility in 2015. (2018). Nature. https://doi:10.1038/nature25181

van Etten, J. (2017). R package gdistance: Distances and routes on geographical grids. Journal of Statistical Software https://doi.org/10.18637/jss.v076.i13

Value

SpatRaster

Examples

ext <- matrix(
  data = c("111", "0", "112", 1),
  nrow = 2,
  ncol = 2,
  dimnames = list(
    c("x", "y"),
    c("min", "max")
   )
 )

 friction_surface <- get_friction_surface(
   surface = "motor2020",
   extent = ext
 )

 from_here <- data.frame(
   x = c(111.2, 111.9),
   y = c(0.2, 0.35)
 )

 calculate_travel_time(
  friction_surface = friction_surface,
  points = from_here
 )

---

Extent from SpatRaster or SpatVector

Description

Formats spatial extent for use in get_friction_surface.

Usage

ext_from_terra(r)

Arguments

r	terra::SpatRaster or terra::SpatVector

Value

2x2 matrix

Examples

library(terra)
r <- terra::rast(
    extent = terra::ext(c(111, 112, 0, 1))
  )

ext_from_terra(r)

---

Convert extent to matrix

Description

This function allows get_friction_surface() to accept the argument extent as a vector, 2x2 matrix, SpatVector, or SpatRaster and extracts and converts into the annoyingly specific format necessary to download the friction surface. See details in ?get_friction_surface

Usage

ext_matrix(extent)

Arguments

extent

vector of length 4, 2x2 matrix, SpatExtent, SpatVector, or SpatRaster

Value

2x2 matrix with column names "x" and "y" and row names "min" and "max"

Examples

# vector/double
x <- c(111, 112, 0, 1)
ext_matrix(x)

# SpatExtent
y <-  terra::ext(x)
ext_matrix(y)

# SpatRaster
r <- terra::rast(extent = y)
ext_matrix(r)

# SpatVector
v <- terra::vect(y)
ext_matrix(v)

---

Extent vector to matrix

Description

Extent vector to matrix

Usage

ext_vect_to_matrix(x)

Arguments

x	numeric length 4, consisting of c(xmin, xmax, ymin, ymax) dimensions of extent

Value

2x2 matrix

Examples

ext_vect_to_matrix(c(111,112,0, 1))

---

Get friction surface

Description

Wrapper function to download friction surfaces via malariaAtlas::getRaster().

Usage

get_friction_surface(
  surface = c("motor2020", "walk2020"),
  filename = NULL,
  overwrite = FALSE,
  extent = NULL
)

Arguments

surface	"motor2020" or ⁠"walk2020⁠.
filename	character. File name for output layer.
overwrite	Overwrite filename if exists
extent	Spatial extent as one of: a numeric vector specifying c(xmin, xmax, ymin, ymax), a terra SpatExtent, SpatVector, or SpatRaster from which the extent will be taken, or or 2x2 matrix See details

Details

Convenience wrapper to malariaAtlas::getRaster() to access motorised and walking travel friction layers per Weiss et al. 2020, that adds safety to check existing files before download. Surfaces can be downloaded directly from: https://malariaatlas.org/project-resources/accessibility-to-healthcare/.

Here —

• surface = "motor2020" will download "Explorer__2020_motorized_friction_surface", and

• surface = "walk2020" will download "Explorer__2020_walking_only_friction_surface".

D. J. Weiss, A. Nelson, C. A. Vargas-Ruiz, K. Gligoric, S., Bavadekar, E. Gabrilovich, A. Bertozzi-Villa, J. Rozier, H. S. Gibson, T., Shekel, C. Kamath, A. Lieber, K. Schulman, Y. Shao, V. Qarkaxhija, A. K. Nandi, S. H. Keddie, S. Rumisha, P. Amratia, R. Arambepola, E. G. Chestnutt, J. J. Millar, T. L. Symons, E. Cameron, K. E. Battle, S. Bhatt, and P. W. Gething. Global maps of travel time to healthcare facilities. (2020) Nature Medicine. https://doi.org/10.1038/s41591-020-1059-1

extent is formatted and then passed through to malariaAtlas::getRaster() as a 2x2 matrix. It is converted into a matrix using ext_matrix. The matrix format used is as returned by sf::st_bbox() — the first column has the minimum, the second the maximum values; rows 1 & 2 represent the x & y dimensions respectively: matrix(c("xmin", "ymin", "xmax", "ymax"), nrow = 2, ncol = 2, dimnames = list(c("x", "y"), c("min", "max"))). NULL extent downloads (large) global layer.

Troubleshooting: if you get a warning ⁠Failed to connect to MAP geoserver⁠, this is an issue with fetching the friction surface using malariaAtlas::getRaster, and not an issue with traveltime itself. The server may be down or there may be an issue with that package.

Value

SpatRaster

Examples

# for more examples of passing exten types see ?ext_matrix

ext <- c(111, 112, 0, 1)

 get_friction_surface(
   surface = "motor2020",
   extent = ext
 )

---

Singapore MRT and LRT data

Description

Locations of all MRT and LRT station exits in Singapore.

Usage

stations

Format

stations A data frame with 563 rows and 2 columns:

x

longitude

y

latitude

Source

Land Transport Authority. (2019). LTA MRT Station Exit (GEOJSON) (2024) Dataset. data.gov.sg. Retrieved December 10, 2024 from https://data.gov.sg/datasets/d_b39d3a0871985372d7e1637193335da5/view

---