-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME.Rmd
134 lines (95 loc) · 6.68 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# slopes package
<!-- badges: start -->
[](https://github.com/ropensci/slopes/actions)
[](https://codecov.io/gh/ropensci/slopes?branch=master)
[](https://github.com/ropensci/software-review/issues/420)
<!-- badges: end -->
The **slopes** R package calculates the slope (longitudinal steepness, also known as gradient) of roads, rivers and other linear (simple) features, based on two main inputs:
- [vector](https://geocompr.robinlovelace.net/spatial-class.html#vector-data) linestring geometries defined by classes in the [`sf`](https://r-spatial.github.io/sf/) package
- [raster](https://geocompr.robinlovelace.net/spatial-class.html#raster-data) objects with pixel values reporting average height, commonly known as digital elevation model (**DEM**) datasets, defined by classes in the [`raster`](https://cran.r-project.org/package=raster) or more recent [`terra`](https://rspatial.org/terra) packages
Data on slopes are useful in many fields of research, including [hydrology](https://en.wikipedia.org/wiki/Stream_gradient), natural hazards (including [flooding](https://www.humanitarianresponse.info/fr/operations/afghanistan/infographic/afg-river-gradient-and-flood-hazard) and [landslide risk management](https://assets.publishing.service.gov.uk/media/57a08d0740f0b652dd0016f4/R7815-ADD017_col.pdf)), recreational and competitive sports such as [cycling](http://theclimbingcyclist.com/gradients-and-cycling-an-introduction/), [hiking](https://trailism.com/trail-grades/), and [skiing](https://www.snowplaza.co.uk/blog/16682-skiing-steeps-what-does-gradient-mean-ski-piste/).
Slopes are also also important in some branches of [transport and emissions modelling](https://www.sciencedirect.com/science/article/pii/S2352146516302642) and [ecology](https://doi.org/10.1016/j.ncon.2016.10.001).
See the [`intro-to-slopes` vignette](https://ropensci.github.io/slopes/articles/intro-to-slopes.html) for details on fields using slope data and the need for this package.
This README covers installation and basic usage. For more information about slopes and how to use the package to calculate them, see the [get started](https://ropensci.github.io/slopes/) and the [introducion to slopes](https://ropensci.github.io/intro-to-slopes/) vignette.
## How it works
The package takes two main types of input data for slope calculation:
- vector geographic objects representing **linear features**, and
- **elevation values** from a digital elevation model representing a continuous terrain surface or which can be downloaded using functionality in the package
The package can be used with two sources of elevation data:
- openly available elevation data via an interface to the [ceramic package](https://github.com/hypertidy/ceramic), enabling estimation of hilliness for routes anywhere worldwide even when local elevation data is lacking. The package takes geographic lines objects and returns elevation data per vertex (providing the output as a 3D point geometry in the sf package by default) and per line feature (providing average gradient by default).
- an elevation model, available on your machine.
## Getting started
### Installation
<!-- You can install the released version of slopes from [CRAN](https://CRAN.R-project.org) with: -->
<!-- ``` r -->
<!-- install.packages("slopes") -->
<!-- ``` -->
Install the development version from [GitHub](https://github.com/) with:
```{r, eval=FALSE}
# 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:
```{r, eval=FALSE}
# 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:
```{r, eval=FALSE}
usethis::edit_r_environ()
MAPBOX_API_KEY=xxxxx # replace XXX with your api key
```
## Basic examples
Load the package in the usual way. We will also load the `sf` library:
```{r message=FALSE, warning=FALSE}
library(slopes)
library(sf)
```
The minimum input data requirement for using the package is an `sf` object containing LINESTRING geometries, as illustrated below (requires a MapBox API key):
```{r}
sf_linestring = lisbon_route # import or load a linestring object
```
```{r, eval=FALSE}
sf_linestring_xyz = elevation_add(sf_linestring) # dem = NULL
#> Loading required namespace: ceramic
#> Preparing to download: 12 tiles at zoom = 12 from
#> https://api.mapbox.com/v4/mapbox.terrain-rgb/
```
```{r, echo=FALSE}
# note: the following should be TRUE
# identical(sf_linestring_xyz, lisbon_route_xyz_mapbox)
sf_linestring_xyz = lisbon_route_xyz_mapbox
```
With the default argument `dem = NULL`, the function downloads the necessary elevation information from Mapbox.
You can also this use a local digital elevation model (`dem = ...`), as shown in the example below:
```{r}
sf_linestring_xyz_local = elevation_add(sf_linestring, dem = dem_lisbon_raster)
```
In both cases you can obtain the average gradient of the linestring with `slope_xyz()` and plot the elevation profile with `plot_slope()` as follows:
```{r elevationprofile}
slope_xyz(sf_linestring_xyz_local)
plot_slope(sf_linestring_xyz_local)
```
_See more functions in [Get started](https://ropensci.github.io/slopes/articles/slopes.html) vignette._
## See more in vignettes
- [Get started](https://ropensci.github.io/slopes/articles/slopes.html)
- [An introduction to slopes](https://ropensci.github.io/slopes/articles/intro-to-slopes.html)
- [Reproducible example: gradients of a road network for a given city](https://ropensci.github.io/slopes/articles/roadnetworkcycling.html)
- [Verification of slopes](https://ropensci.github.io/slopes/articles/verification.html)
- [Benchmarking slopes calculation](https://ropensci.github.io/slopes/articles/benchmark.html)
## Code of Conduct
Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/).
By contributing to this project, you agree to abide by its terms.