Add paper file #44

R/slopes.R

@@ -319,7 +319,7 @@ slope_xyz = function(
 #' [bilinear interpolation](https://en.wikipedia.org/wiki/Bilinear_interpolation)
 #' (`method = "bilinear"`)
 #' which calculates point height based on proximity to the centroids of
-#' surrounging cells.
+#' surrounding cells.
 #' The value of the `method` argument is passed to the `method` argument in
 #' [`raster::extract()`](https://rspatial.github.io/raster/reference/extract.html)
 #' or

paper.Rmd

@@ -1,113 +1,92 @@
 ---
-title: 'Gala: A Python package for galactic dynamics'
+title: 'slopes: An R Package to Calculate Slopes of Roads, Rivers and Trajectories'
 tags:
-  - Python
-  - astronomy
-  - dynamics
-  - galactic dynamics
-  - milky way
+  - R
+  - topography
+  - slopes
+  - gradient
+  - steepness
+  - roads
+  - elevation
 authors:
-  - name: Adrian M. Price-Whelan^[co-first author] # note this makes a footnote saying 'co-first author'
-    orcid: 0000-0003-0872-7098
-    affiliation: "1, 2" # (Multiple affiliations must be quoted)
-  - name: Author Without ORCID^[co-first author] # note this makes a footnote saying 'co-first author'
+  - name: Robin Lovelace
+    orcid: 0000-0001-5679-6536
+    affiliation: 1
+  - name: Rosa Félix
+    orcid: 0000-0002-5642-6006
     affiliation: 2
-  - name: Author with no affiliation^[corresponding author]
-    affiliation: 3
-affiliations:
- - name: Lyman Spitzer, Jr. Fellow, Princeton University
-   index: 1
- - name: Institution Name
-   index: 2
- - name: Independent Researcher
-   index: 3
-date: 13 August 2017
+date: 27 September 2021
 bibliography: paper.bib
-
-# Optional fields if submitting to a AAS journal too, see this blog post:
-# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing
-aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it.
-aas-journal: Astrophysical Journal <- The name of the AAS journal.
-output: md_document
+# We'll later convert to a Markdown Document and remove paper.Rmd:
+output: github_document
+editor_options:
+  markdown:
+    wrap: sentence
 ---
 
 # Summary
 
-The forces on stars, galaxies, and dark matter under external gravitational
-fields lead to the dynamical evolution of structures in the universe. The orbits
-of these bodies are therefore key to understanding the formation, history, and
-future state of galaxies. The field of "galactic dynamics," which aims to model
-the gravitating components of galaxies to study their structure and evolution,
-is now well-established, commonly taught, and frequently used in astronomy.
-Aside from toy problems and demonstrations, the majority of problems require
-efficient numerical tools, many of which require the same base code (e.g., for
-performing numerical orbit integration).
+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
 
-`Gala` is an Astropy-affiliated Python package for galactic dynamics. Python
-enables wrapping low-level languages (e.g., C) for speed without losing
-flexibility or ease-of-use in the user-interface. The API for `Gala` was
-designed to provide a class-based and user-friendly interface to fast (C or
-Cython-optimized) implementations of common operations such as gravitational
-potential and force evaluation, orbit integration, dynamical transformations,
-and chaos indicators for nonlinear dynamics. `Gala` also relies heavily on and
-interfaces well with the implementations of physical units and astronomical
-coordinate systems in the `Astropy` package [@astropy] (`astropy.units` and
-`astropy.coordinates`).
+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](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).
+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
 
-`Gala` was designed to be used by both astronomical researchers and by
-students in courses on gravitational dynamics or astronomy. It has already been
-used in a number of scientific publications [@Pearson:2017] and has also been
-used in graduate courses on Galactic dynamics to, e.g., provide interactive
-visualizations of textbook material [@Binney:2008]. The combination of speed,
-design, and support for Astropy functionality in `Gala` will enable exciting
-scientific explorations of forthcoming data releases from the *Gaia* mission
-[@gaia] by students and experts alike.
+There likely other domains where slopes could be useful, such as agriculture, geology, and civil engineering.
 
-# Mathematics
+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>
 
