In ITSLeeds/slopes: Calculate Slopes of Roads, Rivers and Trajectories

Summary

This package provides functions and example data to support research into the slope (also known as longitudinal gradient or steepness) of linear geographic entities such as roads [@ariza-lopez_dataset_2019] and rivers [@cohen_global_2018]. The package was initially developed to calculate the steepness of street segments but can be used to calculate steepness of any linear feature that can be represented as LINESTRING geometries in the 'sf' class system [@pebesma_simple_2018]. The package takes two main types of input data for slope calculation: vector geographic objects representing linear features, and raster geographic objects with elevation values (which can be downloaded using functionality in the package) representing a continuous terrain surface. Where no raster object is provided the package attempts to download elevation data using the 'ceramic' package.

Statement of need

Although there are several ways to name "slope", such as "steepness", "hilliness", "inclination", "aspect", "gradient", "declivity", the referred slopes in this package can be defined as the "longitudinal gradient" of linear geographic entities, as defined in the context of rivers by[@cohen_global_2018].

The package was initially developed to research road slopes to support evidence-based sustainable transport policies. Accounting for gradient when planning for new cycling infrastructure and road space reallocation for walking and cycling can improve outcomes, for example by helping to identify routes that avoid steep hills. The package can be used to calculate and visualise slopes of rivers and trajectories representing movement on roads of the type published as open data by @ariza-lopez_dataset_2019.

Data on slopes are useful in many fields of research, including hydrology, natural hazards (including flooding and landslide risk management), recreational and competitive sports such as cycling, hiking, and skiing. Slopes are also also important in some branches of transport and emissions modelling and ecology. A growing number of people working with geospatial data require accurate estimates of gradient, including:

Transport planning practitioners who require accurate estimates of roadway gradient for estimating energy consumption, safety and mode shift potential in hilly cities (such as Lisbon, the case study city used in the examples in the documentation).
Vehicle routing software developers, who need to build systems are sensitive to going up or down steep hills (e.g. bicycles, trains, and large trucks), such as active travel planning, logistics, and emergency services.
Natural hazard researchers and risk assessors require estimates of linear gradient to inform safety and mitigation plans associated with project on hilly terrain.
Aquatic ecologists, flooding researchers and others, who could benefit from estimates of river gradient to support modelling of storm hydrographs

There likely other domains where slopes could be useful, such as agriculture, geology, and civil engineering.

An example of the demand for data provided by the package is a map showing gradients across Sao Paulo (Brazil, see image below) that has received more than 300 'likes' on Twitter and generated conversations: https://twitter.com/DanielGuth/status/1347270685161304069

{width="50%"}

Usage and Key functions

Install the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("ropensci/slopes")

Installation for DEM downloads

If you do not already have DEM data and want to make use of the package's ability to download them using the ceramic package, install the package with suggested dependencies, as follows:

# install.packages("remotes")
remotes::install_github("ropensci/slopes", dependencies = "Suggests")

Furthermore, you will need to add a MapBox API key to be able to get DEM datasets, by signing up and registering for a key at https://account.mapbox.com/access-tokens/ and then following these steps:

usethis::edit_r_environ()
MAPBOX_API_KEY=xxxxx # replace XXX with your api key

The key functions in the package are elevation_add(), which adds a third 'Z' coordinate value for each vertex defining LINESTRING objects, and slope_xyz() which calculates slopes for each linear feature in a simple features object.

By default, the elevation of each vertex is estimated using bilinear interpolation (method = "bilinear") which calculates point height based on proximity to the centroids of surrounding cells. The value of the method argument is passed to the method argument in raster::extract() or terra::extract() depending on the class of the input raster dataset. See @kidner_what_1999 for descriptions of alternative elevation interpolation and extrapolation algorithms.