Open temospena opened 3 years ago
Image for new vignette
This is a great map but it adds ~13 MB to the package size as it's embedded in the html of the vignette. Plan: add link to interactive version.
Perfect, that is a much better idea!
Should I put it on branch rev2-fix?
On Sun, Jun 13, 2021 at 9:03 PM Robin @.***> wrote:
This is a great map but it adds ~13 MB to the package size as it's embedded in the html of the vignette. Plan: add link to interactive version.
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/ITSLeeds/slopes/issues/32#issuecomment-860263025, or unsubscribe https://github.com/notifications/unsubscribe-auth/AJKLUXXXZLLCFKNHNYR4SSLTSUFJDANCNFSM46TUJCSA .
Just saw that you already did that on https://github.com/ITSLeeds/slopes/commit/1942e94f9f7c75948004ef9cf225e2e8911792ea :)
On Sun, Jun 13, 2021 at 9:44 PM rosa @.***> wrote:
Perfect, that is a much better idea!
Should I put it on branch rev2-fix?
On Sun, Jun 13, 2021 at 9:03 PM Robin @.***> wrote:
This is a great map but it adds ~13 MB to the package size as it's embedded in the html of the vignette. Plan: add link to interactive version.
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/ITSLeeds/slopes/issues/32#issuecomment-860263025, or unsubscribe https://github.com/notifications/unsubscribe-auth/AJKLUXXXZLLCFKNHNYR4SSLTSUFJDANCNFSM46TUJCSA .
Draft reply to Andy's review: above. Draft reply to Dan's review, below...
Package Review
Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide
* **Briefly describe any working relationship you have (had) with the package authors.** I shared an office with Robin Lovelace some years ago and we're still in touch. * ☒ As the reviewer I confirm that there are no [conflicts of interest](https://devguide.ropensci.org/policies.html#coi) for me to review this work (If you are unsure whether you are in conflict, please speak to your editor _before_ starting your review).
Documentation
The package includes all the following forms of documentation:
* ☐ **A statement of need** clearly stating problems the software is designed to solve and its target audience in README * ☒ **Installation instructions:** for the development version of package and any non-standard dependencies in README * ☒ **Vignette(s)** demonstrating major functionality that runs successfully locally * ☒ **Function Documentation:** for all exported functions * [half an x] **Examples** (that run successfully locally) for all exported functions * ☐ **Community guidelines** including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with `URL`, `BugReports` and `Maintainer` (which may be autogenerated via `Authors@R`).
Functionality
* ☒ **Installation:** Installation succeeds as documented. * ☒ **Functionality:** Any functional claims of the software been confirmed. * ☒ **Performance:** Any performance claims of the software been confirmed. * ☒ **Automated tests:** Unit tests cover essential functions of the package and a reasonable range of inputs and conditions. All tests pass on the local machine. * ☐ **Packaging guidelines**: The package conforms to the rOpenSci packaging guidelines
Estimated hours spent reviewing: 6-8
* ☒ Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer (“rev” role) in the package DESCRIPTION file.
Review Comments
Thanks for the invite to peer review. This is a generally awesome package that works well and is professionally assembled. I’m a reasonably competent R programmer but not an expert in package construction or testing, so apologies for any issues with my review.
Tested on a windows machine - runs well.
Comments on the above tickboxes first:
* Statement of need: does state the problem it solves but not the target audience (the ‘getting started’ article at https://itsleeds.github.io/slopes/articles/slopes.html states the need in a little more detail; the intro to that could go at the top of the readme?)
We have greatly improved the documentation and there is now a statement of need in the README, with a link for people wanting further details. See https://github.com/ITSLeeds/slopes/commit/7c2ac573129ef728ec17565d2307b5d198ca77b9
* Couldn’t find community guidelines though URL / bug reports are in DESCRIPTION * Performance: benchmarks are slower for me but my machine’s quite old * Automated tests are present though I don’t feel qualified to confirm they all pass * Conforming to rOpenSci packaging guidelines: no CodeMeta file; function and argument naming is all great; package API excellent; code style is compact but great; readme is great, though it does use an example that requires a mapbox API auth key and this isn’t mentioned - more on that below.
Other comments
Only a couple of comments:
* The package README includes an example that automatically downloads raster tiles from Mapbox (a fantastically useful feature by the way). (`{r eval = F} lisbon_route_3d_auto = slope_3d(r = lisbon_route)`). However, it doesn’t say that you need a Mapbox API key for it to work. Might be worth adding that, or just a link? (Possibly with a `{r eval = F} usethis::edit_r_environ()` line to show how to add the key?) It’s such a super-useful part of the package, I think it’s worth making sure people know how to use it. * The benchmarking test in the README downloads a dem_lisbon.tif file for one of the tests. That file wouldn’t work in either terra or raster for me - and anyway, if we’re comparing the two methods, I’m not sure why it can’t just use the already-available dem_lisbon_raster twice? (That’s how I ran the benchmark.)
We have updated the benchmark, which is now in a separate vignette, and which no longer requires data download, good point!
There are a couple of things I feel might be missing, possibly from the README intro or maybe something for the https://itsleeds.github.io/slopes/index.html page:
* Perhaps a little example of how to make your own route to use in the package. It’s quick enough that it wouldn’t bloat the README intro. Or could go in main documentation? E.g. using stplanr:
library(stplanr) library(osrm) #Trip between two Sheffield parks #Coords nabbed from right-click in google maps trip <- route( from = c(-1.493284835376672,53.39216628908168), to = c(-1.5066026758341629,53.368424563832754), route_fun = osrmRoute, returnclass = "sf" ) #> Most common output is sf mapview::mapview(trip) #Is linestring so can be used in slopes class(trip$geometry[1]) #Find slope of route... (using mapbox API) sheffield_route_3d_auto = slopes::slope_3d(r = trip) slopes::plot_slope(sheffield_route_3d_auto)
* It’s a slopes package, not an elevation package, but I wonder if it might be worth mentioning how to find elevation changes? Or provide a simple way to see elevation change summaries for particular slopes? I can imagine that being useful for e.g. assessing hilliness of bike journeys. Excuse my ignorance if this is already in the package - I couldn’t get the distance elevation profile example from ‘getting started’ to work for my Sheffield route above (though in theory I should be able to as sf::st_coordinates gives me the 3D matrix?) I could find some values like this:
library(tidyverse) n = sf::st_coordinates(sheffield_route_3d_auto) %>% data.frame %>% mutate(elevationchange = Z-lag(Z))#change in elevation between line segments #Total net elevation of trip sum(n$elevationchange, na.rm = T) #Total climb of trip sum(n$elevationchange[n$elevationchange > 0], na.rm = T)
Would it be possible to provide a similar example that ties to the distance elevation profile example? Again, sorry - I did try using slope package functions to achieve this and failed.
We have updated the documentation, could you clarify it you can reproduce it now? Does the updated information in Get Started helps?
The README has be substantially updated and now documents the package's main functions: https://github.com/ITSLeeds/slopes/commit/dbacab8792dfc178c37b3ceb5aafd9791f515061
More detailed responses in-line
Draft response to review 2:
[x] Installation instructions
[x] Vignette(s)
We have made substantial improvements to the vignettes. There is now an updated introductory
slopes.Rmd
vignette that demonstrates all key function and a shorter README that links to the other vignettes. The more theoretical introduction to slopes has been moved into a new vignette,intro-to-slopes
. See here for details: https://github.com/ITSLeeds/slopes/pull/38Function Documentation
This has been done in https://github.com/ITSLeeds/slopes/commit/018d2d60d0d8065d9d5865c98752b34cd14806bf. Many thanks for the tip.
[x]
@return
sections[x]
\value{...}
sections have been added to the .Rd files using#' @return
in the source code thanks toroxygen2
. See commit https://github.com/ITSLeeds/slopes/commit/7a8cdc519828aae10ca7d4d4bf3e20a2ca11683f[x] Datasets
This is a good point, we put the dataset docs together in a rush. They have been iteratively improved, including in this commit: 45068459072a8602985e22e5d7730d24122a1cdd
Thanks for the comment. We agree that the argument names were at times overly terse and we now find ourselves wishing we spent more time thinking about this earlier on. The good news is that, after some initial issues, we have now got updated and consolidated argument names, as documented here: https://github.com/ITSLeeds/slopes/pull/31/files. To summarise that we now have:
@param routes Routes, the gradients of which are to be calculated.
replacingr
@param dem Raster overlapping with
routesand values representing elevations
replacinge
@param elevations Elevations in same units as x (assumed to be metres)
also replacinge
We also updated arg names in the plotting functions in https://github.com/ITSLeeds/slopes/commit/7651276edab847dd0ce27d33ed182669ae3b28a9
elevation_get()
The documentation of this function has been improved, as can be seen in https://itsleeds.github.io/slopes/reference/elevation_get.html. Specifically, we link to long form documentation explaining how to get an API key, rather than duplicating content in the function documentation. We also link explicitly to the
cc_elevation()
page for people who want more details. Note: we do not see this functionality, that is reliant on potentially temperamental web APIs, as core to the package so we do not want to emphasise this aspect of the package, believing that it's better if users get and understand their own DEM data using other tools, in line with the Linux philosophy of modularity. See https://github.com/ITSLeeds/slopes/commit/7a67e2db3caeccf42c693067076ce224cbaf2de1 for details on updated links to the ceramic package.elevation_extract()
documentationThe documentation has been improved as a result of this comment. See https://github.com/ITSLeeds/slopes/commit/18b0a5dbd7626b0b05029bfcd298bde38fd16796 for details.
One question for the reviewers: should this function even be exported? It seems of little additional use compared with the original
extract()
functions for users but we thought it worth asking and minimising changes. If nothing else the documentation is now more interesting!plot_dz
@param
tags have been shifted up into the exported functionplot_slope()
. All parameters are now better documented, with improved names (legend_position
instead ofx
, for example) and default values.ifelse
statement. The parameter is still set with a default but now thatcolorspace
is imported it is guaranteed to work.plot_slope()
argumentsThe parameter name has been clarified and renamed:
plot_slope()
changesAgreed, the
plot_slope()
function is the one that people will use and it was confusing having bothplot_slope()
and the more esoteric helper functionplot_dz
exported. Onlyplot_slope()
is now exported and the documentation is better. Also, the colourscheme has been updated so 0 corresponds with white, which was not previously the case.sequential_dist()
The description of the input
m
has been updated and now provides this important information:Note: this change also benefits the
slope_matrix()
functions. See https://github.com/ITSLeeds/slopes/commit/7637f45fe1d9f2d18d3cfdd7362f000ce3c5edb6 for details.elevation_add()
) - this is now described in README and in Get Started vignette. d9c40cac95ca8e106ed578daf85edc1a4f450fe4?slope_vector
Agreed, this has been fixed in https://github.com/ITSLeeds/slopes/commit/bcd382adaa8bd230b47a6ca8bce9286f937e961d
slope_matrix_mean()
This function has been added: https://itsleeds.github.io/slopes/reference/slope_matrix.html
slope_xyz
Good point. This, plus other improvement to the docs for this function, have been made in https://github.com/ITSLeeds/slopes/commit/cb0e2e56127f6dedd83744e8b515581b373d4abd - wondering if the function should ever have been exported but it's there now and think it could be useful for others. Especially now it's better documented!
We call
sf
and tend to avoid the::
in the examples, although believe it is useful in some places in the package, e.g. to concisely to demonstrate that a function is from a particular package. See https://github.com/ITSLeeds/slopes/commit/e854cb4c7d6e0d701e7170d4b05749bef3a137b4 for details.We think that the use of simple interger values in the examples supports understanding by allowing people to see how they work from first principles, without needing to think of long lon/lat values. The examples in the vignettes, and the examples in the functions that do the 'heavy lifting' that are most commonly used by users, have real world examples. We would be happy to improve any specific examples that are not clearly explained. Overall, we have improved the documentation but we would welcome any further guidance on examples that should be improved.
This is a good point that would also cause issues for the CRAN submission. Addressed in https://github.com/ITSLeeds/slopes/commit/fe5f12da7250f99b08921bd7cf90928a497242c2
route_cyclestreets
docsThis has been fixed, as can be seen here: https://itsleeds.github.io/slopes/reference/cyclestreets_route.html
dem_lisbon_raster
exampleFixed in https://github.com/ITSLeeds/slopes/commit/f21d4a99c6b80791a11ab750612bc9c61c732002
slope_raster()
exampleThis has been fixed in https://github.com/ITSLeeds/slopes/commit/4c7e2077d8fe271ed08804e66b6daecb606311ab
We have added new tests for the
directed
edge cases and the 'stop` functions. We think improved function behaviour should catch more user mistakes but welcome any further feedback on improving the tests further.We agree with the comments. The package now imports
geodist
,colorspace
andpbapply
. There is now description of installing the packages and API token needed for downloading DEMs in the README after https://github.com/ITSLeeds/slopes/commit/327d5f4d83949b8e2eb6adaaadd5d80ee4a891ce. We have added a codemeta file. Function and argument names, and docs, have been improved thanks to the review process.We have removed the commented code, experiments from early versions of the package code. The codebase should be easier to read now.
We have not yet added caching. We think think could represent 'mission creep'. We have, however, added a link to a description of caching tiles in the
ceramic
package in https://github.com/ITSLeeds/slopes/commit/3d324fea1d2daa6204be8cb66b3bbe0256897dc3We have removed the unused
file
argument, simplifying the function: https://github.com/ITSLeeds/slopes/commit/66de731cf3bfcc4c516622b2d2ddacf2fcfcc4daThis is a good point. Fix documented in https://github.com/ITSLeeds/slopes/issues/36
pbapply
importsAgreed and fixed. We were being overly averse to importing packages, to the point where it was increasing code complexity. Good news: switching this to Imports saved 6 lines of condition checking code: https://github.com/ITSLeeds/slopes/pull/31/commits/eb434d558cc7bc51bdf088466e668062efb51d6e
elevation_extract()
suggestionSee https://github.com/ITSLeeds/slopes/commit/b153e6a27a2d9aa4cc375daf4531df05eb2ffdae thanks for the suggestion
na.rm = TRUE
for z_min() and z_max().sf
vssfc
/sfg
objectsFor some functions such as
slope_xyz()
andslope_raster()
passing geometry objects toroutes
seems to work already, we have updated the docs accordingly.We found a case where passing an
sfc
object can cause issues, as illustrated in the reprex below from a previous version:Created on 2021-09-04 by the reprex package (v2.0.1)
This wasted resources because it downloaded the tiles while the user could have saved time by knowing that it was going to fail due to the class early. We think that requiring
sf
inputs is reasonable given the package's aim of being a high level tool for adding slope variables tosf
data frames that already have attributes.We tried the following:
But it seemed to add complexity for little benefit. However, we have added more safety checks in a cases where
sfc
were found to fail. Happy to further iterate on this if there are other functions that don't work as expected with sfc objects but we expect and encourage most users to use sf objects as inputs, unless there are benefits of catering for and documentingsfc
use cases that we have not considered https://github.com/ITSLeeds/slopes/commit/a3bfcec419c940a3a1369de9ebccfbb3f3c78e3fTrue that, hadn't noticed all that duplication, sloppy coding! Fixed in https://github.com/ITSLeeds/slopes/commit/fbe5740b936e1480dace8b10b3b1ffb7894cf700
colorspace
added to importsplot_slope()
argument passingGood point. See fix in https://github.com/ITSLeeds/slopes/commit/9d7bdddc410c1f0fdd21fc40ef786c3ff35b9e12
elevation_get()
Agreed, this was due to issues with
raster
reprojection code and newwkt
CRS definitions. New approach withterra
resolves this issue, as shown in https://github.com/ITSLeeds/slopes/commit/4476a381ff7150fa7d2ad8fcd5d3eb6f39dd47aeslope_3d
(nowslope_xyz()
) code duplicationWe agree that there was unnecessary duplicated code. We acted on this by removing redundant code, removing one of the conditions completely: https://github.com/ITSLeeds/slopes/commit/6ba560d8956c2ebe979a59223e4275a6a5190b4c
The function, now called elevation add, still has plenty of complexity and could probably be simplified further but, after attempting to do so were not sure how best to progress considering that additional helper functions also create complexity and lines of code, we could not find a way to add helper functions here that would lead to substantial improvements:
Agreed, see comments above re argument names, we have now renamed
r
ande
toroutes
,dem
andelevations
to reflect the different meanings ofe
and for clarity.The first argument of
plot_slope()
is nowroute_xyz
, reflecting the fact the function takes a single route with 'xyz' coordinates https://github.com/ITSLeeds/slopes/pull/35/commits/f9de5ccc70730c837325fcfd49ef84c705c5cbb1Agreed, this would be interesting. We have added a new vignette at https://itsleeds.github.io/slopes/articles/roadnetworkcycling.html that shows the importance of route breakpoints.