-Single dollars ($) are required for inline mathematics e.g. $f(x) = e^{\pi/x}$
+![](https://camo.githubusercontent.com/30a3b814dd72aef5b51db635f2ab6e1b6b6c57b856d239822788967a4932d655/68747470733a2f2f7062732e7477696d672e636f6d2f6d656469612f45724a32647238574d414948774d6e3f666f726d61743d6a7067266e616d653d6c61726765){width="50%"}
 
-Double dollars make self-standing equations:
+# Usage and Key functions
 
-$$\Theta(x) = \left\{\begin{array}{l}
-0\textrm{ if } x < 0\cr
-1\textrm{ else}
-\end{array}\right.$$
+Install the development version from [GitHub](https://github.com/) with:
 
-You can also use plain \LaTeX for equations
-\begin{equation}\label{eq:fourier}
-\hat f(\omega) = \int_{-\infty}^{\infty} f(x) e^{i\omega x} dx
-\end{equation}
-and refer to \autoref{eq:fourier} from text.
+```{r, eval=FALSE}
+# install.packages("remotes")
+remotes::install_github("ropensci/slopes")
+```
 
-# Citations
+### Installation for DEM downloads
 
-Citations to entries in paper.bib should be in
-[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html)
-format.
+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:
 
-If you want to cite a software repository URL (e.g. something on GitHub without a preferred
-citation) then you can do it with the example BibTeX entry below for @fidgit.
+```{r, eval=FALSE}
+# install.packages("remotes")
+remotes::install_github("ropensci/slopes", dependencies = "Suggests")
+```
 
-For a quick reference, the following citation commands can be used:
-- `@author:2001`  ->  "Author et al. (2001)"
-- `[@author:2001]` -> "(Author et al., 2001)"
-- `[@author1:2001; @author2:2001]` -> "(Author1 et al., 2001; Author2 et al., 2002)"
+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:
 
-# Figures
+```{r, eval=FALSE}
+usethis::edit_r_environ()
+MAPBOX_API_KEY=xxxxx # replace XXX with your api key
+```
 
-Figures can be included like this:
-<!-- ![Caption for example figure.\label{fig:example}](figure.png) -->
-and referenced from text using \autoref{fig:example}.
+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.
 
-Figure sizes can be customized by adding an optional second parameter:
-<!-- ![Caption for example figure.](figure.png){ width=20% } -->
+By default, the elevation of each vertex is estimated using [bilinear interpolation](https://en.wikipedia.org/wiki/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()`](https://rspatial.github.io/raster/reference/extract.html) or [`terra::extract()`](https://rspatial.github.io/terra/reference/extract.html) depending on the class of the input raster dataset.
+See @kidner_what_1999 for descriptions of alternative elevation interpolation and extrapolation algorithms.
 
-# Acknowledgements
+<!-- # Calculating slopes on regional transport networks -->
 
-We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong
-Oh, and support from Kathryn Johnston during the genesis of this project.
+<!-- # Acknowledgements -->
 
 # References

paper.bib

@@ -1,59 +1,70 @@
-@article{Pearson:2017,
-  	url = {http://adsabs.harvard.edu/abs/2017arXiv170304627P},
-  	Archiveprefix = {arXiv},
-  	Author = {{Pearson}, S. and {Price-Whelan}, A.~M. and {Johnston}, K.~V.},
-  	Eprint = {1703.04627},
-  	Journal = {ArXiv e-prints},
-  	Keywords = {Astrophysics - Astrophysics of Galaxies},
-  	Month = mar,
-  	Title = {{Gaps in Globular Cluster Streams: Pal 5 and the Galactic Bar}},
-  	Year = 2017
+
+@article{ariza-lopez_dataset_2019,
+  title = {Dataset of Three-Dimensional Traces of Roads},
+  author = {{Ariza-L{\'o}pez}, Francisco Javier and {Mozas-Calvache}, Antonio Tom{\'a}s and {Ure{\~n}a-C{\'a}mara}, Manuel Antonio and de la Vega, Paula Gil},
+  year = {2019},
+  month = aug,
+  volume = {6},
+  pages = {1--10},
+  publisher = {{Nature Publishing Group}},
+  issn = {2052-4463},
+  doi = {10.1038/s41597-019-0147-x},
+  abstract = {Design Type(s)   time series design \textbullet{} repeated measure design \textbullet{} data collection and processing objective \textbullet{} modeling and simulation objective    Measurement Type(s)   position    Technology Type(s)   GPS navigation system    Factor Type(s)     Sample Characteristic(s)   Province of Jaen \textbullet{} road            Machine-accessible metadata file describing the reported data (ISA-Tab format)},
+  copyright = {2019 The Author(s)},
+  journal = {Scientific Data},
+  language = {en},
+  note = {ZSCC: 0000001},
+  number = {1}
 }
 
-@book{Binney:2008,
-  	url = {http://adsabs.harvard.edu/abs/2008gady.book.....B},
-  	Author = {{Binney}, J. and {Tremaine}, S.},
-  	Booktitle = {Galactic Dynamics: Second Edition, by James Binney and Scott Tremaine.~ISBN 978-0-691-13026-2 (HB).~Published by Princeton University Press, Princeton, NJ USA, 2008.},
-  	Publisher = {Princeton University Press},
-  	Title = {{Galactic Dynamics: Second Edition}},
-  	Year = 2008
+@article{cohen_global_2018,
+  title = {Global River Slope: {{A}} New Geospatial Dataset and Global-Scale Analysis},
+  shorttitle = {Global River Slope},
+  author = {Cohen, Sagy and Wan, Tong and Islam, Md Tazmul and Syvitski, J. P. M.},
+  year = {2018},
+  month = aug,
+  volume = {563},
+  pages = {1057--1067},
+  issn = {0022-1694},
+  doi = {10.1016/j.jhydrol.2018.06.066},
+  abstract = {A rivers' longitudinal gradient (i.e. slope) is a key parameter in fluvial hydrology, hydraulics, and geomorphology. It affects a multitude of fluvial variables such as flow velocity and sediment transport. Limitations in river slope data, both its availability and accuracy, constrain the fidelity of fluvial modeling, particularly at larger or global scales. Traditional slope calculation algorithms cannot accurately predict river slopes as these are based on cell-by-cell calculation, which is only suitable for hillslopes and small mountainous streams. This paper presents a methodology for calculating global river slope and a procedure to upscale it for relatively coarse resolution, suitable for global scale modeling. The methodology is based on a simple principle of calculating slope from elevation depression over the length of a river segment, which is automated to allow global scale calculations. Version 1.0 of the Global River-Slope (GloRS) geospatial dataset is introduced and shown to be a step improvement over a previous product (NHDplus for the contiguous United States) and compares favorably to observed slope data collected from the literature. Statistical analysis of Earth's continents and large basins highlights interesting spatial trends. A semi-empirical regression analysis between basin-average river slope and other basin-scale parameters show that terrain slope accounts for 67\% of the variability in basin-average river slope, with average discharge, sediment load and basin temperature contributing additional improvements to global predictions of 3\%, 4\%, and 3\%, respectively.},
+  journal = {Journal of Hydrology},
+  keywords = {GIS,Global,Rivers,Slope},
+  language = {en},
+  note = {ZSCC: 0000005}
 }
 
-@article{gaia,
-    author = {{Gaia Collaboration}},
-    title = "{The Gaia mission}",
-    journal = {Astronomy and Astrophysics},
-    archivePrefix = "arXiv",
-    eprint = {1609.04153},
-    primaryClass = "astro-ph.IM",
-    keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes},
-    year = 2016,
-    month = nov,
-    volume = 595,
-    doi = {10.1051/0004-6361/201629272},
-    url = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G},
+@article{zeileis_colorspace_2019,
+  title = {Colorspace: {{A}} Toolbox for Manipulating and Assessing Colors and Palettes},
+  shorttitle = {Colorspace},
+  author = {Zeileis, Achim and Fisher, Jason C. and Hornik, Kurt and Ihaka, Ross and McWhite, Claire D. and Murrell, Paul and Stauffer, Reto and Wilke, Claus O.},
+  year = {2019},
+  journal = {arXiv preprint arXiv:1903.06490},
+  note = {ZSCC: 0000004}
 }
 
-@article{astropy,
-    author = {{Astropy Collaboration}},
-    title = "{Astropy: A community Python package for astronomy}",
-    journal = {Astronomy and Astrophysics},
-    archivePrefix = "arXiv",
-    eprint = {1307.6212},
-    primaryClass = "astro-ph.IM",
-    keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools},
-    year = 2013,
-    month = oct,
-    volume = 558,
-    doi = {10.1051/0004-6361/201322068},
-    url = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A}
+
+
+@article{pebesma_simple_2018,
+	title = {Simple Features for R: Standardized Support for Spatial Vector Data},
+	author = {Pebesma, Edzer},
+	year = {2018},
+	date = {2018},
+	journal = {The R Journal},
+	url = {https://journal.r-project.org/archive/2018/RJ-2018-009/index.html},
+	note = {Citation Key Alias: sf2018
+Citation Key: pebesma{\_}simple{\_}2018},
+	langid = {en}
 }
 
-@misc{fidgit,
-  author = {A. M. Smith and K. Thaney and M. Hahnel},
-  title = {Fidgit: An ungodly union of GitHub and Figshare},
-  year = {2020},
-  publisher = {GitHub},
-  journal = {GitHub repository},
-  url = {https://github.com/arfon/fidgit}
+@inproceedings{kidner_what_1999,
+	title = {GeoComputation},
+	author = {Kidner, David and Dorey, Mark and Smith, Derek},
+	year = {1999},
+	date = {1999},
+	publisher = {www.geocomputation.org},
+	volume = {99},
+	url = {http://www.geocomputation.org/1999/082/gc_082.htm},
+	note = {Citation Key: kidner{\_}what{\_}1999},
+	address = {Mary Washington College Fredericksburg, Virginia, USA}
 }