JOSS review: example, tests, minor issues

[ConnorDonegan]

I'm having some trouble running the vignette code and want to raise some suggestions. I write these in the spirit of the JOSS review process being interactive, and giving feedback while completing the review rather than only after. Two items from the review criteria that require attention are

• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?

Getting to the download_boundaries function in the tutorial I get:

mainPath <- getwd()
initiate_project(mainPath) # 167; 2
country <- "Switzerland"     
> download_boundaries(mainPath,
+                     country,
+                     adminLevel = 2,
+                     type = "gbAuthoritative",
+                     alwaysDownload = TRUE)
+ Requested data not available. Searching for available data, please wait...
              Type Level Availability
1           gbOpen     0          YES
2           gbOpen     1          YES
3           gbOpen     2          YES
4           gbOpen     3          YES
5   gbHumanitarian     0           NO
6   gbHumanitarian     1           NO
7   gbHumanitarian     2           NO
8   gbHumanitarian     3           NO
9  gbAuthoritative     0           NO
10 gbAuthoritative     1           NO
11 gbAuthoritative     2           NO
12 gbAuthoritative     3           NO
Run the download_boundaries function again with valid parameters.

I understand that it might be advantageous to have a vignette with code that doesn't need to run because the external data sources you're querying can change and are outside of the control of the project. However, I think new users (including me) would really benefit from having a single example that moves from initiate_project to opening the data in AccessMod, particularly a simple one. Something of that nature will ne needed to meet the JOSS expectation for "examples of how to use the software."

I like that the tutorial has some thorough discussion of each function, but it would be helpful if example code were accessible from the help pages, e.g., ?download_boundaries. Currently the help pages don't have any example code. Having example code will also provide some protection against errors getting introduced with revisions to the code.

I see that the Processed input compiling section is related to this issue of moving between inAccessMod and AccessMod, but it doesn't really stand out for that purpose (that is, a user may not be able to find it very quickly if that's what they were looking for) and I think new users would appreciate a bit more support getting to that point.

Some minor items I'd like to suggest:

• add instructions to the README file so users know how to obtain the vignette: vignette("Tutorial", package = "inAccessMod") and/or a link to an online version
  • spell out acronyms when they first appear, namely HeRAMS data (in the tutorial)---I don't know what that is and a (non-google) web search turned up a bunch of furniture on the first page of results.
  • are there any tutorials for AccessMod that could be linked to from this tutorial? For example, if you have the user/learner create a simple file using inAccessMod, and they run compile_processed_data, where do they go next? How do they pick up again at the right spot using AccessMod?

https://github.com/openjournals/joss-reviews/issues/5879

[ptimoner]

Dear @ConnorDonegan ,

Thanks a lot for your time in reviewing my package and for all your suggestions. I followed all of them as I believed they could really improve the support to the user.

• I modified the vignette, and it is now possible to move from "initiate_project" (first step) to "compile_processed_data" (last step) just following the Tutorial, using the same example project across the different functions.
• I added example codes to the help pages.
• I added example data within the package for the additional functions (multi_ts and hf_best_cov), the ones that can be run outside the main pipeline, and that can be useful for AccessMod users. This way, the user can test the functions even they don't have their own inputs.
• I added the instructions to the README file so users know how to obtain the vignette.
• I spelled out HeRAMS in the Tutorial.
• I added the link to AccessMod page (where there is all the information for its installation and use), in both the README file and the Tutorial.

I hope these changes meet your expectations, and the package is now more user-friendly.

Thank you again for your valuable insights,

Best regards,

Pablo

https://github.com/openjournals/joss-reviews/issues/5879

[ConnorDonegan]

Thanks Pablo, I look forward to working through the new material (within the coming week or two).

[ConnorDonegan]

I was able to move through the tutorial, download landcover, roads, facilities, boundaries, and population raster, and open them all up in QGIS to verify that the files are what I would expect. I think the changes to the tutorial go a long way towards helping users get started. I'm going to close this one then and continue the discussion on the main review page https://github.com/openjournals/joss-reviews/issues/5879

Thanks